about an application's scriptability: terminology, implementation infor-
mation, 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 cre-
ate 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 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. (However, also see the Bugs
section.)
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 imple-
mentation element is the cocoa element.
The element structure of an sdef is as follows. Indentation shows con-
tainment, and `*', `+', and `?' have their usual EBNF meanings: `*' means
zero or more, `+' means one or more, and `?' means zero or one (i.e.,
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 ele-
ment. 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. ``Character'' is something of
a misnomer; a four-character code is really four bytes of
data that can be expressed as a string of four characters in
the MacRoman encoding. If one of the bytes would be an
unprintable character, use an entity reference with the
appropriate code point. For example, the code 0x00000001
would be written as ���.
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.
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 parame-
ters, or a KVC key name for a property or ele-
ment.
method An Objective-C method name: use for responds-
to methods.
name A name used internally by Cocoa Scripting: use
for suites, command and event key names, enu-
merations, and enumerators.
cocoa elements are optional; if omitted, sdp(1) will gener-
ate a default name. The basic rule is to capitalize each
scriptSuite files as the CommandClass; the default is always
NSScriptCommand. An explicit cocoa element is only neces-
sary if you want to override these defaults.
WARNING: The above is correct for sdp(1), but not for Cocoa
Scripting. See Bugs.
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 pro-
grammers, 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 data-
base.
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', respec-
tively.
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+
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 parame-
ter'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:
o 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.)
o 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.
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 in-
line. 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 enumer-
ators 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.
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 auto-
matic 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.
WARNING: scriptSuite and scriptTerminology files do not sup-
port record-type elements. You must use an sdef file
directly.
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.
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 dif-
ferent 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 cor-
rect 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 ele-
ment 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
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 Guide-
lines <http://developer.apple.com/technotes/tn2002/tn2106.html>, Sdef
Scriptability Guide for Cocoa
<http://developer.apple.com/documentation/Cocoa/Conceptual/ScriptableCocoaApplications>.
o code attributes used to support hex constants (such as
``0x1234abcd'') for their value. Use entity references (such as
�) or literal characters instead. Remember that the character
will be translated to a byte using MacRoman encoding, not Unicode, so
the code point may be entirely different from the resulting byte.
For example, to get a 0xBD (a capital omega in MacRoman), you would
use Ω.
o 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.
o Boolean attributes, that is, optional and hidden, now accept `yes'
and `no' as values (formerly the attribute name, e.g.
`hidden="hidden"').
o The not-in-properties attribute is now named in-properties; its pos-
sible values are `yes' (the default) and `no'.
o cocoa elements of property and element elements now use a `key'
attribute (formerly `method').
o The default Cocoa key for element elements is now the type's plural
(formerly its name).
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
BUGS
Cocoa Scripting in Tiger supports direct use of sdefs, but does a few
Man(1) output converted with
man2html
|