Control Statements Reference
This chapter describes AppleScript control statements. A control statement is a statement that determines when and how other statements are executed or how expressions are evaluated. For example, a control statement may cause AppleScript to skip or repeat certain statements.
Simple statements can be written on one line, while compound statements can contain other statements, including multiple clauses with nested and multi-line statements. A compound statement is known as a statement block.
Compound statements begin with one or more reserved words, such as tell
, that identify the type of control statement. The last line of a compound statement always starts with end
, and can optionally include the word that begins the control statement (such as end tell
).
considering and ignoring Statements
The considering
and ignoring
statements cause AppleScript to consider or ignore specific characteristics as it executes groups of statements. There are two kinds of considering
and ignoring
statements:
Those that specify attributes to be considered or ignored in performing text comparisons.
Those that specify whether AppleScript should consider or ignore responses from an application.
Specify how AppleScript should treats attributes, such as case, in performing text comparisons.
Syntax
|
Placeholders
- attribute
A characteristic of the text:
case
If this attribute is ignored, uppercase letters are not distinguished from lowercase letters. See Special Considerations below for related information. See also
greater than, less than
for a description of how AppleScript sorts letters, punctuation, and other symbols.diacriticals
If this attribute is ignored,
text
objects are compared as if no diacritical marks (such as ´, `, ˆ, ¨, and ˜) are present; for example,"résumé"
is equal to"resume"
.hyphens
If this attribute is ignored,
text
objects are compared as if no hyphens are present; for example"anti-war"
is equal to"antiwar"
.numeric strings
By default, this attribute is ignored, and text strings are compared according to their character values. For example, if this attribute is considered,
"1.10.1" > "1.9.4"
evaluates astrue
; otherwise it evaluates asfalse
. This can be useful in comparing version strings.punctuation
If this attribute is ignored,
text
objects are compared as if no punctuation marks (such as. , ? : ; ! ' "
) are present; for example"What? he inquired."
is equal to"what he inquired"
.white space
If this attribute is ignored, the
text
objects are compared as if spaces, tab characters, and return characters were not present; for example"Brick house"
would be considered equal to"Brickhouse"
.
- Default Value:
- Case and numeric strings are ignored; all others are considered.
- statement
Any AppleScript statement.
Examples
The following examples show how considering
and ignoring
statements for various attributes can change the value of text comparisons.
"Hello Bob" = "HelloBob" --result: false |
ignoring white space |
"Hello Bob" = "HelloBob" --result: true |
end ignoring |
"BOB" = "bob" --result: true |
considering case |
"BOB" = "bob" --result: false |
end considering |
"a" = "á" --result: false |
ignoring diacriticals |
"a" = "á" --result: true |
end considering |
"Babs" = "bábs" --result: false |
ignoring case |
"Babs" = "bábs" --result: false |
end ignoring |
ignoring case and diacriticals |
"Babs" = "bábs" --result: true |
end ignoring |
Discussion
You can nest considering
and ignoring
statements. If the same attribute appears in both an outer and inner statement, the attribute specified in the inner statement takes precedence. When attributes in an inner considering
or ignoring
statement are different from those in outer statements, they are added to the attributes to be considered and ignored.
Special Considerations
Because text item delimiters
(described in version) respect considering
and ignoring
attributes in AppleScript 2.0, delimiters are case-insensitive by default. Formerly, they were always case-sensitive. To enforce the previous behavior, add an explicit considering case
statement.
considering
and ignoring
are fully Unicode-aware. For example, with ignoring case
, “Горбач” is equal to “ГОРБАЧ”. Also, the characters ignored by diacriticals, hyphens, punctuation, and white space are defined by Unicode character classes:
ignoring punctuation
ignores category P*, which includes left- and right-quotation marks such as“ ” « »
.ignoring hyphens
ignores category Pd, which includes em- and en-dashes.ignoring whitespace
ignores category Z*, plus tab (\t), return (\r), and linefeed (\n), which includes em-, en-, and non-breaking spaces.
Para
Permits a script to continue without waiting for an application to respond to commands that target it.
Syntax
|
Placeholders
- statement
Any AppleScript statement.
Examples
The following example shows how to use an ignoring statement so that a script needn’t wait while Finder is performing a potentially lengthy task:
tell application "Finder" |
ignoring application responses |
empty the trash |
end ignoring |
end tell |
Your script may want to ignore most responses from an application, but wait for a response to a particular statement. You can do so by nesting considering
and ignoring
statements:
tell application "Finder" |
ignoring application responses |
empty the trash |
-- other statements that ignore application responses |
considering application responses |
set itemName to name of first item of startup disk |
end considering |
-- other statements that ignore application responses |
end ignoring |
end tell |
Discussion
A response to an application command indicates whether the command completed successfully, and also returns results and error messages, if there are any. When you use an ignoring application responses
block, you forego this information.
Results and error messages from AppleScript commands, scripting additions, and expressions are not affected by the application responses
attribute.
error Statements
During script execution, errors can occur in the operating system (for example, when a specified file isn’t found), in an application (for example, when the script specifies an object that doesn’t exist), and in the script itself. An error message is a message that is supplied by an application, AppleScript, or macOS when an error occurs during the handling of a command. An error message can include an error number, which is an integer that identifies the error; an error expression, which is an expression, usually a text
object, that describes the error; and other information.
A script can signal an error—which can then be handled by an error handler—with the error
statement. This allows scripts to supply their own messages for errors that occur within the script. For example, a script can prepare to handle anticipated errors by using a try
statement. In the on error
branch of a try
statement, a script may be able to recover gracefully from the error. If not, it can use an error
statement to resignal the error message it receives, modifying the message as needed to supply information specific to the script.
Signals an error in a script.
Syntax
|
Placeholders
- errorMessage
A
text
object describing the error. Although this parameter is optional, you should provide descriptions for errors wherever possible. If you do not include an error description, an emptytext
object ("") is passed to the error handler.- errorNumber
The error number for the error. This is an optional parameter. If you do not include a number parameter, the value -2700 (unknown error) is passed to the error handler.
If the error you are signaling is a close match for one that already has an AppleScript error constant, you can use that constant. If you need to create a new number for the error, avoid using one that conflicts with error numbers defined by AppleScript, macOS, and the Apple Event Manager. In general, you should use positive numbers from 500 to 10,000. For more information, see Error Numbers and Error Messages.
- resultList
A list of objects. Applies only to commands that return results for multiple objects. If results for some, but not all, of the objects specified in the command are available, you can include them in the partial result parameter. This is rarely supported by applications.
- offendingObject
A reference to the object, if any, that caused the error.
- expectedType
A class. If a parameter specified in the command was not of the expected class, and AppleScript was unable to coerce it to the expected class, then you can include the expected class in the
to
parameter.
Examples
The following example uses a try
statement to handle a simple error, and demonstrates how you can use an error
statement to catch an error, then resignal the error exactly as it was received, causing AppleScript to display an error dialog (and halt execution):
try |
word 5 of "one two three" |
on error eStr number eNum partial result rList from badObj to expectedType |
-- statements that take action based on the error |
display dialog "Doing some preliminary handling..." |
-- then resignal the error |
error eStr number eNum partial result rList from badObj to expectedType |
end try |
In the next example, an error
statement resignals an error, but omits any original error information and supplies its own message to appear in the error dialog:
try |
word 5 of "one two three" |
on error |
-- statements to execute in case of error |
error "There are not enough words." |
end try |
For more comprehensive examples, see Working with Errors.
if Statements
An if
statement allows you to define statements or groups of statements that are executed only in specific circumstances, based on the evaluation of one or more Boolean expressions.
An if
statement is also called a conditional statement. Boolean expressions in if
statements are also called tests.
Executes a statement if a Boolean expression evaluates to true
.
Syntax
|
Placeholders
- boolean
A Boolean expression.
- statement
Any AppleScript statement.
Examples
This script displays a dialog if the value of the Boolean expression ageOfCat > 1
is true
. (The variable ageOfCat
is set previously.)
if ageOfCat > 1 then display dialog "This is not a kitten." |
Executes a group (or groups) of statements if a Boolean expression (or expressions) evaluates to true
.
Syntax
|
Placeholders
- boolean
A Boolean expression.
- statement
Any AppleScript statement.
Examples
The following example uses a compound if
statement, with a final else
clause, to display a statement based on the current temperature (obtained separately):
if currentTemp < 60 then |
set response to "It's a little chilly today." |
else if currentTemp > 80 then |
set response to "It's getting hotter today." |
else |
set response to "It's a nice day today." |
end if |
display dialog response |
Discussion
An if
statement can contain any number of else if
clauses; AppleScript looks for the first Boolean expression contained in an if
or else if
clause that is true
, executes the statements contained in its block (the statements between one else if
and the following else if
or else
clause), and then exits the if
statement.
An if
statement can also include a final else
clause. The statements in its block are executed if no other test in the if
statement passes.
repeat Statements
You use a repeat
statement to create loops or execute groups of repeated statements in scripts.
There are a number of types of repeat
statement, each differing in the way it terminates the loop. Each of the options, from repeating a loop a specific number of times, to looping over the items in a list, to looping until a condition is met, and so on, lends itself to particular kinds of tasks.
For information on testing and debugging repeat
statements, see Debugging AppleScript Scripts.
Terminates a repeat
loop and resumes execution with the statement that follows the repeat
statement.
You can only use an exit
statement inside a repeat
statement. Though most commonly used with the repeat (forever)
form, you can also use an exit
statement with other types of repeat
statement.
Syntax
|
Examples
See the example in repeat (forever)
.
Repeats a statement (or statements) until an exit
statement is encountered.
To terminate a repeat
(forever) statement, you can:
Use an
exit
statement and design the logic so that it eventually encounters theexit
statement.Use a
return
statement, which exits the handler or script that contains the loop, and therefore the loop as well.Use a
try
statement and rely on an error condition to exit the loop.
Syntax
|
Placeholders
- statement
-
Any AppleScript statement.
Examples
This form of the repeat
statement is similar to the repeat until
form, except that instead of putting a test in the repeat
statement itself, you determine within the loop when it is time to exit. You might use this form, for example, to wait for a lengthy or indeterminate operation to complete:
repeat |
-- perform operations |
if someBooleanTest then |
exit repeat |
end if |
end repeat |
In a script application that stays open, you can use an idle
handler to perform periodic tasks, such as checking for an operation to complete. See idle Handlers for more information.
Repeats a statement (or statements) a specified number of times.
Syntax
|
Placeholders
- integer
-
Specifies the number of times to repeat the statements in the body of the loop.
Instead of an integer, you can specify any value that can be coerced to an integer.
If the value is less than one, the body of the
repeat
statement is not executed. - statement
-
Any AppleScript statement.
Examples
The following handler uses the repeat (number) times
form of the repeat
statement to raise a passed number to the passed power:
on raiseToTheNth(x, power) |
set returnVal to x |
repeat power - 1 times |
set returnVal to returnVal * x |
end repeat |
return returnVal |
end raiseToTheNth |
Repeats a statement (or statements) until a condition is met. Tests the condition before executing any statements.
Syntax
|
Placeholders
- boolean
A Boolean expression. If it has the value
true
when entering the loop, the statements in the loop are not executed.- statement
Any AppleScript statement.
Examples
The following example uses the repeat until
form of the repeat
statement to allow a user to enter database records. The handler enterDataRecord()
, which is not shown, returns true
if the user is done entering records:
set userDone to false |
repeat until userDone |
set userDone to enterDataRecord() |
end repeat |
Repeats a statement (or statements) as long as a condition is met. Tests the condition before executing any statements. Similar to the repeat until
form, except that it continues while a condition is true
, instead of until it is true
.
Syntax
|
Placeholders
- boolean
A Boolean expression. If it has the value
false
when entering the loop, the statements in the loop are not executed.- statement
Any AppleScript statement.
Examples
The following example uses the repeat while
form of the repeat
statement to allow a user to enter database records. In this case, we’ve just reversed the logic shown in the repeat until
example. Here, the handler enterDataRecord()
, which is not shown, returns true
if the user is not done entering records:
set userNotDone to true |
repeat while userNotDone |
set userNotDone to enterDataRecord() |
end repeat |
Repeats a statement (or statements) until the value of the controlling loop variable exceeds the value of the predefined stop value.
Syntax
|
Placeholders
- loopVariable
Controls the number of iterations. It can be a previously defined variable or a new variable you define in the
repeat
statement.- startValue
Specifies a value that is assigned to loopVariable when the loop is entered.
You can specify an integer or any value that can be coerced to an integer.
- stopValue
Specifies an value. When that value is exceeded by the value of loopVariable, iteration ends. If stopValue is less than startValue, the body is not executed.
You can specify an integer or any value that can be coerced to an integer.
- stepValue
Specifies a value that is added to loopVariable after each iteration of the loop. You can assign an
integer
or areal
value; areal
value is rounded to aninteger
.- Default Value:
- 1
- statement
Any AppleScript statement.
Examples
The following handler uses the repeat with loopVariable (from startValue to stopValue)
form of the repeat
statement to compute a factorial value (the factorial of a number is the product of all the positive integers from 1 to that number):
on factorial(x) |
set returnVal to 1 |
repeat with n from 2 to x |
set returnVal to returnVal * n |
end repeat |
return returnVal |
end factorial |
Discussion
You can use an existing variable as the loop variable in a repeat with loopVariable (from startValue to stopValue)
statement or define a new one in the statement. In either case, the loop variable is defined outside the loop. You can change the value of the loop variable inside the loop body but it will get reset to the next loop value the next time through the loop. After the loop completes, the loop variable retains its last value.
AppleScript evaluates startValue, stopValue, and stepValue when it begins executing the loop and stores the values internally. As a result, if you change the values in the body of the loop, it doesn’t change the execution of the loop.
Loops through the items in a specified list.
The number of iterations is equal to the number of items in the list. In the first iteration, the value of the variable is a reference to the first item in list, in the second iteration, it is a reference to the second item in list, and so on.
Syntax
|
Placeholders
- loopVariable
Any previously defined variable or a new variable you define in the
repeat
statement (see Discussion).- list
A list or a object specifier (such as
words 1 thru 5
) whose value is a list.list can also be a record; AppleScript coerces the record to a list (see Discussion).
- statement
Any AppleScript statement.
Examples
The following script uses the repeat with loopVariable (in list)
form of the repeat
statement to loop through a list of first names, displaying a greeting for each.
set peopleList to {"Chris", "David", "Sal", "Ben"} |
repeat with aPerson in peopleList |
display dialog "Hello " & aPerson & "!" |
end repeat |
Discussion
You can use an existing variable as the loop variable in a repeat with loopVariable (in list)
statement or define a new one in the repeat with…
statement. In either case, the loop variable is assigned a new value—the current item in the loop—at the start of each loop. After the loop completes, the loop variable retains its last value.
This example uses an existing variable as the loop variable:
set currentIncrement to 0 |
-- The loop variable is an existing variable, defined above |
repeat with currentIncrement in {1, 2, 3, 4} |
-- Do something |
end repeat |
currentIncrement |
--result: item 4 of {1, 2, 3, 4} --result: the last value of the loop variable |
This example defines a new variable as the loop variable:
-- The loop variable is a new variable, defined in the repeat statement |
repeat with currentIncrement in {1, 2, 3, 4} |
-- Do something |
end repeat |
currentIncrement |
--result: item 4 of {1, 2, 3, 4} --result: the last value of the loop variable |
You can change the value of the loop variable inside the loop body, but it gets reset to the next loop value the next time through the loop. Again, after the loop completes, the loop variable retains its last value.
repeat with currentIncrement in {1, 2, 3, 4} |
display dialog currentIncrement |
set currentIncrement to 0 |
end repeat |
currentIncrement |
--result: 0 |
AppleScript evaluates loopVariable in
list as an object specifier—a reference to the current item in the list—that takes on the value of item 1 of list
, item 2 of list
, item 3 of list
, and so on until it reaches the last item in the list. For example:
repeat with i in {1, 2, 3, 4} |
set listItem to i |
end repeat |
--result: item 4 of {1, 2, 3, 4} --result: an object specifier |
To access the actual value of an item in the list, rather than a reference to the item, use the contents of
property:
repeat with i in {1, 2, 3, 4} |
set listItem to contents of i |
end repeat |
--result: 4 |
This technique is especially important when performing a comparison, as you typically want to test whether the value of a list item matches another value. The following script examines a list of words, displaying a dialog if it finds the word “hammer” in the list. To perform a proper comparison, the test statement (if (contents of currentWord) is equal to "hammer" then
) compares the contents
of the current list item, rather than the object specifier itself.
set wordList to words in "Where is the hammer?" |
repeat with currentWord in wordList |
log currentWord |
if (contents of currentWord) is equal to "hammer" then |
display dialog "I found the hammer!" |
end if |
end repeat |
You can also use list variables directly in expressions, which may result in an implicit coercion from an object reference to a specific data type. In the following example, the loop variable i
is implicitly coerced to an integer (equivalent to explicitly retrieving the contents of i
) by using the +
operator to add it to a variable containing an integer.
set total to 0 |
repeat with i in {1, 2, 3, 4} |
set total to total + i |
end repeat |
--result: 10 |
tell Statements
A tell
statement specifies the default target—that is, the object to which commands are sent if they do not include a direct parameter. Statements within a tell
statement that use terminology from the targeted object are compiled against that object’s dictionary.
The object of a tell
statement is typically a reference to an application object or a script
object. For example, the following tell
statement targets the Finder application:
tell application "Finder" |
set frontWindowName to name of front window |
-- any number of additional statements can appear here |
end tell |
You can nest tell
statements inside other tell
statements, as long as you follow the syntax and rules described in tell (compound)
.
When you need to call a handler from within a tell
statement, there are special terms you use to indicate that the handler is part of the script and not a command that should be sent to the object of the tell
statement. These terms are described in The it and me Keywords and in Calling Handlers in a tell Statement.
A tell
statement that targets a local application doesn’t cause it to launch, if it is not already running. For example, a script can examine the running
property of the targeted application
object to determine if the application is running before attempting to send it any commands. If it is not running it won’t be launched.
If a tell
statement targets a local application and executes any statements that require a response from the application, then AppleScript will launch the application if it is not already running. The application is launched as hidden, but the script can send it an activate
command to bring it to the front, if needed.
A tell
statement that targets a remote application will not cause it to launch—in fact, it will not compile or run unless the application is already running. Nor is it possible to access the running
property of an application on a remote computer.
Specifies a target object and a command to send to it.
Syntax
|
Placeholders
- referenceToObject
-
Any object. Typically an object specifier or a
reference
object (which contains an object specifier). - statement
-
Any AppleScript statement.
Examples
This simple tell
statement closes the front Finder window:
tell front window of application "Finder" to close |
For more information on how to specify an application object, see the application
class.
Specifies a target object and one or more commands to send to it. A compound tell
statement is different from a simple tell
statement in that it always includes an end
statement.
Syntax
|
Placeholders
- referenceToObject
Any object. Typically an object specifier or a
reference
object (which contains an object specifier).- statement
-
Any AppleScript statement, including another
tell
statement.
Examples
The following statements show how to close a window using first a compound tell
statement, then with two variations of a simple tell
statement:
tell application "Finder" |
close front window |
end tell |
tell front window of application "Finder" to close |
tell application "Finder" to close front window |
The following example shows a nested tell
statement:
tell application "Finder" |
tell document 1 of application "TextEdit" |
set newName to word 1 -- handled by TextEdit |
end tell |
set len to count characters in newName -- handled by AppleScript |
if (len > 2) and (len < 15) then -- comparisons handled by AppleScript |
set name of first item of disk "HD" to newName -- handled by Finder |
end if |
end tell |
This example works because in each case the terminology understood by a particular application is used within a tell
block targeting that application. However, it would not compile if you asked the Finder for word 1
of a document, or told TextEdit to set name
of the first item on a disk, because those applications do not support those terms.
try Statements
A try
statement provides the means for scripts to handle potential errors. It attempts to execute one or more statements and, if an error occurs, executes a separate set of statements to deal with the error condition. If an error occurs and there is no try
statement in the calling chain to handle it, AppleScript displays an error and script execution stops.
For related information, see error Statements and AppleScript Error Handling.
Attempts to execute a list of AppleScript statements, calling an error handler if any of the statements results in an error.
A try
statement is a two-part compound statement that contains a series of AppleScript statements, followed by an error handler to be invoked if any of those statements causes an error. If the statement that caused the error is included in a try
statement, then AppleScript passes control to the error handler. After the error handler completes, control passes to the statement immediately following the end of the try
statement.
Syntax
|
Placeholders
- statement
Any AppleScript statement.
- errorMessage
A
text
object, that describes the error.- errorNumber
The error number, an integer. For possible values, see Error Numbers and Error Messages.
- offendingObject
A reference to the object, if any, that caused the error.
- resultList
A list that provides partial results for objects that were handled before the error occurred. The list can contain values of any class. This parameter applies only to commands that return results for multiple objects. This is rarely supported by applications.
- expectedType
The expected class. If the error was caused by a coercion failure, the value of this variable is the class of the coercion that failed. (The second example below shows how this works in a case where AppleScript is unable to coerce a
text
object into aninteger
.)- variable
Either a global variable or a local variable that can be used in the handler. A variable can contain any class of value. The scope of a local variable is the handler. The scope of a global variable extends to any other part of the script, including other handlers and
script
objects. For related information about local and global variables, see version.
Examples
The following example shows how you can use a try
statement to handle the “Cancel” button for a display alert
command. Canceling returns an error number of -128, but is not really an error. This test handler just displays a dialog to indicate when the user cancels or when some other error occurs.
try |
display alert "Hello" buttons {"Cancel", "Yes", "No"} cancel button 1 |
on error errText number errNum |
if (errNum is equal to -128) then |
-- User cancelled. |
display dialog "User cancelled." |
else |
display dialog "Some other error: " & errNum & return & errText |
end if |
end try |
You can also use a simplified version of the try
statement that checks for just a single error number. In the following example, only error -128 is handled. Any other error number is ignored by this try
statement, but is automatically passed up the calling chain, where it may be handled by other try
statements.
try |
display alert "Hello" buttons {"Cancel", "Yes", "No"} cancel button 1 |
on error number -128 |
-- Either do something special to handle Cancel, or just ignore it. |
end try |
The following example demonstrates the use of the to
keyword to capture additional information about an error that occurs during a coercion failure:
try |
repeat with i from 1 to "Toronto" |
-- do something that depends on variable "i" |
end repeat |
on error from obj to newClass |
log {obj, newClass} -- Display from and to info in log pane. |
end try |
This repeat
statement fails because the text
object "Toronto"
cannot be coerced to an integer
. The error handler simply writes the values of obj
(the offending value, "Toronto"
) and newClass
(the class of the coercion that failed, integer
) to Script Editor’s Event Log History window (and to the script window’s Event Log pane). The result is “(*Toronto, integer*)”, indicating the error occurred while trying to coerce “Toronto” to an integer.
For additional examples, see Working with Errors.
use Statements
A use
statement declares a required resource for a script—an application, script library, framework, or version of AppleScript itself—and can optionally import terminology from the resource for use elsewhere in the script. The effects and syntax of use
vary slightly depending on the used resource; the different cases are described below.
The basic function of use
is to require that a resource be present before the script begins executing. If the requirement cannot be met, the script will fail to run. A use
statement can also specify a minimum version for the required resource, such as a minimum compatible version of an application. In this example, AppleScript will ensure that Safari version 7.0 or later is available:
use application "Safari" version "7.0" |
use
statements can also import terminology from the used resource, making the terms available throughout the script without requiring the use of tell
or using terms from
. AppleScript tracks where terms were imported from, and sends events that use those terms to that target. Ordinarily, commands are sent to the current target (it
) as described in Target, but imported terminology overrides this. If…
the event identifier is imported
the direct parameter is an imported class or enumeration identifier
the direct parameter is an object specifier ending with an imported term
…then the command is sent to the import source instead. This happens even if the command is inside a tell
block for a different target. For example, this script uses a command from Safari:
use application "Safari" |
search the web for "AppleScript" |
Importing happens by default, but can be suppressed using the without importing
parameter, if applicable. You can use this to add requirements to existing scripts without changing anything else about the script:
use application "Safari" version "7.0" without importing |
Because Safari's terms are not imported, the script will still need to use tell
to send it events.
Declares a required minimum version of AppleScript, and that the script expects a newer behavior for how scripting additions are handled, described in use (scripting additions).
Syntax
|
Placeholders
- versionText
The required minimum version of AppleScript, as a version string such as
"2.3.2"
. If omitted, its default value is 2.3, the version in whichuse
was introduced. This value is always text, not a number, and is compared as ifconsidering numeric strings
is in effect. For example,"2.10"
is greater than"2.3"
, because 10 is greater than 3.
Examples
In its simplest form, use
can be used to declare that the script uses AppleScript:
use AppleScript |
This also implicitly means that the script uses AppleScript version 2.3 or later, when use
was first introduced, and that the script expects a newer behavior for how scripting additions are handled, described in use (scripting additions).
A use
command can also explicitly specify a minimum required version of AppleScript:
use AppleScript version "2.3.2" |
Declares that a script uses scripting additions.
Syntax
|
Placeholders
- boolean
A boolean value,
true
orfalse
. AppleScript will recompile this towith importing
orwithout importing
. The default iswith importing
.
Examples
Use use scripting additions
to explicitly declare that the script uses scripting addition commands:
use scripting additions |
Discussion
Scripting addition commands are handled differently if a script has use
commands. If a script has one or more use
commands of any kind, scripting addition commands are not available by default. You must explicitly indicate that you wish to use scripting additions, either with a use
or using terms from
command.
use scripting additions |
display dialog "hello world" |
using terms from scripting additions |
display dialog "hello world" |
end using terms from |
If a script uses use scripting additions
, AppleScript may optimize scripting addition commands, sending them to the current application instead of the current target (it
) when it does not change the meaning to do so. For example, random number does not need to be sent to another application to work correctly, and will always be sent to the current application when imported with use
. Without a use scripting additions
command, AppleScript must use a less efficient dispatching scheme, so explicitly declaring them is recommended.
Declares a required application or script library, and may import its terms for use later in the script.
Syntax
|
Placeholders
- versionText
The required minimum version of the resource as a version number, such as
"2.3.2"
. This value is always text, not a number, and is compared as ifconsidering numeric strings
is in effect. For example,"2.10"
is greater than"2.3"
, because 10 is greater than 3.- identifier
An optional identifier for the resource.
- specifier
Specifier data for the resource. This is typically a name, as in
use application "Finder"
oruse script "My Library"
, but may be any valid specifier form, such as by ID, as inuse application id "com.apple.mail"
.- boolean
A boolean value,
true
orfalse
. AppleScript will recompile this towith importing
orwithout importing
. The default iswith importing
.
Examples
A use
command may refer to an application:
use application "Finder" |
…or a script library:
use script "Happy Fun Ball" |
If an optional identifier is given, it defines a property whose value is the required resource. This can make it more convenient to refer to the resource, as in this example: the get
statement uses the identifier Safari
instead of the full specifier application "Safari"
.
use Safari : application "Safari" |
get the name of Safari's front window |
By using use
with multiple applications, you can combine terms from different sources in ways impossible using tell
, because tell
only makes one terminology source available at a time. For example, the following script, in one statement, uses Mail and Safari to search the web for the sender of the currently selected mail message. The get
event is sent to Mail because it defines message viewer
, while the search the web
event is sent to Safari.
use application "Mail" |
use application "Safari" |
search the web for the sender of the first item of ¬ |
(get selected messages of the front message viewer) |
Declares a required framework for use with the AppleScript/Objective-C bridge.
Syntax
|
Placeholders
- specifier
Specifier data for the resource. This may be a base name (
"AppKit"
), a full name ("AppKit.framework"
), or a POSIX path ("/System/Library/Frameworks/AppKit.framework"
).
Examples
Most scripts that use the AppleScript/Objective-C bridge should have at least one of these two use
statements:
use framework "Foundation" |
use framework "AppKit" |
You can also use other frameworks, such as WebKit:
use framework "WebKit" |
Discussion
When you declare a required framework, AppleScript ensures the framework is loaded before running your script. To ensure that your AppleScript/Objective-C script libraries work correctly in any application, declare all needed frameworks explicitly; otherwise, there is no guarantee that a given framework will be available, and your script may fail.
The version
parameter is not supported for frameworks; to check whether or not a framework supports a certain feature, use NSClassFromString
or -respondsToSelector:
.
using terms from Statements
A using terms from
statement lets you specify which terminology AppleScript should use in compiling the statements in a script. Whereas a tell
statement specifies the default target (often an application) to which commands are sent and the terminology to use, a using terms from
statement specifies only the terminology.
A using terms from
statement can be useful in writing application event handler scripts, such as Mail rules.
Another use for this type of statement is with a script that targets an application on a remote computer that may not be available when you compile the script (or the application may not be running). Or, you might be developing locally and only want to test with the remote application at a later time. In either case, you can use a using terms from
statement to specify a local application (presumably with a terminology that matches the one on the remote computer) to compile against.
Even if a statement contained within a using terms from
statement compiles, the script may fail when run because the target application’s terminology may differ from that used in compiling.
You can nest using terms from
statements. When you do so, each script statement is compiled against the terminology of the application named in the innermost enclosing using terms from
statement.
Instructs AppleScript to use the terminology from the specified source in compiling the enclosed statements.
Syntax
|
Placeholders
- application
A specifier for an application object.
- script
A specifier for a script library.
- statement
Any AppleScript statement.
Examples
The following example shows how to use a using terms from
statement in writing a Mail rule action script. These scripts take the following form:
using terms from application "Mail" |
on perform mail action with messages theMessages for rule theRule |
tell application "Mail" |
-- statements to process each message in theMessages |
end tell |
end perform mail action with messages |
end using terms from |
To use the script, you open Preferences for the Mail application, create or edit a rule, and assign the script as the action for the rule.
For an example that works with an application on a remote machine, see Targeting Remote Applications.
As discussed in use Statements, a script with any use
statements does not make scripting addition terms visible by default. You can enable scripting addition terms for specific parts of a script with using terms from
as in this example:
use AppleScript |
-- scripting addition commands such as "display dialog" will not compile here... |
using terms from scripting additions -- ...but will compile within this block. |
display dialog "Hello world!" |
end using terms from |
Discussion
using terms from
does not import terms as use
does, and is subject to the same limits on terminology use as tell
. using terms from scripting additions
does not enable optimization of scripting addition commands as use scripting additions
does.
with timeout Statements
You can use a with timeout
statement to control how long AppleScript waits for a command to execute before timing out. By default, when an application fails to respond to a command, AppleScript waits for two minutes before reporting an error and halting execution.
Specifies how long AppleScript waits for a response to a command that is sent to another application.
Syntax
|
Placeholders
- integerExpression
The amount of time, in seconds, AppleScript should wait before timing out (and interrupting the command).
- statement
Any AppleScript statement.
Examples
The following script tells TextEdit to close its first document; if the document has been modified, it asks the user if the document should be saved. It includes the statement with timeout of 20 seconds
, so that if the user doesn’t complete the close
operation within 20 seconds, the operation times out.
tell application "TextEdit" |
with timeout of 20 seconds |
close document 1 saving ask |
end timeout |
end tell |
Discussion
When a command fails to complete in the allotted time (whether the default of two minutes, or a time set by a with timeout
statement), AppleScript stops running the script and returns the error "event timed out"
. AppleScript does not cancel the operation—it merely stops execution of the script. If you want the script to continue, you can wrap the statements in a try
statement. However, whether your script can send a command to cancel an offending lengthy operation after a timeout is dependent on the application that is performing the command.
A with timeout
statement applies only to commands sent to application objects, not to commands sent to the application that is running the script.
In some situations, you may want to use an ignoring application responses
statement (instead of a with timeout
statement) so that your script needn’t wait for application commands to complete. For more information, see considering and ignoring Statements.
with transaction Statements
When you execute a script, AppleScript may send one or more Apple events to targeted applications. A transaction is a set of operations that are applied as a single unit—either all of the changes are applied or none are. This mechanism works only with applications that support it.
Associates a single transaction ID with any events sent to a target application as a result of executing commands in the body of the statement.
Syntax
|
Placeholders
- session
An object that identifies a specific session.
- statement
Any AppleScript statement.
Examples
This example uses a with transaction
statement to ensure that a record can be modified by one user without being modified by another user at the same time. (In the following examples, “Small DB” and “Super DB” are representative database applications.)
tell application "Small DB" |
with transaction |
set oldName to Field "Name" |
set oldAddress to Field "Address" |
set newName to display dialog ¬ |
"Please type a new name" ¬ |
default answer oldName |
set newAddress to display dialog ¬ |
"Please type the new address" ¬ |
default answer oldAddress |
set Field "Name" to newName |
set Field "Address" to newAddress |
end transaction |
end tell |
The set
statements obtain the current values of the Name and Address fields and invite the user to change them. Enclosing these set
statements in a single with transaction
statement informs the application that other users should not be allowed to access the same record at the same time.
A with transaction
statement works only with applications that explicitly support it. Some applications only support with transaction
statements (like the one in the previous example) that do not take a session object as a parameter. Other applications support both with transaction
statements that have no parameter and with transaction
statements that take a session parameter.
The following example demonstrates how to specify a session for a with transaction
statement:
tell application "Super DB" |
set mySession to make session with data {user: "Bob", password: "Secret"} |
with transaction mySession |
... |
end transaction |
end tell |
Copyright © 2016 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2016-01-25