SDEF
NAME
sdef -- scripting definition file DESCRIPTION
Scripting definition files (sdefs) are XML files that describe everything about an application's scriptability: terminology, implementation information, and complete documentation. sdp(1) uses sdefs to generate a variety of implementation and definition files for use in an application and in AppleScript. BASICS
To read this man page, you should know what ``element'' and ``attribute'' mean in an XML document. To create an sdef, you should know how to create well-formed XML; use of an XML editor will probably make your life easier. For basic concepts and style guidelines, see Technical Note TN2106, Scripting Interface Guidelines. Knowledge of AppleScript is helpful but not necessary; see the AppleScript Language Guide, especially chapters 4 (Commands) and 5 (Objects and References). If you have already been working with sdefs in Mac OS X 10.2 or 10.3, read the History section, since the format has changed in 10.4. If you are familiar with AppleScript or with writing aete resources, most of the sdef elements will be familiar to you. If you are not, or if you want to know how sdef elements map to your implementation language, here is a brief translation guide. For more detailed information, see the definitions in the Reference section. sdef code class class property attribute (XML), field (C), member variable (C++/ObjC), to-one relation element element (XML), to-many relation command, event verb, method (ObjC), member function (C++) (this is not entirely accurate; see the Reference entry) parameter parameter direct parameter self (ObjC) or this (C++), with some caveats; see the Reference entry STRUCTURE
There are two broad categories of elements: terminology element: An element that defines a term usable in a script: class, command, contents, enumerator, event, parameter, property, record-type, and value-type. implementation element: An element that holds implementation information for a particular application framework. Currently, the only implementation element is the cocoa element. The element structure of an sdef is as follows. Indentation shows containment, and `*', `+', and `?' have their usual EBNF meanings: `*' means zero or more, `+' means one or more, and `?' means zero or one (i.e., optional). dictionary (the root element) suite+ (class | command | enumeration | event | record-type | value-type)+ enumeration enumerator+ record-type property+ class contents? property+ element+ accessor* responds-to* command or event direct-parameter? parameter* result? The elements listed above may also contain documentation, implementation, and synonym elements, as noted here: element occurs in documentation dictionary, suite, and all terminology elements implementation all but dictionary synonym all terminology elements REFERENCE
Common Attributes The following attributes are common to several of the element types described below. name For terminology elements, the scripting term for the element. Names must be one or more C identifiers (i.e., [A-Za-z_][A-Za-z0-9_]*) separated by a space. (Other elements have name attributes too, but for different purposes and with different content rules.) code The four-character code (eight-character for verbs) for the element. AppleScript and the Apple Event Manager use these codes to handle dispatching. A code may be specified as a hex constant, e.g., ``0x1234abcd'', if some of the characters are unprintable. type The type of an element, property, or parameter. The value must be one of the primitive types `any', `text', `integer', `real', `number', `boolean', `specifier', `location specifier', `record', `date', `file', `point', `rectangle', or `type', or the name of a class, enumeration, record-type, or value-type defined elsewhere in the sdef. To specify a complex type such as ``list of integer'' or ``number or text'', use a type element as described below. Usage of type attributes changed significantly in Mac OS X 10.4; see History for details. description (optional) A short description of the element. hidden (optional) If an element is marked hidden, it is not shown in the dictionary, though it is still implemented. This is useful for obsolete or not-ready-for-prime-time scripting features. Cocoa scriptTerminology files do not support hidden terms; for best results, build an `aete' into your application as well. The value may be `yes' or `no' (the default). Elements accessor Accessors define which access forms an element supports. There are six forms: index numeric index (window 1) name named element (window "Bob") id unique id (file id 8727). Ids are often numeric, but don't have to be. range a range of elements (records 4 through 12) relative relative to another object (word before paragraph 2) test objects satisfying a test (shapes whose color is blue) Accessor elements are currently only useful for aetes; Cocoa Scripting ignores them and figures out supported forms based on the element's properties. ATTRIBUTES style index | name | id | range | relative | test class An abstract object definition that lists the properties, elements, and supported verbs for instances of that class. Class instances are called ``objects.'' CONTAINS implementation?, synonym*, contents?, element*, property*, responds-to* ATTRIBUTES name As above. code As above. description As above. hidden As above. plural (optional) The plural name of the class. If omitted, defaults to the name with `s' appended. inherits (optional) The class, if any, that this one descends from. cocoa Holds implementation information for Cocoa Scripting. Use the appropriate attribute for the containing element to describe the relevant bit of Cocoa implementation. ATTRIBUTES class An Objective-C class name: use for classes and the CommandClass of verbs. key A string key for an NSDictionary of parameters, or a KVC key name for a property or element. method An Objective-C method name: use for respondsto methods. name A name used internally by Cocoa Scripting: use for suites, command and event key names, enumerations, and enumerators. cocoa elements are optional; if omitted, sdp(1) will generate a default name. The basic rule is to capitalize each word of the element's name except the first, and then to remove any spaces. There are two special cases: classes also capitalize the first word, and elements start with the plural of the specified element type. For example: element default name <class name="refresh rate"> RefreshRate <property name="current resolution"> currentResolution <element type="monitor"> monitors This default name becomes the `class' for classes, the `key' for properties, elements, and parameters, and the `name' for suites, verbs, enumerations, and enumerators. In Cocoa, verbs are implemented by a class, which Cocoa refers to in scriptSuite files as the CommandClass; the default is always NSScriptCommand. An explicit cocoa element is only necessary if you want to override these defaults. command (aka method, member function; see also event) Commands and events, collectively called ``verbs,'' are messages that may be sent to an object. For documentation purposes, sdefs distinguish between commands, which are verbs a script would send to an object (e.g., ``close''), and events, which are notifications sent to an object by a framework or system service (e.g., ``did close''). Unlike most object-oriented languages, verbs are defined independently of any particular class; a class may then list the verbs that it responds to. To Java and Objective-C programmers, sdef verbs therefore resemble protocols more than member functions. You may specify the same command more than once with different parameters, such as to define a polymorphic ``open'' command that has different parameters depending on whether it is applied to a document or a database. CONTAINS implementation?, synonym*, direct-parameter?, parameter*, result? ATTRIBUTES name As above. code As above; event codes are eight characters. description As above. hidden As above. contents Similar to a property, but its name and code are optional. If omitted, they default to ``contents'' and `pcnt', respectively. In Mac OS X 10.2 and later, Cocoa Scripting will treat the contents property as its class's implied container: scripts may refer to elements of the contents property as if they were elements of the class. For example, TextEdit documents have a ``text'' contents property. Technically, the first word of a document is ``word 1 of text of document 1'', but because ``text'' is an implied container, a script can also say ``word 1 of document 1''. dictionary The root element of an sdef. CONTAINS suite+ ATTRIBUTES title The title of the dictionary, which appears in the dictionary display. direct-parameter The direct parameter of a verb is a value that appears immediately after the verb and specifies its target. The type of the direct parameter is usually an application class. For example, in the command ``close window 1'', the direct parameter is ``window 1''. Not all verbs have a direct parameter; in such cases, omit this element. In Cocoa Scripting, the direct parameter is the object to which the message is sent (i.e., ``self'') if the direct parameter is an application class. Otherwise, the message is sent to the application object with the direct parameter's value as a normal parameter. direct-parameter is a special case of parameter; it has no `name' or `code' attribute, and may not be hidden. documentation When an element needs more exposition than a simple `description' attribute can provide, use a documentation element. Script Editor's dictionary viewer will display additional XHTML markup included inside an html element, for example: <property name="link" type="text"> <documentation> <html> Goes <a href="http://www.apple.com/applescript">here</a> by default. </html> </documentation> </property> Because the contents of an html element are still parsed as XML, they must be well-formed XML, which means they must be XHTML, not HTML. In particular: oo All tags must be balanced, including ones HTML would let you leave open. (Use <p>this</p> <p>that</p>, not <p>this <p>that.) oo Empty tags must use XML notation. (Use <br/>, not <br>.) The contents are an XHTML fragment, not a complete XHTML document. You may include any other XML elements you wish inside a documentation element; sdp(1) will simply ignore them. element (aka to-many relation.) An object contained in another one. An object may have any number of elements of a given class, including none at all, and may have any number of element classes. For example, the documents of an application are elements. CONTAINS implementation?, accessor* ATTRIBUTES type As above. description As above. hidden As above. access (optional) The allowed access for the element class: `r' for read-only, `w' for write-only and `rw' for read-write (the default). enumeration A list of symbolic constants (enumerators). For example, the type of the ``saving'' parameter for ``close'' is the enumeration yes/no/ask. CONTAINS implementation?, enumerator+ ATTRIBUTES name As above. code As above. description As above. hidden As above. inline (optional) Controls how many enumerators are displayed in-line. By default (with no attribute), all enumerators are displayed inline. For example: sdef: <enumeration name="save options"> <enumerator name="yes"/> <enumerator name="no"/> <enumerator name="ask"/> </enumeration> <parameter name="saving" type="save options"/> display: saving yes/no/ask By specifying a number, that number of enumerators will be listed in-line, with a link to the complete definition. To show only the enumeration name, use ``inline="0"''. For example: inline="2" saving yes/no/more... inline="0" saving save options This attribute only affects the display; it has no semantic meaning. enumerator A symbolic constant. CONTAINS implementation?, synonym* ATTRIBUTES name As above. code As above. description As above. hidden As above. event See command. parameter A named value included with a verb. Parameter names are often prepositions: ``with'', ``by'', etc. CONTAINS implementation? ATTRIBUTES name As above. code As above. type As above. description As above. hidden As above. optional (optional) Indicates whether the parameter is optional or required. The value may be `yes' (optional) or `no' (required; the default). property (aka field, instance variable, to-one relation.) A unique data member of an object. Properties always have a name, and there is always exactly one of them with a given name in an object. For example, the name of a document is a property. CONTAINS implementation? ATTRIBUTES name As above. code As above. type As above. description As above. hidden As above. access (optional) `r', `w', or `rw' (the default), as for element. in-properties (optional) For frameworks that provide automatic support for a ``properties'' property, indicates whether or not this property should not be included. The value may be `yes' (the default) or `no'. record-type A simple structure, as opposed to a class. (In C terms, a ``POD'' or ``plain old data'' type.) Points, rectangles, and print settings are all record-types. CONTAINS implementation?, synonym*, property+ ATTRIBUTES name As above. code As above. type As above. description As above. hidden As above. responds-to Defines a verb that a class responds to. Cocoa Scripting only requires these in order to define a custom method for handling a verb (see cocoa); they are otherwise purely for documentation. CONTAINS implementation? ATTRIBUTES name The name of the verb. hidden As above. result The type of value generated when a verb is executed. If there is no result, omit this element. result is a special case of parameter; it has only `type' and `description' attributes and may not be hidden or optional. suite A collection of related terms. Suites are purely an organizational aid to the user; they have no impact on scripts. There is no technical limit on how many items a suite can contain, but 10 to 15 items is considered a comfortable size. CONTAINS implementation?, (class | command | enumeration | event record-type | value-type)+ ATTRIBUTES name The suite's name to be shown in the dictionary. This is not a term that may appear in scripts. code As above. description As above. hidden As above. synonym Defines an alternate term or code for the main element. ATTRIBUTES name The alternate name, which follows the rules for terminology element names. code The alternate code. hidden As above. At least one of `name' or `code' is required. Depending on which attributes are present, the dictionary will have different effects: Name only Use these to define an alternate term that may be used at compile time. It will decompile as the main term. For example, AppleScript uses ``app'' as a name-only synonym for ``application''. Cocoa scriptTerminology files do not support these; generate an `aete' resource for your application as well. Code only Use these when migrating from one code to another. (Typically, this happens when correcting an older version of the dictionary which used a non-standard code.) Compiled scripts that use the synonym code will decompile using the main term. Code-only synonyms are implicitly hidden. Because of how Cocoa scriptSuite files work, they must contain a cocoa element with a `method' or `key' attribute in order to generate a correct scriptSuite file. Name and Code Use these to define an alternate term that is preserved across compilation. Effectively, this is a separate term that happens to act the same as the main one. As with code-only synonyms, they must contain a cocoa element to generate a correct scriptSuite file. Sdef synonym elements have nothing to do with `Synonyms' sections in Cocoa's suite definition files. Those are a trick to allow two different classes in the dictionary to share the same implementation class; this is necessary because suite definition files use the implementation class name as a key. If you have two classes that happen to share the same implementation, declare them separately, and point their implementation elements at the same class. sdp(1) will do the right thing and generate a `Synonyms' section for you. type Any element that has a type attribute may instead have one or more type elements. (Using both in the same element is an error.) Using more than one type element indicates that any of the types are allowed; using the `list' attribute indicates a list of the specified type. Using type elements inside type elements, such as to express ``list of list of integer'', is not currently supported. ATTRIBUTES type As above. list (optional) Indicates that the full type is a list of the type specified by the `type' attribute. May be `yes' or `no' (the default). EXAMPLES tabs (list of integer): <property name="tabs"> <type type="integer" list="yes"/> </property> frequency (number or text): <property name="frequency"> <type type="number"/> <type type="text"/> </property> value-type A simple type definition. A value-type has no properties and no elements accessible by your scripting; it is useful for defining new basic types, such as an image. CONTAINS implementation?, synonym* ATTRIBUTES name As above. code As above. description As above. hidden As above. cocoa elements for values should declare the backing Cocoa class (typically NSData) using the `class' attribute, and may also declare the qualifier name using the `name' attribute, but this is only used inside the scriptSuite file. For example, an ``image'' type might be declared like this: <value-type name="image" code="PICT"> <cocoa class="NSData" name="Image"/> </value-type> EXAMPLES
See /Developer/Examples/Scripting Definitions. SEE ALSO
sdp(1), /System/Library/DTDs/sdef.dtd, TN2106: Scripting Interface Guidelines <http://developer.apple.com/technotes/tn2002/tn2106.html> HISTORY
sdef changed in several significant ways in Mac OS X 10.4. sdp(1) will still recognize the old forms, but Cocoa Scripting and Script Editor will not. oo ``collector'' elements such as classes, types, and properties no longer exist. Their former children should be moved to their immediate ancenstor element. In general, children may be freely mixed now. For example, placing a command element next to a class element is perfectly acceptable. oo cocoa elements of property and element elements now use a `key' attribute (formerly `method'). oo The default Cocoa key for element elements is now the type's plural (formerly its name). oo Some primitive types changed their names: `string' is now `text', `object' is now `specifier', and `location' is now `location specifier'. oo Complex types such as `list of integer' or `number or text' are now expressed using type elements, not complex strings. For example: before: <property name="tabs" type="list of integer"/> after: <property name="tabs"> <type type="integer" list="yes"/> </property> before: <property name="frequency" type="number | text"/> after: <property name="frequency"> <type type="number"/> <type type="text"/> </property> See the type documentation for complete details. oo Boolean attributes, that is, optional and hidden, now accept `yes' and `no' as values (formerly the attribute name, e.g. `hidden="hidden"'). oo The not-in-properties attribute is now named in-properties; its possible values are `yes' (the default) and `no'. To upgrade a pre-10.4 sdef to the new format, you can use xsltproc(1) with a supplied transform: xsltproc --novalid /usr/share/sdef/upgrade.xsl my.sdef > my-tiger.sdef Mac OS X April 25, 2002 Mac OS X