11. Application commands
Command syntax
For convenience, appscript makes application commands available as methods on every reference. (Note: due to the limitations of aete-based terminology, the user must determine for themselves which commands can operate on a particular reference. Some applications document this information separately.)
reference.command_name(*arg, **args, waitreply=True,
timeout=60, resulttype=None, ignore=None)
*arg : anything -- direct arg, if any
**kwargs : anything -- labelled arg(s), if any
waitreply : bool -- wait for application to return a result/error?
canaskforconsent : bool -- can appscript ask user for permission
if needed to control target application?
timeout : int -- no. of seconds to wait for a reply
resulttype : None | Keyword -- AE type to coerce return value to
ignore : None | list of Keyword -- string characteristics to ignore
when evaluating references
Result : anything -- value returned by application, if any
- *arg
- An application command can have either zero or one direct parameters. The application's dictionary indicates which commands take a direct parameter, and if it is optional or required.
- **kwargs
- An application command can have zero or more labelled parameters. The application's dictionary describes the labelled parameters for each command, and if they are optional or required.
- waitreply
- If
True
(the default), appscript will wait for the application to reply to the command. IfFalse
, it will return as soon as the command is sent, ignoring any return values or application errors. - canaskforconsent
- In macOS 10.14+, if
True
(the default), allows the process running this script to ask the user for permission to control the target application when sending its first command. IfFalse
, the command will only be sent if permission has previously been granted, otherwise an error -1744 (event would require users consent) will occur. Ignored in 10.13 and earlier. Note that this option only applies to commands defined by the application. The standard commands recognized by all Mac applications (run
,open
,quit
, etc.) are not affected. See the System Integrity Protection section in Chapter 14 for more information. - timeout
- The number of seconds to wait for the application to reply before raising a timeout error. The default is 60 seconds but may be increased or decreased as needed; Use 0 to wait indefinitely. For example, a longer timeout may be needed to prevent a timeout error occurring during a particularly long-running application command. Note: due to a quirk in the Apple Event Manager API, timeout errors may be reported as either error -1712 (the Apple event timed out) or -609 (connection invalid, which is also raised when an application unexpectedly quits while handling a command).
- resulttype
- Some applications may allow the return value's type to be specified for certain commands (typically
get
). For example, the Finder'sget
command returns filesystem references as alias objects if the resulttype isk.alias
. - ignore
- Some applications may allow the client to specify text attributes that should be considered or ignored when performing string comparisons, e.g. when resolving by-test references. When specifying the attributes to ignore, the list should contain zero or more of the following enumerators:
k.case
,k.diacriticals
,k.expansion
,k.hyphens
,k.punctuation
,k.whitespace
. Note that most applications currently ignore this setting and always use the default behaviour, which is to ignore case but consider everything else.
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=k.paragraph)
# tell application "TextEdit" to make new document at end of documents
app('TextEdit').documents.end.make(new=k.document)
# tell application "Finder" to get items of home as alias list
app('Finder').home.items.get(resulttype=k.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
).The
set
command may pass itsto
parameter as a direct rather than labelled argument if there is no other direct parameter and no other labelledto
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=class)
is equivalent to:
application.make(new=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.)Calling a reference directly is equivalent to invoking its
get
command. For example:reference()
is the same as:
reference.get()
Command errors
The appscript.CommandError
exception describes an error raised by the target application or Apple Event Manager when sending a command.
CommandError(Exception)
Properties:
errornumber : int -- Mac OS error number
errormessage : str -- application-supplied/generic error description
offendingobject : anything | None -- object that caused the error,
if given by application
expectedtype : anything | None -- object that caused a coercion error,
if given by application
partialresult : anything | None -- part of return value constructed
before error occurred, if given
by application
Methods:
__int__() -- Mac OS error number
__str__() -- formatted description of error
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]]