11.1 References as Incantations

One very productive way to think of a reference is as an incantation. It's like frozen speech. It encapsulates a bit of phraseology, a particular utterance. If a variable's value is a reference, that value is something you can use to access the object it refers to. What I mean by "use" is "say": a reference is an encapsulation of the words you would have to utter (in your code, of course) in order to access the object. In a way, a reference is like a miniature package of suspended evaluation; it's a little phrase that isn't evaluated until you use it. When you do use it, it works just as if you'd said the phrase at that point in your code.

For example, consider this code:

tell application "Finder"
        set x to (get folder 1)
        display dialog (get name of x) -- Mannie
end tell

The dialog shows the name of the folder. Why does this work? As we have said, x is this reference:

folder "Mannie" of desktop of application "Finder"

This means that using x is like using those words. Therefore, when you say this:

get name of x

it's just like saying this:

get name of folder "Mannie" of desktop of application "Finder"

A reference answers the "What would I have to say...?" question. What would I have to say in order to speak of the Finder's folder 1? The Finder tells us one answer; I could say this:

folder "Mannie" of desktop of application "Finder"

You may be disconcerted at first by that fact that this is not what you did say. You said folder 1, referring to the folder by index number; the Finder said folder "Mannie", referring to it by name. You didn't say of desktop; the Finder did. You shouldn't worry about this. You just have to have faith, when an application gives you a reference, that this reference will access the thing you asked for access to.

11.1.1 Pre-Resolution of Terminology

When the time comes to use a reference, you don't have to be in the context of a tell. The reference is not only a complete target, it's a complete target whose vocabulary has already been resolved according to the context in which the reference was originally formed.

As a result, this works:

tell application "Finder"
        set x to (get folder 1)
end tell
name of x -- "Mannie"

(We looked a little at this phenomenon in Chapter 10; now we are in a position to discuss it properly.) How can this be? Look at just the last line of that code, in isolation:

name of x

That line contains no folder; it contains no Finder! But that line causes a message to be sent to the Finder asking for the name of a particular folder. The entire target:

folder "Mannie" of desktop of application "Finder"

is frozen into x. So the effect of the last line of that code is exactly—I mean exactly—as if you had said this:

tell application "Finder"
        get name of folder "Mannie" of desktop
end tell

The whole incantation involving the folder, the desktop, and the Finder is effectively frozen into x, ready to use. The terms folder and desktop have already been resolved, just as they would be in the context of a tell block targeting the Finder—because they were frozen into x in just such a context.

11.1.2 Being Careful with References

Keep in mind that a reference is full of hidden power. You can send an Apple event without realizing it, merely by using a reference. It's easy to be lulled into thinking you'll always know when you're sending an Apple event to a target application, because you'll see the chain of ofs and tells culminating in the name of the application. But with a reference, you won't see any of that; the whole chain is hidden inside the reference.

The Event Log in the script editor application can be a big help here, because it tracks Apple events. When you execute this code:

tell application "Finder"
        set x to (get folder 1)
end tell
name of x -- "Mannie"

the event log says this:

tell application "Finder"
        get folder 1
        get name of folder "Mannie" of desktop
end tell

That makes it very clear what's happening.

Another thing to bear in mind is that a reference is mere words, not a magic pointer. Consider the following:

tell application "Finder"
        set x to folder 1
        display dialog (get name of x) -- Mannie
        set name of x to "Moe"
        display dialog (get name of x) -- error!
end tell

The reason for the error is perfectly clear if you imagine a reference as an incantation. What's x during the first display dialog command? It's this:

folder "Mannie" of desktop of application "Finder"

And that's what it is during the second display dialog command, too; the incantation doesn't change. But at that point there is no folder "Mannie"—because we just changed the name of that folder to "Moe"! Our reference no longer works, because the incantation no longer speaks of the thing we want to speak of. The speech is frozen, while the world has changed.