4.8 Dictionary

A scriptable application defines a repertory of Apple events to which it is prepared to respond, and to be scriptable with AppleScript, it must publish information about this repertory, so that when a script targeting the application is compiled or decompiled, the AppleScript scripting component can confirm that the English-like words of its code really are defined by the application, and can translate between those English-like words and the Apple event structures that will actually be used when communicating with that application as the script runs. Such publication is performed through a dictionary. Not just scriptable applications must have a dictionary; scripting additions must have one too. And AppleScript itself has a dictionary (displayed in Appendix A).

Physically, a dictionary may take one of two forms:

• In Mac OS 9, and optionally on Mac OS X (typically under Carbon), a dictionary is a resource of type 'aete'. The format of an 'aete' resource ('aete' stands for Apple Event Terminology Extension) is formally defined in:

  /System/Library/Frameworks/ApplicationServices.framework/Versions/A/ Frameworks/AE.framework/Versions/A/Headers/AEUserTermTypes.h

  and is documented at http://developer.apple.com/documentation/mac/IAC/IAC-308.html.

• In a Cocoa application, a dictionary is a set of XML (property list) text files inside the application's package, with file extensions .scriptSuite and .scriptTerminology. For the .scriptSuite and .scriptTerminology file formats, see:

  http://developer.apple.com/documentation/Cocoa/Conceptual/Scriptability/Tasks/SuiteDefs.html

  A new XML format, the .sdef file, is currently under development; it will represent within a single file all the information in both a .scriptSuite file and a .scriptTerminology file. You can learn more about it from the sdef manpages.

A dictionary may be published statically or dynamically. It is published statically if AppleScript can read the dictionary right off the disk; it can do this with an 'aete' resource. It is published dynamically if AppleScript must ask the running application for its dictionary (which it does by sending the application an Apple event, of course). A Cocoa application implements scriptability by publishing its dictionary dynamically, because AppleScript can't read the .scriptSuite and .scriptTerminology files directly. An advantage of the dynamic approach to dictionary publication is that the dictionary may be dynamically constructed—that is, the application can actually vary its own dictionary in response to particular circumstances. A disadvantage is that the application must be running in order for AppleScript to acquire its dictionary (and so it must be launched merely in order for AppleScript to compile or decompile a script that targets it).

A dictionary contains two kinds of information:

Machine-readable information

The dictionary describes its repertory of Apple events in a manner intended primarily for the AppleScript scripting component, and not for a human user, since the whole idea of AppleScript is to shield the user from having to gaze upon raw Apple events. Still, you're allowed to look at it, and this can be useful if you need to know what's going on behind the scenes when you talk to a particular application. An easy way to get a look at this part of the dictionary is to use Script Debugger, which provides an option to show a dictionary in terms of Apple events.

Human-readable information

The part of the dictionary specifically intended for human eyes lists the actual English-like words you may use when targeting the application, along with comments that can contain additional information about what these words do and how you are to use them. The comments are intended for human beings only, but the listing of English-like terminology is also used by AppleScript when compiling or decompiling, to translate between English-like words and Apple events.

A raw dictionary, in and of itself, is not intended to be particularly readable by a human being. Under Mac OS 9 and before, in fact, it can be quite a chore to inspect a raw dictionary; the best way is to use a dedicated 'aete' resource editor. A very good free one is Gary McGath's EightyRez (http://www.panix.com/~gmcgath/EightyRez.html). A Cocoa application's dictionary is just text, and can be studied with the Property List Editor (included with the Developer Tools) or with any word processor. For example, take a look in /System/Library/Frameworks/Foundation.framework/Resources at NSCoreSuite.scriptSuite and NSCoreSuite.scriptTerminology. You might not understand everything you're seeing, but you'll get a fair idea of what goes on in a dictionary.

Usually, the way you look at a dictionary is through some utility that knows how to parse it and present it in a human-readable fashion. A dedicated script editor is an example of such a utility. That's because when you're writing a script you are likely to want to study the dictionary of the application you're targeting, so that you know what to say to it; indeed, it may be said that nine-tenths of the art of programming with AppleScript is figuring out what a targeted application expects and permits you to say to it (as we saw in Chapter 3). You might think that this would be no art at all, since there's the dictionary giving you this information straight out. But it turns out that a dictionary is a remarkably poor device for communicating to a human user the information that is really needed. A dictionary can be well or badly written, and in any case it doesn't really tell you how much of the AppleScript language the application implements, how well it implements it, and (most important) how you're supposed to combine the vocabulary listed in the dictionary into expressions that will cause the application to do what you want. A great many trees will have to die so that we can mull over the implications of this difficulty in Chapter 19.