Section 8.5. Top-Level Entities

8.5. Top-Level Entities

A script object's top-level entities are variables defined at the top level of the script object having the special feature that even though they belong to the script object, and even though the rules of scope protect them from being visible to code outside the script object, they can be accessed (retrieved and assigned to) by code outside the script object. A top-level entity is either a script property, a handler, or a script object.

8.5.1. Accessing Top-Level Entities

The most important fact about a script object's top-level entities is that even though they are not directly visible to code outside the script object, they are accessible on demand to any code that can see the script object. This means that they can be both retrieved and assigned to (fetched and set) by such code.

A special way of talking is required for doing this. Because a script object's top-level entities are not visible outside the script object, it is necessary, in effect, to ask the script object politely to yield access to a top-level entity (and the script object always politely complies). We say that to access a script object's top-level entities, you must target that script object. The syntax for doing this comes in two forms:

• Use the of operator (or the 's operator) to specify the top-level entity in relation to its script object. For example:

   script myScript     property x : "Howdy"     on sayHowdy( )         display dialog x     end sayHowdy     script innerScript         display dialog x     end script end script set x of myScript to "Hello" myScript's sayHowdy( ) -- Hello run innerScript of myScript -- Hello

  
  

• Alternatively, refer to the top-level entity within a tell block addressed to the script object. This requires the use of the keyword its, except in the case of a handler call. For example:

   script myScript     property x : "Howdy"     on sayHowdy( )         display dialog x     end sayHowdy     script innerScript         display dialog x     end script end script tell myScript     set its x to "Hello"     sayHowdy( ) -- Hello     run its innerScript -- Hello end tell

  
  

In the second form, the keyword its (explained more fully in Chapter 11) is required to specify that we mean myScript's top-level entities and not some other variables. If you omit its from the line where you set x, you actually set a different x (an implicit global, as we'll see in Chapter 10), not the property of myScript. If you omit its from the line where you run innerScript, there is a runtime error, because no defined variable called innerScript is visible here.

(It makes no difference whether the keyword its appears before the call to sayHowdy. This special treatment of handler calls will be discussed in "Handler Calls, Commands, and Script Objects," later in this chapter.)

8.5.2. Persistence of Top-Level Entities

Another remarkable feature of a top-level entity of a script object is that it is persistent, meaning that its value survives the execution of the script. If a top-level entity's value is changed during the execution of a script, then if you execute the script again, the top-level entity will have this new value at the outset, as long as you haven't done something to reinitialize it.

So, for example:

 script myScript     property x : 5 end script tell myScript     set its x to (its x) + 1 end tell display dialog myScript's x 

In a script editor application, run that code. A dialog appears saying 6. Now, for dramatic effect, without closing the script window or making any other change, walk away and do something else, such as get a cup of coffee. Now run the code again. The dialog says 7!

A script as a whole is a script object, so we can demonstrate the very same thing much more simply with a property of the script as a whole:

 property x : 5 set x to x + 1 display dialog x 

The first time you run this, the dialog says 6. Then when you run it again, the dialog says 7.

This amazing behavior is possible because AppleScript has a memory (see "Maintenance of State" in Chapter 3). Your compiled script is in AppleScript's memory. After the script is executed, AppleScript retains the compiled script, and along with it, the values of all its top-level entities. A script property is a top-level entity. So after the first execution of the script, AppleScript is remembering that the script has a property x and that its value is 6. Thus when you run the script a second time and x is incremented again, it becomes 7.

Now, at this point, you are saying: "But wait! I can see x being initialized to 5 right there in the script. So what about that line? Are you saying that, the second time the script is executed, AppleScript is ignoring that line?" Well, it's really just a matter of what initialize means. It means to give a value to something that has no value. The second time the script is executed, x has a value already, remembered from the previous execution. So the initialization has no effect, because x doesn't need initializing.

Now let's go back to the previous code, with the script object myScript. What AppleScript is remembering between executions is the script as a whole. So what persists is the top-level entities of the script as a whole. But myScript is a script object defined at the top level, so it is a top-level entity of the script as a whole. Therefore it persists, and therefore its top-level entities persist. That's why that example works.

Generalizing, this means we can nest a script object in a script object in a script object to any depth we like, and as long as each script object is defined at the top level of its containing script object and the top script object is defined at the top level of the script as a whole, the properties of even the deepest script object in the nesting will persist between executions.

Here's an example two levels deep:

 script outerScript     script innerScript         property x : 5         on increment( )             set x to x + 1         end increment     end script     tell innerScript to increment( )     display dialog innerScript's x end script run outerScript -- 6, then 7, and so forth 

Here's an even more dramatic example, where one script object value is replaced wholesale with another:

 script myScript     script myInnerScript         display dialog "Hello"     end script     run myInnerScript end script script myNastyScript     display dialog "Get lost" end script run myScript set myScript's myInnerScript to myNastyScript 

That code displays Hello the first time, but then it displays Get lost every time after that. The reason is that after the first time, myInnerScript has been replaced by myNastyScript, and this new version of myInnerScript persists.

8.5.2.1. What reinitializes top-level entities

Nothing lives forever, so just how long does all this persistence persist? Well, for one thing, it all comes to an end if you edit the script. That's because altering the script means that the entire script must be recompiled, and at that point the contents of the old compiled script, along with the values of the top-level entities from the previous execution, are thrown away from AppleScript's memory. So, compiling reinitializes top-level entities. (That's why throughout this section I've been telling you to execute the script multiple times without doing anything else. If you so much as type a space in the script window, the script's persistence goes away.)

Another thing that reinitializes top-level entities is generating the script object anew in code. To see what I mean, consider this code:

 repeat 3 times     script s         property x : 1         display dialog x         set x to x + 1     end script     run s end repeat 

There is a loop that repeats three times, and each time we see x being incremented.But what about afterwards? Do you think the value of x will persist after it increments three times? (Think about it before reading on.)

Ha ha, it was a trick question! The value of x will never even increment in the first place. Well, it increments, but then it is reinitialized. That code does not display 1 and then 2 and then 3; it displays 1 and then 1 and then 1. Why? Because each time through the loop, the entire script object definition happens again. So the variable s is defined anew, with a new script object. And each time, this new script object's top-level entities are initialized afresh. The script object s is not defined at the top level of a script object; it is not itself a top-level entity. Thus, no persistence.

Similarly, when a script object is defined within a handler, it has no persistence. The script object is created anew each time the handler runs. This is true even in a script object's explicit run handler. This code illustrates that a script object in an explicit run handler does not have persistent top-level entities:

 script myScript     on run         script myInnerScript             property x : 10         end script         tell myInnerScript             set its x to (its x) + 1             display dialog its x         end tell     end run end script run myScript -- 11 

That code yields 11 every time it runs. As I said in "Code and the Run Handler" in Chapter 6, only stuff in the implicit run handler is at the top level. An explicit run handler is an ordinary handler, and stuff inside it follows the rules for being inside a handler. So myInnerScript is not defined at the top level of a script object; it is not a top-level entity, and has no persistence.

8.5.2.2. File-level persistence

So far we've talked about persistence only while a script window remains open for editing in a script editor application. But what about when a script is saved as a compiled script file and its window is closed? Does persistence work when the script file is opened for editing again later? And does persistence work when a saved compiled script file is repeatedly executed by a script runner?

The answer, unfortunately, is: it depends. Persistence doesn't work if you save, close, and open a script file using the current Script Editor. When you run the newly opened script, you find that everything is reinitialized. On the other hand, such persistence does work with older versions of the Script Editor (1.9 or before), or with Script Debugger. Create and run this script several times in Script Debugger:

 property x : 5 set x to x + 1 display dialog x 

Now save the script as a compiled script file, and quit, just to prove to yourself that AppleScript's own memory of the value of x is well and truly erased. Now open the compiled script file again (in Script Debugger) and execute it. The incrementing of x picks up right where it left off previously.

It would be really nice if persistence always worked in a compiled script file, but unfortunately this mechanism is not automatic, and in fact has nothing to do with AppleScript itself. AppleScript has no way to enforce file-level persistence, because AppleScript doesn't deal with files. It is up to the environment that's talking to the AppleScript scripting component, after it asks AppleScript to run a compiled script file, to save AppleScript's copy of the compiled script back into the compiled script file after execution. If it doesn't do this, then the compiled script file won't contain the new values, and the values won't persist. Script Editor and Script Debugger behave differently in this regard.

Similarly, script runners and other environments that execute compiled script files can behave differently. Some environments do save the compiled script file back to disk after each execution along with any changed top-level entities. For example, applets do this. So does Apple's Script Menu, and so does BBEdit with its Script menu. But Entourage's Script menu, for example, does not.

Actually, persistence in Apple's Script Menu (and perhaps some other environments) is itself inconsistently implemented. It turns out that the Script Menu implements persistence only if execution of the script returns a value (even though this value is otherwise ignored). Some actions, such as the user canceling out of a dialog, can cause the script to return with no value, and in that case, persistence fails. You can guarantee persistence in this situation by trickery, making sure that the script returns a value no matter what. In the case of display dialog you can catch the error produced by the user canceling and return a value anyway:

 property x : 5 set x to x + 1 try     display dialog x on error     return 0 end try 

All this inconsistency can be troublesome. You can't depend on file-level persistence; you must test each intended environment to see whether (and how) it works there. In the next section, I'll describe a mechanism for implementing file-level persistence from within a script, in such a way that it is guaranteed to work.