10.3. Scope of Top-Level Entities

A top-level entity is visible in the scope where it is defined, and at all deeper levels nested in that scope subsequent to where it is defined.

Let's take, for example, a script property. The script property x here, declared at the top level of the script as a whole, is also in scope inside a script object and a handler:

property x : 10
script myScript
    display dialog x
end script
on myHandler( )
    display dialog x
end myHandler
run myScript -- 10
myHandler( ) -- 10

If a top-level entity is in scope in a script object, a script object nested at a deeper level may declare a top-level entity with the same name. This deeper name will overshadow the first entity's name within that deeper scope. Thus in this example there is never the slightest ambiguity as to what is meant by x at any point:

property x : 5
script scriptOne
    property x : 10
    script scriptTwo
        property x : 20
        display dialog x
    end script
    display dialog x
    run scriptTwo
end script
script scriptThree
    property x : 30
    display dialog x
end script
script scriptFour
    display dialog x
end script
display dialog x -- 5
run scriptOne -- 10, 20
run scriptThree -- 30
run scriptFour -- 5

Regions of scope outside a script object cannot see that script object's top-level entities. But if they can see a name referring to that script object, they can ask to access that script's top-level entities, as explained in "Top-Level Entities" in Chapter 8. In the same way, a region of scope at a deeper level can access an overshadowed name:

script scriptOne
    property x : 10
    script inner
        property x : 20
        display dialog scriptOne's x -- 10
    end script
end script
script scriptTwo
    display dialog scriptOne's x -- 10
    display dialog x -- error: The variable x is not defined
end script
run scriptOne's inner
run scriptTwo

In that example, scriptOne is a top-level entity of the top-level script (that's where it's defined). For that reason (and because the name scriptOne is not overshadowed), script inner, which is nested two levels down within the top-level script, can see scriptOne. The name x is overshadowed within inner, so inner cannot see scriptOne's property x. But because it can see scriptOne, it can ask scriptOne for access to it. For the same reason, code inside scriptTwo can see scriptOne. It is outside scriptOne, so it can't see scriptOne's property x. But since it can see scriptOne, it can ask scriptOne for access to it.

A curious fact is that a top-level entity is visible at its own level to code even before it is defined. That's because the initialization takes place during compilation, before any code runs. So, for example, a script object:

run myScript -- Howdy
script myScript
    display dialog "Howdy"
end script

A handler:

myHandler( ) -- Howdy
on myHandler( )
    display dialog "Howdy"
end myHandler

And even a property:

display dialog x -- Howdy
property x : "Howdy"

This sort of thing, however, especially with a property, is generally regarded as confusing and poor style. Also, code at a deeper nested level can see a higher-level entity only after that entity has been defined. This doesn't work:

run myScript
script myScript
    display dialog myOtherScript's x -- error: The variable myOtherScript is not defined
end script
script myOtherScript
    property x : "Howdy"
end script

A handler appears to be an exception, but it isn't really:

run myScript
script myScript
    myHandler( )
end script
on myHandler( )
    display dialog "Howdy"
end myHandler

That worked, but not because code inside myScript can see myHandler. It can't see itmyHandler is not in scope herebut it can call it! That's because of the rules of message-passing, which have nothing to do with the rules of scope. (See "Inheritance" in Chapter 8.) The handler call myHandler( ) in myScript reaches myHandler at the top level because the top level is myScript's parent. To show that code inside myScript can't see myHandler, consider the same script without the parentheses after myHandler, so that the code is not calling myHandler but merely mentioning it:

run myScript
script myScript
    myHandler -- error: The variable myHandler is not defined
end script
on myHandler( )
    display dialog "Howdy"
end myHandler

Note that a script object defined not at the top level of a script object (or script) is not a top-level entity. Basically, it's an implicit local (see "Scope of Undeclared Variables," later in this chapter), which means that such a definition must precede any reference to itself, and that it can't be seen outside the scope where it is defined. Interestingly, when you define a script object at the top level of a handler, the rule about the definition preceding a reference to itself is enforced by the compiler (with a mysterious error message):

on myHandler( )
    run myScript
    script myScript -- compile-time error: The myScript property is specified more
than once 

        display dialog "Howdy"
    end script
end myHandler
myHandler( )