AppleScript Tutorial 3 - The Dictionary
In this tutorial, youll learn where to find an applications dictionary, which describes all of the terms understood by that application.
The index of the AppleScript tutorial series.
If you have not already completed tutorial 2, go back to see what makes an existing script tick, and customize it to work slightly differently.
After youve finished this tutorial chapter, go on to learn what is an object and a class.
Natural Language, but StructuredThis tutorial should answer these questions for you:
Earlier tutorials in this series looked at existing scripts. Now you will start to learn the AppleScript development process so you can create your own scripts from scratch.
- If AppleScript language is so human why doesnt any instruction work?
- How do I know what commands are understood by an application?
- What is an AppleScript dictionary, how do I view it and how is it organized?
- Whats the difference between a class, command, property and parameter, and where are they in the dictionary?
The DictionaryOne of the most attractive aspects of AppleScript, as a programming or scripting language, is its use of natural, almost human language. Although earlier versions of AppleScript included French and other dialects, AppleScript now only offers English like language.
A series of instructions written in AppleScript code is called an AppleScript script. They are commonly referred to as simply AppleScripts or scripts. I will also refer to people who write scripts as a scripter.
Here is an example of a fairly English like script that does a complex task. Imagine that youve created a word processing document where each topic heading uses the heading style. You want to build a table of contents for your report by telling AppleWorks to get every paragraph in the front document whose paragraph style is heading and the length is greater than zero. The script would be very close to this English description:
tell application "AppleWorks 6" to get every paragraph in the front document whose paragraph style is "heading" and the length is greater than 0
The script above actually works. It looks very English like.
This readability tends to inspire the budding scripter to launch headlong into writing scripts, which is good. But the down side of AppleScripts natural language is that new scripters tend to assume that almost anything goes, but quickly become frustrated when few attempts succeed at writing natural language. You might have experienced this frustration yourself. Like any language, human or computer based, AppleScript has a structure that must be obeyed. This tutorial series focusses on explaining the correct structure or syntax of the AppleScript language to save you from guessing.
Opening a Dictionary in the Script EditorYou can tell an application what to do, if you use the appropriate verbs, nouns, adjectives and sentence structure. But how do you know what terms an application understands? Fortunately, an integral part of any scriptable application (ie an application that supports AppleScript) is its AppleScript dictionary (to which well often refer to as simply the dictionary). Each application has its own dictionary that lists all the applications scripting terms, their description and usage.
A human language dictionary (such as English, French or German), lists each noun, adjective, verb and adverb in the language. An applications AppleScript dictionary lists similar information. It lists each class, property, command and parameter. Figure 1 gives a brief description of each, to be discussed in detail in upcoming lessons.
Term Similar to English Description Examples Class Noun The classification given to a particular type of object. menu, document, character, field, cell. Property Adjective An attribute or quality of a class. color of oval, length of paragraph, name of document Command Verb A command or instruction to do an action. make new document, select menu item, save document, delete record. Parameter Adverb A value or argument that more precisely defines the events behavior. make new text with data "hello", save front document using translator "HTML".
Figure 1: Terms Defined by an Applications Dictionary
Like a human language dictionary, an applications dictionary does not explain the grammar or sentence structure. Well cover the sentence structures and AppleScript keywords (such as set, tell, if, repeat, whose, it) briefly as we go and in detail in later tutorials.
The dictionary is the single most important source of information you need to write scripts for an application.
SuitesTo display an applications AppleScript dictionary, you open the application file with a script editor. The most commonly used script editor is Apples Script Editor, which is included with all Macintosh operating systems from System 7.5 onward. However, you have other options including Script Debugger, Scripter, Smile and FaceSpan.Exercise 1: Opening AppleWorks Dictionary
A copy of Script Editor should already be on your hard disk, in the location: Applications/ AppleScript/ Script Editor. (In Mac OS 9 and earlier, its probably in the startup disk, in the location: Applications: Apple Extras: AppleScript: Script Editor). Most of these tutorials assume that you have Apple's Script Editor. Where this tutorial mentions "the script editor" (in lower case), any script editor could be used, though Apple's Script Editor (written in title case) is your most probable choice and the one appearing in most of the screen shots here. The other editors are used occasionally in later tutorials to show their particular strengths.
Its probably a good idea for you to locate your script editor and drag it to your application dock, for easy access throughout this tutorial.
You can open an applications dictionary in a script editor by either selecting Open Dictionary in the script editors File menu, or by dragging the applications icon onto the script editor icon in the Finder. An alias of either application also works.
Lets open AppleWorks AppleScript dictionary.
- If you havent already, in the Finder, locate the script editor in the location: Applications/ AppleScript/ Script Editor. Click once on Script Editor to select it. Drag the Script Editor icon, so it appears in your Dock. (If you are using Mac OS 9 or earlier, you could instead make an alias of the script editor in a convenient location, such as on the desktop, or in a folder of frequently used programs.)
- Locate your AppleWorks application file. Drag it onto your Script Editor icon in the Dock, as shown in Figure 2.
Figure 2: Dragging an Application onto Script Editor, to Show its Dictionary
- Script Editor should open AppleWorks dictionary, as shown in Figure 3. Leave this window open for the next exercise.
Figure 3: The AppleWorks AppleScript Dictionary
Supplementary ExercisesIn Script Editor, the left pane of an applications dictionary lists all the terms understood by that application. The terms are grouped in functional suites, usually starting with the Standard Suite, then the applications general suite, followed by any particular functional groupings. For instance, AppleWorks has separate suites for text, database, spreadsheet and graphics. Each suite groups together related features in the application. For example, the terms recalculate, sort, cell and row are listed in the AppleWorks Spreadsheet Suite since they are particular to spreadsheet operations.Exercise 2: Viewing AppleWorks Dictionary
Within each suite, the terms are listed in two subsections: Classes and Commands. You can expand each suite heading and each Classes/Commands heading to show the terms within that grouping. (In older script editors, all suite listings are shown in bold, are already permanently expanded and do not subsection the classes and commands, but list them together, with classes in italics and commands in plain text.) For example, within the AppleWorks Spreadsheet Suite, the terms recalculate and sort are in the Commands subsection, while cell and row are in the Classes subsection.
Selecting a term in the left pane displays its description in the right pane. The detail depends on whether its a class or command. The description of a class may include: the plural form (eg cells is the plural of cell); a list of elements (eg a range of cells may contain several rows and columns); a list of properties (eg each cell has a formula, format and lock value). The description of a command may include a list of parameters (eg sort can specify a reference to the cell range, the orientation and the key cell data), and a result. I will explain these in detail in subsequent tutorial chapters.
Following on from the previous exercise, lets look at some classes and commands in AppleWorks AppleScript dictionary.
- In the left pane , you should see various suite headings. Expand the AppleWorks Spreadsheet Suite. In this suite, expand the Classes and Commands sections. Click on the word cell (which is in the AppleWorks Spreadsheet Suite, in the Classes section), to select it. The AppleWorks Dictionary window should look like Figure 4a (or Figure 4b if youre using an old script editor.)
Figure 4a: Dictionary Showing the Definition of a Class
Figure 4b: Dictionary Showing the Definition of a Class (Old Script Editor)
- Have a look through the properties of a cell. You should see formula, format, Lock, name and so on.
- In the left pane, still in the AppleWorks Spreadsheet Suite, in the Commands section, click on the word sort to select it. The window should look like Figure 5.
Figure 5: Dictionary Window Showing the Definition of a Command
ConclusionTry these supplementary tasks:
- Locate the graphic object class in the AppleWorks dictionary.
- What properties does an graphic object have?
- In which suite is the paragraph class?
Next...Now weve had a look at an applications AppleScript dictionary. Weve briefly viewed suites of classes and events and their descriptions, including their properties and parameters. The next few tutorials will examine each of these in detail.
© 1998 - 2004 BareFeetWareGo on to Tutorial 4 to learn what is an object, what is a class, and more detail on how classes are described in the dictionary.