|SDEF(5)||File Formats Manual||SDEF(5)|
sdef — scripting
Scripting definition files (sdefs) are XML files that describe everything about an application scripting interface: terminology, implementation information, and complete documentation. Applications may incorporate them to define their own scriptability, and scripting clients such as AppleScript and Scripting Bridge read them to determine what operations an application supports.
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 an older version of Mac OS X, read the History section, since there have been changes to the format. If you are using Cocoa, Cocoa Scripting as of Mac OS X 10.4 (Tiger) supports using sdefs directly rather than preprocessing them with sdp(1); see the Sdef Scriptability Guide for Cocoa for details.
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. Many
of these equivalents are not exact; for more detailed information, see the
definitions in the Reference
There are two broad categories of elements:
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)
The elements listed above may also contain
elements, as noted here:
If you wish to re-export scripting features from a framework your application links to, such as AppKit, you should include the sdef of that framework in your own. (Sdef-based applications have only the scripting interface that they explicitly declare. This is in contrast to the older scriptSuite scheme, which would automatically import scripting interface from any loaded bundles.)
To do this, use an XInclude element (http://www.w3.org/TR/xinclude) pointing to the desired file. Sdefs for system frameworks are located in /System/Library/ScriptingDefinitions. For example, the sdef for a typical Cocoa application would begin with this:
<dictionary xmlns:xi="http://www.w3.org/2001/XInclude"> <xi:include href="file:///System/Library/ScriptingDefinitions/CocoaStandard.sdef" xpointer="xpointer(/dictionary/suite)" /> ...
By using inclusion instead of copying and pasting, your application will automatically stay up to date with changes to the framework. Only include a framework sdef if you also link to that framework; otherwise you run the risk of your application interface disagreeing with what it actually implements.
The following attributes are common to several of the element types described below.
[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.)
access-groups are inherited by document containment. For example, applying an access-group element to a class effectively applies the same rights to all of its property and element elements as well. access-group elements are not inherited by class inheritance or class containment, so in the above example, while a client would be able to get references to elements of the original class, they would not necessarily be able to do anything with them, nor would they necessarily have access to elements defined in subclasses.
Accessor elements are currently only useful for aetes; Cocoa Scripting ignores them and figures out supported forms based on the element's properties.
may have a cocoa element, depending on
how it is implemented: despite its resemblance to an Objective-C
category, the implementation of a
class-extension may in fact be
a subclass. For example, when defining your own document class, the sdef
would extend the standard “document” definition, but the
implementation would be a subclass of
NSDocument. If the implementation is an
Objective-C category, then a cocoa
element is not required; if it is a subclass, then use a
cocoa element with a
‘class’ attribute naming the subclass.
NSDictionaryof parameters, or a KVC key name for a property or element.
NO; for ‘string-value’, any text; and for ‘integer-value’, any integer. You may use at most one of these three attributes in a given cocoa element. The default value is the numeric value of the enumerator's ‘code’ attribute.
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:
<class name="refresh rate">
<property name="current resolution">
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.
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.
contentselement in a class.
In addition, Cocoa Scripting will treat the contents property as its class's implied container: scripts may refer to properties and elements of the contents property as if they belong to 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”.
direct-parameterelement in a verb.
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.
documentationelement may contain any number of
htmlelements, which contain text that will be displayed at that point in the dictionary. The text may contain HTML markup tags, but in order to keep the XML processor from interpreting them as XML, they must be escaped using either entities or a CDATA section, for example:
<documentation> <html> For answers to commonly asked questions about <i>do shell script</i>, see <![CDATA[ <a href="http://developer.apple.com">TN2065</a>. ]]> </html> </documentation>
Bear in mind that an sdef is intended to be a reference, not a tutorial. If you want to include any lengthy material, consider using a link to an external resource.
<enumeration name="save options"> <enumerator name="yes"/> <enumerator name="no"/> <enumerator name="ask"/> </enumeration> <parameter name="saving" type="save options"/>
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:
This attribute only affects the display; it has no semantic meaning.
WARNING: scriptSuite and
scriptTerminology files do not support
record-type elements. You must use an sdef
At least one of ‘name’ or ‘code’ is required. Depending on which attributes are present, the element will have different effects:
synonym elements of
class elements also define a plural name:
this defaults to the name with “s” appended, or may be
explicitly defined using a
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
cocoa elements at the same class.
sdp(1) will do the right thing and
generate a ‘Synonyms’ section for you.
typeattribute may instead have one or more
typeelements. (Using both in the same element is an error.) Using more than one
typeelement indicates that any of the types are allowed; using the ‘list’ attribute indicates a list of the specified type. Using
typeelements, such as to express “list of list of integer”, is not currently supported.
value-typehas no properties and no elements accessible by your scripting; it is useful for defining new basic types, such as an image.
cocoa elements for
value-type elements 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>
sdp(1), /System/Library/DTDs/sdef.dtd, TN2106: Scripting Interface Guidelines ⟨http://developer.apple.com/technotes/tn2002/tn2106.html⟩, Sdef Scriptability Guide for Cocoa ⟨http://developer.apple.com/documentation/Cocoa/Conceptual/ScriptableCocoaApplications⟩.
Changes in OS X 10.10:
documentationelements are more flexible: they may now be placed inside or in between
resultelements; and dictionary display has been improved to display
documentationelements in the order they appear in the document.
class-extensionelements now have an optional
titleattribute used for dictionary display, in particular when displaying multiple extensions of the same class in one suite.
Changes in Mac OS X 10.8:
value-typeelements, and now uses default values as described above.
Changes in Mac OS X 10.5 (Leopard):
htmlelements (children of
documentationelements) are now declared to contain text, not XHTML elements. For example:
Both forms work in 10.4 and 10.5, but the former is now deprecated.
responds-toelements is now called ‘command’, and may be an id or a name.
Changes in Mac OS X 10.4 (Tiger):
propertiesno longer exist. Their former children should be moved to their immediate ancestor element. In general, children may be freely mixed now. For example, placing a
commandelement next to a
classelement is perfectly acceptable.
typeelements, not complex strings. For example:
<property name="tabs" type="list of integer"/>
<property name="tabs"> <type type="integer" list="yes"/> </property>
<property name="frequency" type="number|
<property name="frequency"> <type type="number"/> <type type="text"/> </property>
See the type documentation for complete details.
hidden, now accept ‘yes’ and ‘no’ as values (formerly the attribute name, e.g. ‘hidden="hidden"’).
not-in-propertiesattribute is now named
in-properties; its possible values are ‘yes’ (the default) and ‘no’.
elementelements now use a ‘key’ attribute (formerly ‘method’).
elementelements is now the type's plural (formerly its name).
|June 17, 2021||Mac OS X|