4. Getting Help

When developing appscript-based scripts, there are several ways to get information about applications' scripting interfaces: the ASDictionary application and its bundled asdict command-line tool, appscript's powerful built-in help method, and introspection.

ASDictionary

ASDictionary, available from the appscript website's Downloads page, provides a convenient GUI interface for exporting application terminology resources in plain text and HTML formats. ASDictionary can export HTML dictionaries in both single-file format and a frame-based format similar to rdoc's.

In addition, the asdict tool bundled with ASDictionary can be used to export application dictionaries in HTML format, or browse them interactively from the command line. See ASDictionary's documentation for more information.

Built-in help method

Appscript's Application and Reference classes include a powerful interactive help system that allows you to explore applications' scripting interfaces from within running scripts and Ruby's interactive irb interpreter. The help method can provide information on any suite, class, command or reference, and display the inheritance and relationships for a selected class or the entire application.

Built-in help is invoked by calling an app object's help method, optionally passing it a string indicating the type of information you want. The resulting help message is printed to stderr and script execution continues as normal. For example, to view the help system's own help, call the help method with '-h' as its argument:

app('TextEdit').help('-h')

To print a description of any class or command or view inheritance and relationships, pass the help method a help string containing one or more of the following options:

-h

show help

-o

overview of all suites, classes and commands

-k

list all built-in keywords (type names)

-u [suite-name]

summary of named suite or all suites

-t [class-or-command-name]

terminology for named class/command or current reference

-i [class-name]

inheritance tree for named class or all classes

-r [class-name]

one-to-one and one-to-many relationships for named class or current reference

-s [property-or-element-name]

values of properties and elements of object(s) currently referenced

Arguments (shown in brackets) are optional. Additional information on usage is available via help('-h').

Examples:

app('Finder').help('-o')
app('Finder').help('-t window')
app('Finder').files.help # same as help('-t')
app('Finder').help('-d item -r folder -i container')
app('Finder').files.help('-s')

To print detailed information on a specific reference, call its help method without arguments. Examples:

app('TextEdit').help
app('TextEdit').version.help
app('TextEdit').documents.help

To print detailed information on a specific command, call the help method on an application or reference object with the -t option followed by the command's name. Examples:

app('TextEdit').help('-t open')
app('TextEdit').documents.help('-t count -t close')

c = app('TextEdit').help.help('-o -i -s').documents.help[1].help.count

Introspection

In addition to supporting Ruby's standard #methods and #respond_to? methods, appscript's Application and Reference classes also define several instance methods for obtaining information on the target application:

properties

Returns a list of all property names.

elements

Returns a list of all element names.

commands

Returns a list of all command names.

keywords

Returns a list of all class, enumerator, type and property names.

parameters(commandName)

Takes a command's name as string and returns the names of its parameters.

As with Ruby's Object#methods, all of these methods return a list of strings.

Examples

te = app('TextEdit')

p te.commands
# ["activate", "close", "count", "delete", "duplicate", "exists", ...]

p te.parameters('make')
# ["at", "new", "with_data", "with_properties"]

Notes

While appscript's documentation systems try to be reasonably forgiving of flawed or faulty terminology resources, there may be a few particularly problematic applications on which they fail. Should this happen, use ASDictionary to export the application's terminology in plain text format instead.

Other sources of help

• The sample folder contains example scripts demonstrating a range of common tasks.
• Refer to any scripting documentation and example scripts supplied by the application developer.
• Look for third-party scripts that provide examples of use (though many of these scripts will be written in AppleScript rather than Ruby).
• The rb-appscript website has links to mailing lists and other general resources.