Script Suite and Script Terminology Files

Cocoa applications can provide scriptability information in the form of script suite and script terminology files. This format, sometimes referred to as the script suite format, has been supported since the first version of Cocoa scripting. This chapter provides a detailed look at the use and structure of these files.

When supplying scripting information in the script suite format, an application provides at least one nonlocalized script suite file and a corresponding script terminology file. These files together describe the scripting capabilities of the application and the terminology a scripter uses to access those capabilities.

Script Suite Files

A script suite file describes scriptable objects in terms of their attributes, relationships, and supported commands. You can think of a script suite file as supplying scripting information for use by Cocoa’s internal scripting support; that information can also be used by your application. “Script Terminology Files” describes the files used to store the scripting terminology that corresponds to the information in a script suite file. That terminology defines the terms actually used by scripters to control the application.

The information in a script suite file consists of a nested list of key-value pairs. Script suites are always property lists, but in addition they must conform to the format described in “The Structure of a Script Suite File.” For information on creating them, see “Creating Your Own Script Suite Files.”

Frameworks, loadable bundles, and applications that support scripting can include a script suite file as a language-independent resource. The name of the file takes the form suiteName.scriptSuite, where suiteName uniquely identifies the script suite file. An example would be MyApplication.scriptSuite.

Script suites are located in the (nonlocalized) Resources directory of an application, framework, or bundle. For example, for a framework named MyStuff.framework, the script suite file (named MyStuff.scriptSuite) would reside in MyStuff.framework/Resources/.

Listing B-1 shows the class description for the NSApplication class, taken from NSCoreSuite.scriptSuite, Cocoa's script suite file for the AppleScript Standard suite. The class description is shown as exported in “XML Property List File” format by the Property List Editor application. You can find the full version of this script suite file on your system by following the Resources symbolic link at /System/Library/Frameworks/Foundation.framework.

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

        <key>NSApplication</key>
        <dict>
            <key>AppleEventCode</key>
            <string>capp</string>
            <key>Attributes</key>
            <dict>
                <key>isActive</key>
                <dict>
                    <key>AppleEventCode</key>
                    <string>pisf</string>
                    <key>ReadOnly</key>
                    <string>YES</string>
                    <key>Type</key>
                    <string>NSNumber&lt;Bool&gt;</string>
                </dict>
                <key>name</key>
                <dict>
                    <key>AppleEventCode</key>
                    <string>pnam</string>
                    <key>ReadOnly</key>
                    <string>YES</string>
                    <key>Type</key>
                    <string>NSString</string>
                </dict>
                <key>version</key>
                <dict>
                    <key>AppleEventCode</key>
                    <string>vers</string>
                    <key>ReadOnly</key>
                    <string>YES</string>
                    <key>Type</key>
                    <string>NSString</string>
                </dict>
            </dict>
            <key>Superclass</key>
            <string>NSCoreSuite.AbstractObject</string>
            <key>SupportedCommands</key>
            <dict>
                <key>NSCoreSuite.Open</key>
                <string>handleOpenScriptCommand:</string>
                <key>NSCoreSuite.Print</key>
                <string>handlePrintScriptCommand:</string>
                <key>NSCoreSuite.Quit</key>
                <string>handleQuitScriptCommand:</string>
            </dict>
            <key>ToManyRelationships</key>
            <dict>
                <key>orderedDocuments</key>
                <dict>
                    <key>AppleEventCode</key>
                    <string>docu</string>
                    <key>LocationRequiredToCreate</key>
                    <string>NO</string>
                    <key>ReadOnly</key>
                    <string>YES</string>
                    <key>Type</key>
                    <string>NSDocument</string>
                </dict>
                <key>orderedWindows</key>
                <dict>
                    <key>AppleEventCode</key>
                    <string>cwin</string>
                    <key>ReadOnly</key>
                    <string>YES</string>
                    <key>Type</key>
                    <string>NSWindow</string>
                </dict>
            </dict>
        </dict>

Each scriptable class in a script suite file must have a “class description” which, in key-value form, declares the attributes and relationships of the class in terms of type and four-character code (or Apple event code). For example, the four-character code for NSApplication in Listing B-1 is the string "capp". You can read more about four-character codes in “Code Constants Used in Scriptability Information.” The primary key for a class description must be a class name such as NSApplication that identifies a real Objective-C class.

The class description also declares the AppleScript commands the class supports and specifies the superclass, if the superclass also supports scripting of its objects. In this case, the superclass for NSApplication is AbstractObject, which is the root of the scriptable class hierarchy, and corresponds to the NSObject class.

The Structure of a Script Suite File

A script suite file is a text file containing key-value pairs in the form of a series of nested dictionaries, with two main categories: class descriptions and command descriptions.

A class description describes the attributes and relationships of a scriptable class. Relationships can be one-to-one or one-to-many. A class description also lists the commands a class supports and specifies whether a particular method of the class handles the command or the command’s default implementation is used to execute the command. A description of a class can designate a scriptable superclass, and thus inherit the attributes, relationships, and supported commands of that class. Class descriptions for the classes defined in an application's script suite file are instantiated by the global instance of NSScriptSuiteRegistry when it loads the application's scriptability information.

A command description defines the characteristics of an AppleScript command that the application, framework, or bundle specifically supports. This information includes the class of the command, the type of the return value, and the number and types of arguments. Many of the commands defined in the Standard suite (such as copy, duplicate, move, and so on) have default implementations in subclasses of NSScriptCommand, listed in “Subclasses for Standard AppleScript Commands.” Command descriptions for the commands defined in an application's script suite file are instantiated by the global instance of NSScriptSuiteRegistry when it loads the application's scriptability information. For more information on the script command mechanism, see “Script Commands.”

A script suite file may contain additional declarations, such as enumerations. For example, NSCoreSuite.scriptSuite contains a declaration for the SaveOptions enumeration, which defines the AppleScript values for yes, no, and ask that are used when closing a file.

The following tables describe the structure of a script suite file, including its optional and required keys.

Table B-1  Suite dictionary

Key

Value type or reference

Description

name

NSString

Name of suite (required); the name can be placed anywhere in the definition, as long as it is a first-level element

AppleEventCode

NSString

Four-character code for this suite (required)

Classes

Class list dictionary (Table B-2)

optional (no classes defined by default)

Commands

Command list dictionary (Table B-7)

optional (no classes defined by default)

Synonyms

Synonym list dictionary (Table B-10)

optional (no synonyms defined by default)

Enumerations

Enumeration list dictionary (Table B-11)

optional (no enumerations defined by default)

Table B-2  Class list dictionary

Key

Reference

Description

className

Class dictionary (Table B-3)

One per each scriptable class. Must be the name of an Objective-C class defined by Cocoa or the application.

Table B-3  Class dictionary

Key

Value type or reference

Description

Superclass

NSString

Scriptable superclass; must be the name of an Objective-C class. All attributes, relationships, and supported commands are inherited and can be overridden. You can use the notation suiteName.className to designate the class. (Optional.) You can also use the AbstractObject class to specify a base class your scriptable classes can inherit from that contains no scriptability of its own.

AppleEventCode

NSString

Four-character code for this class (required)

Attributes

Property list dictionary (Table B-4)

Attributes of the class (optional)

ToOneRelationships

Property list dictionary (Table B-4)

One-to-one relationships of the class (optional)

ToManyRelationships

Property list dictionary (Table B-4)

One-to-many relationships of the class (optional)

SupportedCommands

Supported commands dictionary (Table B-6)

Commands supported by the class (optional)

Table B-4  Property list dictionary

Key

Reference

Description

propertyName

Property dictionary (Table B-5)

Definition of an attribute or relationship. attributeName should map to an instance variable of the class for which there are accessor methods.

Table B-5  Property dictionary

Key

Value type

Description

Type

NSString

Name of class of values of this property (required)

AppleEventCode

NSString

Four-character code for this suite (required)

ReadOnly

NSString

“Yes” or “No” (optional; “No” by default)

Table B-6  Supported commands dictionary

Key

Value type

Description

commandName

NSString

Name of method this class uses to implement the command or ““ if the default implementation is sufficient. commandName should be in suiteName.commandName notation if command is not in the same suite as the class.

Table B-7  Command list dictionary

Key

Reference

Description

commandName

Command dictionary (Table B-12)

Command definition.

Table B-8  Command dictionary

Key

Value type or reference

Description

CommandClass

NSString

Class of command. Set this value to NSScriptCommand for default behavior. If not using default, must be set to a subclass of NSScriptCommand (required).

AppleEventCode

NSString

Four-character code for this command (required)

AppleEventClassCode

NSString

Four-character class constant for this command (optional; by default, is the constant for the script suite)

Type

NSString

Class name of result of command or “” if no result (optional; no result by default)

ResultAppleEventCode

NSString

Four-character code for the return type of the command. Must be present if “Type” value is assigned. Can be “****” if the return type is variable.

Arguments

Argument list dictionary (Table B-13)

Arguments of command (optional; no arguments by default)

Table B-9  Argument list dictionary

Key

Value type or reference

Description

Type

NSString

Name of class for this argument (required)

AppleEventCode

NSString

Four-character code for this argument (required)

Optional

NSString

“Yes” or “No” (optional; “No” by default)

Table B-10  Synonym list dictionary

Key

Value type or reference

Description

Apple event code

NSString

Class name for which four-character code is a synonym.

Table B-11  Enumeration list dictionary

Key

Reference

Description

enumerationName

Enumeration dictionary (Table B-12)

One per enumeration.

Table B-12  Enumeration dictionary

Key

Value type or reference

Description

AppleEventCode

NSString

Four-character code for this enumeration (required)

Enumerators

Enumerators list dictionary (Table B-13)

Enumerators in the enumeration (required)

Table B-13  Enumerators dictionary

Key

Value type or reference

Description

enumeratorName

NSString

Four-character Apple event code for this enumerator (required)

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.

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.

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)

Cocoa Scripting’s Built-in Script Suites

Cocoa scripting provides two suites of standard scripting information: the Standard (or Core) suite and the Text suite. These suites define scriptability information for basic AppleScript commands, including copy, count, create, delete, exists, and move. They also provide information for basic AppleScript classes, such as application, document, window, and text, and for corresponding Cocoa classes, such as NSApplication, NSDocument, NSWindow, and NSTextStorage.

The Standard and Text suites are introduced in “Built-in Support for Standard and Text Suites” and described in more detail in “Use the Document Architecture” and “Access the Text Suite.”

Creating Your Own Script Suite Files

To add to Cocoa’s built-in scripting support using the script suite and script terminology approach, your application supplies files describing the scriptability information for the objects, properties, and commands it supports. For example, an application that can draw shapes (such as the Sketch application) might specify that it supports circle, rectangle, and line objects, with color and location properties. It might also support commands such as rotate and scale, in addition to standard commands such as get, set, and delete.

To create a script suite file or script terminology file, you can either use a plain text or XML editor, or use an application such as Property List Editor, which provides built-in support for creating property lists. Property List Editor is included with the OS X developer tools. If you have existing scriptability information, see “Converting and Updating Scriptability Information” for information on how to convert between various formats.

You construct files that contain entries for the classes, commands, and enumerations used by your application, including the codes, method, and class information used by Cocoa and the terminology used by scripters. Your files must follow the formats described in “The Structure of a Script Suite File” and “The Structure of a Script Terminology File.” If you use the Property List Editor application, you can ensure that you are creating a valid property list. You can also save your scriptability information in several formats:

These formats can be opened by various text editors or by Property List Editor. As a result, you can freely work with a script suite file in whichever format is most convenient for you.

Figure B-1 shows the Standard suite (from the file NSCoreSuite.scriptSuite) as displayed in the Property List Editor application. In this figure, the Classes and the NSApplication class definition are expanded so that attributes, supported commands, and relationships for NSApplication are visible.

The AbstractObject class specifies a base class that your scriptable classes can inherit from when their actual superclass has no scriptability support.

Figure B-1  Script suite for the Standard suite in Property List Editor
Script suite for the Cocoa Core suite in Property List Editor

For examples of script suites and sample code for scriptable applications, see the Sketch and TextEdit example projects, .