| SDEF(5) | File Formats Manual | SDEF(5) |
sdef — scripting
definition file
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
section.
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)
suite+
class |
class-extension |
command |
enumeration |
event |
record-type |
value-type) +enumeration
record-type
class
|
class-extension
command
|
event
The elements listed above may also contain
documentation,
implementation, synonym,
xref and access-group
elements, as noted here:
xrefclass,
class-extension, command,
enumeration, event,
record-type, and
value-type.suite,
class, class-extension,
command, element,
property, contents, and
responds-to.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.
name[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.)idcodetypedescriptionaccess-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.
A class-extension
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.
CommandClass of verbs.NSDictionary of
parameters, or a KVC key name for a property or element.YES or
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"><element
type="monitor">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.
WARNING: The above is correct for sdp(1), but not for Cocoa Scripting. See Bugs.
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.
contents element 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-parameter element 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.
documentation element. A
documentation element may contain any number of
html elements, 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
file directly.
At least one of ‘name’ or ‘code’ is required. Depending on which attributes are present, the element will have different effects:
Named 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 plural
attribute.
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
cocoa elements at the same class.
sdp(1) will do the right thing and
generate a ‘Synonyms’ section for you.
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.
value-type has 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>
/Developer/Examples/AppKit/Sketch.
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:
documentation
elements are more flexible: they may now be placed inside or in between
parameter,
direct-parameter, and
result elements; and dictionary display has been
improved to display documentation elements in the
order they appear in the document.class-extension
elements now have an optional title attribute used
for dictionary display, in particular when displaying multiple extensions
of the same class in one suite.Changes in Mac OS X 10.8:
access-group elements.cocoa elements
for class, parameter,
responds-to, and
value-type elements, and now uses default values
as described above.Changes in Mac OS X 10.5 (Leopard):
xref elements.html
elements (children of documentation
elements) 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-to
elements is now called ‘command’, and may be an id or a
name.Changes in Mac OS X 10.4 (Tiger):
classes, types, and
properties no 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
command element next to a
class element is perfectly acceptable.type
elements, 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 |
text"/><property name="frequency">
<type type="number"/>
<type type="text"/>
</property>
See the type documentation for complete details.
optional and
hidden, now accept ‘yes’ and
‘no’ as values (formerly the attribute name, e.g.
‘hidden="hidden"’).not-in-properties attribute is now named
in-properties; its possible values are
‘yes’ (the default) and ‘no’.cocoa
elements of property and
element elements now use a ‘key’
attribute (formerly ‘method’).element elements is now
the type's plural (formerly its name).| June 17, 2021 | Mac OS X |