rb-appscript

11. Application Commands

Command syntax

Appscript commands have the following syntax:

application.command_name([direct_parameter][, keyword_parameters])

Both direct and keyword parameters are optional.

Application commands are implemented by the application's top-level application object (represented by an Appscript::Application instance). For convenience, appscript also makes application commands available as methods on every reference. If a command is called upon a reference rather than an Application object, that reference will be taken as the application's direct parameter (with one or two caveats; see the Special Cases section below).

The command's direct parameter can be any value; the application's dictionary will (usually) indicate the appropriate types. A command can have a maximum of one direct parameter; if more than one is given, an error will occur. Keyword parameters are specified as a Hash object whose keys are symbols representing the parameter names:

application.command_name(direct_parameter, {:name1 => value1, :name2 => value2, ...})

Note that Ruby allows the hash to be written without the enclosing { and } for appearance's sake:

application.command_name(direct_parameter, :name1 => value1, :name2 => value2, ...)

Each command can have zero or more keyword parameters as defined in the application dictionary. In addition, appscript provides the following default parameters for indicating how the command should be handled:

NameClassDescription
:wait_replyBooleanWait for application to return a result/error?
:timeoutIntegerNumber of seconds to wait for a reply (no timeout = 0)
:result_typenil | SymbolAE type to coerce return value to (e.g. :FSRef)
:ignorenil | Array of SymbolString characteristics to ignore when evaluating references. The array should contain zero or more of the following enumerators: :case, :diacriticals, :expansion, :hyphens, :punctuation, :whitespace

(Note that most applications currently ignore the :ignore parameter and use the default behaviour, i.e. ignore case.)

For convenience, appscript allows the direct parameter and/or keyword parameters arguments to be omitted from the method's argument list if unused. For example, a command that has no direct or keyword parameters would be written as:

application.command_name

If the command takes only keyword parameters, or the direct parameter is the reference upon which the command is called, it can be written as:

application.command_name(:name1 => value1, :name2 => value2, ...)

If the command takes only a direct parameter and the value given is not a hash, then it can be written as follows:

application.command_name(direct_parameter)

If the direct parameter is a Ruby hash, you must provide an empty keyword parameters hash as the second argument to the call:

application.command_name(direct_hash_parameter, {})

If you forget, appscript will treat this hash value as the command's keyword parameters, resulting in an error or other unexpected behaviour.

See the Special cases section below for additional rules.

Examples

# tell application "TextEdit" to activate
app('TextEdit').activate

# tell application "TextEdit" to open fileRefList
app('TextEdit').open(fileRefList)

# tell application "Finder" to get version
app('Finder').version.get

# tell application "Finder" to set name of file "foo.txt" of home to "bar.txt"
app('Finder').home.files['foo.txt'].name.set('bar.txt')

# tell application "TextEdit" to count (text of first document) each paragraph
app('TextEdit').documents.first.text.count(:each => :paragraph)

# tell application "TextEdit" to make new document at end of documents
app('TextEdit').documents.end.make(:new => :document)

# tell application "Finder" to get items of home as alias list
app('Finder').home.items.get(:result_type => :alias)

Special cases

The following special-case behaviours are implemented for convenience:

  1. Commands that take a reference to one or more application objects as a direct parameter may be written in the following form:

    reference.command(keyword_parameters)

    The conventional form is also supported should you ever wish (or need) to use it:

    application.command(reference, keyword_parameters)

    The two forms are equivalent (appscript converts the first form to the second behind the scenes) although the first form is preferred for conciseness.

  2. If a command that already has a direct parameter is called on a reference, i.e.:

    reference.command(direct_parameter[, keyword_parameters])

    the reference upon which it is called will be packed as the Apple event's 'subject' attribute (keySubjectAttr).

  3. When the set command is called on a reference, its to parameter can be written as a direct parameter; i.e.:

    reference.set(value)

    instead of:

    reference.set(:to => value)

    or:

    application.set(reference, :to => value)

    The first form is preferred, although all three are supported.

  4. If the make command is called on an insertion location reference, appscript will pack that reference as the Apple event's at parameter if it doesn't already have one; i.e.:

    insertion_location.make(:new => some_class)

    is equivalent to:

    application.make(:new => some_class, :at => insertion_location)

    If the make command is called on an object reference, appscript will pack that reference as the Apple event's 'subject' attribute. (Note that some applications may not handle the subject attribute correctly, in which case the reference should be passed as the make command's at parameter instead.)

Command errors

The Appscript::CommandError exception describes an error raised by the target application or Apple Event Manager when sending a command.

CommandError < RuntimeError

    Methods:
        
        error_number : FixNum -- Mac OS error number
        
        error_message : String -- application-supplied/generic error description
        
        offending_object : anything | nil -- object that caused the error, 
                                             if given by application
        
        expected_type : anything | nil -- object that caused a coercion error, 
                                          if given by application
        
        partial_result : anything | nil -- part of return value constructed 
                                           before error occurred, if given 
                                           by application
        
        to_i : FixNum -- equivalent to #error_number

        to_s : String -- formatted error information

Note to AppleScript users

Unlike AppleScript, which implicitly sends a get command to any unresolved application object references at the end of evaluating an expression, appscript only resolves a reference when it receives an appropriate command. For example:

d = app('TextEdit').documents

is not the same as:

set d to documents of app "TextEdit"

even though the two may look similar. In the first case, the value assigned to d is an appscript reference: app('TextEdit').documents. In the second, AppleScript evaluates the documents of app "TextEdit" reference by performing an implicit get command and then assigning its result, a list of references to individual documents, to d. To obtain the original reference as an AppleScript value, the literal reference must be preceded by an a reference to operator as shown below.

To get a single reference to all documents:

set d to a reference to documents of app "TextEdit"
return d
--> a reference to documents of app "TextEdit"


d = app('TextEdit').documents
print d
--> app('TextEdit').documents

To get a list of references to each document:

set d to get documents of app "TextEdit" -- (explicit 'get' is optional)
return d
--> {document 1 of app "TextEdit", document 2 of app "TextEdit"}


d = app('TextEdit').documents.get -- (explicit 'get' is required)
print d
--> [app('TextEdit').documents[1], app('TextEdit').documents[2]]