Cocoa Scripting Guide: Script Terminology Files

< Previous PageNext Page >

Hide TOC

Script Terminology Files

A script terminology file maps AppleScript terminology—the English-like words and phrases a scripter can use in a script, such as the first word in the first paragraph—to the class and command descriptions in a script suite file. A script terminology file also provides valuable documentation about an application’s scripting support, which users can examine in the Script Editor and Xcode applications.

Note: If an application also includes an 'aete' resource, Script Editor displays the contents of that resource instead of the script terminology. (In Mac OS X version 10.4 and later, if an application uses an sdef file, any 'aete' file is ignored.)

Like a script suite file, a script terminology file is stored as a nested list of key-value pairs. Script terminologies are always property lists, but in addition they must conform to the format described in “The Structure of a Script Terminology File.” See “Creating Your Own Script Suite Files” for information on how to create and edit these files.

Note: English is currently the only supported dialect in AppleScript. It is not recommended that you localize your terminology for other languages.

Listing B-2 shows the terminology for the NSApplication class, taken from NSCoreSuite.scriptTerminology, the script terminology file for the Standard suite (provided by Cocoa). The terminology is shown as exported in “ASCII Property List File” format by the Property List Editor application. You can find the full version of this file on your system by following the Resources symbolic link at /System/Library/Frameworks/Foundation.framework.

Listing B-2 NSApplication class from the script terminology file for the Standard suite

        NSApplication = {

            Attributes = {

                isActive = {

                    Description = "Is this the frontmost (active) application?";

                    Name = frontmost;

};

                name = {Description = "The name of the application."; Name = name; };

                version = {Description = "The version of the application."; Name = version; };

};

            Description = "An application's top level scripting object.";

            Name = application;

            PluralName = applications;

};

        NSColor = {Description = "A color."; Name = color; PluralName = colors; };

        NSDocument = {

            Attributes = {

                fileName = {Description = "The document's path."; Name = path; };

                isDocumentEdited = {

                    Description = "Has the document been modified since the last save?";

                    Name = modified;

};

                lastComponentOfFileName = {Description = "The document's name."; Name = name; };

};

            Description = "A document.";

            Name = document;

            PluralName = documents;

};

The Structure of a Script Terminology File

Script terminologies, like script suite files, are stored as text files of key-value pairs. As with a script suite file, a script terminology file consists of a series of nested dictionaries. Many of the subdictionaries (class, command, argument, and so on) should have counterparts in the script suite file.

The following tables describe the optional and required keys for a script terminology file.

**Table B-14** Terminology dictionary
Key	Value type or reference	Description
“`Name`”	`NSString` or `NSArray` of `NSString` objects	Human-readable name of suite (required); the name can be placed anywhere in the definition, as long as it is a first-level element
“`Description`”	`NSString`	Human-readable description of suite (optional; but highly recommended)
“`Classes`”	Class list terminology dictionary (Table B-15)	Required only if there is a corresponding definition in the script suite file
“`Commands`”	Command list terminology dictionary (Table B-19)	Required only if there is a corresponding definition in the script suite file
“`Synonyms`”	Class synonym list terminology dictionary (Table B-23)	Required only if there is a corresponding definition in the script suite file
“`Enumerations`”	Enumeration terminology dictionary (Table B-25	Required only if there is a corresponding definition in the script suite file

**Table B-15** Class list terminology dictionary
Key	Reference	Description
“className”	Class terminology dictionary (Table B-16)	One per each scriptable class. Must be the name of an Objective-C class.

**Table B-16** Class terminology dictionary
Key	Value type or reference	Description
“`Name`”	`NSString` or `NSArray` of `NSString` objects	Human-readable name of class (required)
“`Description`”	`NSString`	Human-readable description of class (optional; but highly recommended)
“`PluralName`”	`NSString`	Human-readable name for plural form of class (required)
“`Attributes`”	Attribute list terminology dictionary (Table B-17)	Attributes of the class (required only if there is a corresponding definition in the script suite file)

**Table B-17** Attribute list terminology dictionary
Key	Reference	Description
“attributeName”	Attribute terminology dictionary (Table B-18)	Description of attribute of the class

**Table B-18** Attribute terminology dictionary
Key	Value type or reference	Description
“`Name`”	`NSString` or `NSArray` of `NSString` objects	Human-readable name of attribute (required).
“`Description`”	`NSString`	Human readable description of attribute (optional, but highly recommended)
“`Number`”	`NSString` or `NSArray` of `NSString` objects	“plural” or “singular” (default).

**Table B-19** Command list terminology dictionary
Key	Reference	Description
“commandName”	Command terminology dictionary (Table B-20)	One per each supported script command.

**Table B-20** Command terminology dictionary
Key	Value type or reference	Description
“`Name`”	`NSString` or `NSArray` of `NSString` objects	Human-readable name of command (required)
“`Description`”	`NSString`	Human-readable description of command (optional; but highly recommended)
“`Arguments`”	Argument list terminology dictionary (Table B-21)	Description of command arguments (required only if there is a definition)

**Table B-21** Argument list terminology dictionary
Key	Reference	Description
“argumentName”	Argument terminology dictionary (Table B-22)	Descriptions of command arguments.

**Table B-22** Argument terminology dictionary
Key	Value type or reference	Description
“`Name`”	`NSString` or `NSArray` of `NSString` objects	Human-readable name of argument (required)
“`Description`”	`NSString`	Human-readable description of argument (optional, but highly recommended)
“`Sex`”	`NSString` or `NSArray` of `NSString` objects	“masculine”, “feminine”, “none” (default)
“`Number`”	`NSString` or `NSArray` of `NSString` objects	“plural” or “singular” (default)

**Table B-23** Class synonym list terminology dictionary
Key	Reference	Description
“`Apple event code`”	Class synonym terminology dictionary (Table B-24)	Descriptions of constant synonyms for class

**Table B-24** Class synonym terminology dictionary
Key	Value type or reference	Description
“`Name`”	`NSString` or `NSArray` of `NSString` objects	Human-readable name of class (required)
“`Description`”	`NSString`	Human-readable description of class (optional)
“`PluralName`”	`NSString`	Human-readable name of plural form of class (required)

**Table B-25** Enumeration list terminology dictionary
Key	Reference	Description
“enumerationName”	Enumerators list terminology dictionary (Table B-26)	One per enumeration (required).

**Table B-26** Enumerators list terminology dictionary
Key	Value type or reference	Description
“enumeratorName”	Enumerator terminology dictionary (Table B-27)	One per enumerator (required).

**Table B-27** Enumerator terminology dictionary
Key	Value type or reference	Description
“`Description`”	`NSString`	Human-readable description of enumerator (optional)
“`Name`”	`NSString`	Human-readable name of enumerator (required)

< Previous PageNext Page >

Hide TOC

Last updated: 2008-03-11

Did this document help you?
Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.




	Get information on Apple products. Visit the Apple Store online or at retail locations. 1-800-MY-APPLE Copyright © 2007 Apple Inc. All rights reserved. \| Terms of use \| Privacy Notice