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:
Name | Class | Description |
---|---|---|
:wait_reply | Boolean | Wait for application to return a result/error? |
:timeout | Integer | Number of seconds to wait for a reply (no timeout = 0) |
:result_type | nil | Symbol | AE type to coerce return value to (e.g. :FSRef ) |
:ignore | nil | Array of Symbol | String 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:
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.
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
).When the
set
command is called on a reference, itsto
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.
If the
make
command is called on an insertion location reference, appscript will pack that reference as the Apple event'sat
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 themake
command'sat
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]]