3.9. Dictionary

AppleScript is a little language. It is also an extensible language. The purpose of AppleScript is to communicate with scriptable applications by means of Apple events; each such application can extend the terminology of the language in its own way, defining a repertory of Apple events to which it is prepared to respond, along with the English-like AppleScript terms to which these Apple events and their various parts correspond. To be scriptable with AppleScript, the application must publish information about this repertory. The mechanism by which this publication takes place is a resource called a dictionary.

The AppleScript scripting component uses the dictionary when compiling and decompiling a script, for two purposes:

• To confirm, at compile time, that the English-like terms used by the AppleScript programmer are legal

• To translate, at compile time and at decompile time, between English-like terms and Apple event structures

Not only does a scriptable application have a dictionary; a scripting addition does too, and for the very same reasons. (In fact, AppleScript itself has a dictionary.)

3.9.1. Dictionary Formats

A dictionary may be expressed in any of three formats :

The 'aete ' resource

The 'aete' resource is present in scriptable applications in Mac OS 9 and before, and in Carbon applications in Mac OS X (and optionally in Cocoa applications as well). For information about its format, see:

http://developer.apple.com/documentation/mac/IAC/IAC-308.html

In Xcode, to see a header file defining some relevant constants, choose File Open Quickly and enter AEUserTermTypes.h.

An 'aete' resource may be static or dynamic . AppleScript can read a static 'aete' resource directly off the disk; but it has to ask the application for a dynamic 'aete' resource (which it does by sending the application an Apple event, of course), which means that the application must be running in order for its 'aete' resource to be read. The advantage of the dynamic approach is that the dictionary can be constructed in real time, in response to current circumstances.

The scriptSuite and scriptTerminology files

This pair of files are an innovation of Cocoa Scripting, a technology intended to allow a developer to write a scriptable application in Cocoa fairly easily. They are XML (property list) files with extensions .scriptSuite and .scriptTerminology. For information about their format, see:

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

These files are not directly usable by AppleScript. Rather, the Cocoa engine translates them into a dynamic 'aete' resource when the application launches. Because of this, a Cocoa application that uses these files to implement its scriptability must be running in order for AppleScript to consult its dictionary; this is why certain applications are launched when you compile a script that targets them. For this reason, and because Cocoa's rendering of these files can result in a "substandard" 'aete' resource (Apple's word, not mine), some Cocoa applications include a static 'aete' resource as well.

The sdef file

An sdef (pronouned "ess-deaf") is an XML file expressing dictionary information. It was invented as part of Panther (Mac OS X 10.3); there, however, it could not be used directly as a dictionary. Instead, it was merely a convenient way to construct a dictionary; the sdef file had then to be translated into either or both of the other two formats by way of a provided tool called sdp .

On Tiger, things are greatly improved. First, the sdef specification has been changed in such a way as to allow it to express aspects of a dictionary that were impossible with the earlier sdef type, or even with an 'aete' resource. Second, a Cocoa application's sdef can be read directly by AppleScript. Thus, on Tiger, an sdef is a better dictionarybetter than a dictionary has ever been before. The downside is that a Cocoa application that expresses its dictionary solely through a new-format sdef is scriptable only on Tiger. For more information, type man sdef in the Terminal. Chapter 27 contains an example of how to make a Cocoa application scriptable using an sdef.

3.9.2. Dictionary Troubles

A scriptable application's dictionary is exposed in human-readable form in a script editor application (see Figure 2-2). 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. 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. There are three main problems:

• Because each scriptable application defines its own terminology, learning to script a new application sometimes feels like having to learn an entirely new version of the AppleScript language.

• The dictionary is inadequate to express what the programmer needs to know in order to script the application successfully. Some of this inadequacy is due to poorly written dictionaries. Some of it is due to the inherent structure of all dictionaries, just as a mere list of vocabulary is insufficient for learning a human language. Some of it is due to the way dictionaries are displayed in a script editor application. (This is one reason to use Script Debugger, which supplies a superior dictionary view.)

• At any given point in a script, up to four sets of vocabulary are in force: the target application's dictionary, the dictionaries of all loaded scripting additions, AppleScript's own dictionary, and any other terms created and used by the programmer in the course of the script. These namespaces are not readily distinguished, and collide in confusing and frustrating ways.

For a vivid demonstration of how an AppleScript programmer's time is spent wrestling with the target application's dictionary, please pause and read Appendix A. Dictionaries and the problems associated with them are studied in depth in Chapter 20. Some alternative tools for displaying the contents of an 'aete' resource are listed in Appendix C.