Advanced Search

Log In | Not a Member?

Contact ADC

Hide TOC

Commands Reference

This chapter describes the commands available to perform actions in AppleScript scripts. For information on how commands work, see “Commands Overview”.

The commands described in this chapter are available to any script—they are either built into the AppleScript language or added to it through the standard scripting additions (described in “Scripting Additions”).

Table 7-1 lists each command according to the suite (or related group) of commands to which it belongs and provides a brief description. Detailed command descriptions follow the table, in alphabetical order.

Brings an application to the front, launching it if necessary.

Syntax

Parameters

application

The application to activate.

Result

None.

Examples

activate application "TextEdit"

tell application "TextEdit" to activate

Discussion

The activate command does not launch applications on remote machines. For examples of other ways to specify an application, see the application class and “Remote Applications”.

Returns the character for a specified number.

Syntax

Parameters

integer

The character code, an integer between 0 and 255.

Result

A text object containing the character that corresponds to the specified number.

Signals an error if integer is out of range.

Examples

set theChar to ASCII character 65 --result: "A"

set theChar to ASCII character 194 --result: "¬"

set theChar to ASCII character 2040 --result: invalid range error

Discussion

The name “ASCII” is something of a misnomer. ASCII character uses the primary text encoding, as determined by the user’s language preferences, to map between integers and characters. If the primary language is English, the encoding is Mac OS Roman, if it is Japanese, the encoding is MacJapanese, and so on. For integers below 128, this is generally the same as ASCII, but for integers from 128 to 255, the results vary considerably.

Because of this unpredictability, ASCII character and ASCII number are deprecated starting in AppleScript 2.0. Use the id property of the text class instead, since it always uses the same encoding, namely Unicode.

Returns the number associated with a specified character.

Syntax

Parameters

text

A text object containing at least one character. If there is more than one character, only the first one is used.

Result

The character code of the specified character as an integer.

Examples

set codeValue to ASCII number "¬" --result: 194

Discussion

The result of ASCII number depends on the user’s language preferences; see the Discussion section of ASCII character for details.

Plays the system alert sound one or more times.

Syntax

Parameters

integer

Number of times to beep.

Default Value:

1

Result

None.

Examples

Audible alerts can be useful when no one is expected to be looking at the screen:

beep 3 --result: three beeps, to get attention

display dialog "Something is amiss here!" -- to show message

Allows the user to choose an application.

Syntax

Parameters

with title text

Title text for the dialog.

Default Value:

"Choose Application"

with prompt text

A prompt to be displayed in the dialog.

Default Value:

"Select an application:"

multiple selections allowed boolean

Allow multiple items to be selected? If true, the results will be returned in a list, even if there is exactly one item.

Default Value:

false

as class (application | alias)

Specifies the desired class of the result. If specified, the value must be one of application or alias.

Default Value:

application

Result

The selected application, as either an application or alias object; for example, application "TextEdit". If multiple selections are allowed, returns a list containing one item for each selected application, if any.

Signals a “user canceled” error if the user cancels the dialog. For an example of how to handle such errors, see “try Statements”.

Examples

choose application with prompt "Choose a web browser:"

choose application with multiple selections allowed

choose application as alias

Discussion

The choose application dialog initially presents a list of all applications registered with the system. To choose an application not in that list, use the Browse button, which allows the user to choose an application anywhere in the file system.

Allows the user to choose a color from a color picker dialog.

Syntax

Parameters

default color RGB color

The color to show when the color picker dialog is first opened.

Default Value:

{0, 0, 0}: black.

Result

The selected color, represented as a list of three integers from 0 to 65535 corresponding to the red, green, and blue components of a color; for example, {0, 65535, 0} represents green.

Signals a “user canceled” error if the user cancels the choose color dialog. For an example of how to handle such errors, see “try Statements”.

Examples

This example lets the user choose a color, then uses that color to set the background color in their home folder (when it is in icon view):

tell application "Finder"

    tell icon view options of window of home

        choose color default color (get background color)

        set background color to the result

    end tell

end tell

Allows the user to choose a file.

Syntax

Parameters

with prompt text

The prompt to be displayed in the dialog.

Default Value:

None; no prompt is displayed.

of type list of text

A list of Uniform Type Identifiers (UTIs); for example, {"public.html", "public.rtf"}. Only files of the specified types will be selectable. For a list of system-defined UTIs, see Uniform Type Identifiers Overview. To get the UTI for a particular file, use info for.

Note: Four-character file type codes, such as "PICT" or "MooV", are also supported, but are deprecated. To get the file type code for a particular file, use info for.

Default Value:

None; any file can be chosen.

default location alias

The folder to begin browsing in.

Default Value:

Browsing begins in the last selected location, or, if this is the first invocation, in the user’s Documents folder.

invisibles boolean

Show invisible files and folders?

Default Value:

true: This is only for historical compatibility reasons. Unless you have a specific need to choose invisible files, you should always use invisibles false.

multiple selections allowed boolean

Allow multiple items to be selected? If true, the results will be returned in a list, even if there is exactly one item.

Default Value:

false

showing package contents boolean

Show the contents of packages? If true, packages are treated as folders, so that the user can choose a file inside a package (such as an application).

Default Value:

false. Manipulating the contents of packages is discouraged unless you control the package format or the package itself.

Result

The selected file, as an alias. If multiple selections are allowed, returns a list containing one alias for each selected file, if any.

Signals a “user canceled” error if the user cancels the dialog. For an example of how to handle such errors, see “try Statements”.

Examples

set aFile to choose file with prompt "HTML or RTF:" ¬

    of type {"public.html", "public.rtf"} invisibles false

A UTI can specify a general class of files, not just a specific format. The following script allows the user to choose any image file, whether its format is JPEG, PNG, GIF, or whatever. It also uses the default location parameter combined with path to (folder) to begin browsing in the user’s Pictures folder:

set picturesFolder to path to pictures folder

choose file of type "public.image" with prompt "Choose an image:" ¬

    default location picturesFolder invisibles false

Allows the user to specify a new filename and location. This does not create a file—rather, it returns a file specifier that can be used to create a file.

Syntax

Parameters

with prompt text

The prompt to be displayed near the top of the dialog.

Default Value:

"Specify new file name and location"

default name text

The default file name.

Default Value:

"untitled"

default location alias

The default file location. See choose file for examples.

Default Value:

Browsing starts in the last location in which a search was made or, if this is the first invocation, in the user’s Documents folder.

Result

The selected location, as a file. For example:

file "HD:Users:currentUser:Documents:untitled"

Signals a “user canceled” error if the user cancels the dialog. For an example of how to handle such errors, see “try Statements”.

Examples

The following example supplies a non-default prompt and search location:

set fileName to choose file name with prompt "Save report as:" ¬

default name "Quarterly Report" ¬

default location (path to desktop folder)

Discussion

If you choose the name of a file or folder that exists in the selected location, choose file name offers the choice of replacing the chosen item. However, choosing to replace does not actually replace the item.

Allows the user to choose a directory, such as a folder or a disk.

Syntax

Parameters

with prompt text

The prompt to be displayed in the dialog.

Default Value:

None; no prompt is displayed.

default location alias

The folder to begin browsing in.

Default Value:

Browsing begins in the last selected location, or, if this is the first invocation, in the user’s Documents folder.

invisibles boolean

Show invisible folders?

Default Value:

false

multiple selections allowed boolean

Allow multiple items to be selected? If true, the results will be returned in a list, even if there is exactly one item.

Default Value:

false

showing package contentsboolean

Show the contents of packages? If true, packages are treated as folders, so that the user can choose a package folder, such as an application, or a folder inside a package.

Default Value:

false. Manipulating the contents of packages is discouraged unless you control the package format or the package itself.

Result

The selected directory, as an alias. If multiple selections are allowed, returns a list containing one alias for each selected directory, if any.

Signals a “user canceled” error if the user cancels the choose folder dialog. For an example of how to handle such errors, see “try Statements”.

Examples

The following example specifies a prompt and allows multiple selections:

set foldersList to choose folder ¬

    with prompt "Select as many folders as you like:" ¬

    with multiple selections allowed

The following example gets a POSIX path to a chosen folder and uses the quoted form property (of the text class) to ensure correct quoting of the resulting string for use with shell commands:

set folderName to quoted form of POSIX path of (choose folder)

Suppose that you choose the folder named iWork '08 in your Applications folder. The previous statement would return the following result, which properly handles the embedded single quote and space characters in the folder name:

"'/Applications/iWork '\\''08/'"

Allows the user to choose items from a list.

Syntax

Parameters

list (of number or text)

A list of numbers and/or text objects for the user to choose from.

with title text

Title text for the dialog.

Default Value:

None; no title is displayed.

with prompt text

The prompt to be displayed in the dialog.

Default Value:

"Please make your selection:"

default items list (of number or text)

A list of numbers and/or text objects to be initially selected. The list cannot include multiple items unless you also specify multiple selections allowed true. If an item in the default items list is not in the list to choose from, it is ignored.

Default Value:

None; no items are selected.

OK button name text

The name of the OK button.

Default Value:

"OK"

cancel button name text

The name of the Cancel button.

Default Value:

"Cancel"

multiple selections allowed boolean

Allow multiple items to be selected?

Default Value:

false

empty selection allowed boolean

Allow the user to choose OK with no items selected? If false, the OK button will not be enabled unless at least one item is selected.

Default Value:

false

Result

If the user clicks the OK button, returns a list of the chosen number and/or text items; if empty selection is allowed and nothing is selected, returns an empty list ({}). If the user clicks the Cancel button, returns false.

Examples

This script selects from a list of all the people in Address Book who have defined birthdays, and gets the birthday of the selected one. Notice the if the result is not false test (choose from list returns false if the user clicks Cancel) and the set aName to item 1 of the result (choose from list returns a list, even if it contains only one item).

tell application "Address Book"

    set bDayList to name of every person whose birth date is not missing value

    choose from list bDayList with prompt "Whose birthday would you like?"

    if the result is not false then

        set aName to item 1 of the result

        set theBirthday to birth date of person named aName

        display dialog aName & "'s birthday is " & date string of theBirthday

    end if

end tell

Discussion

For historical reasons, choose from list is the only dialog command that returns a result (false) instead of signaling an error when the user presses the “Cancel” button.

Allows the user to choose a running application on a remote machine.

Syntax

Parameters

with title text

Title text for the choose remote application dialog.

Default Value:

None; no title is displayed.

with prompt text

The prompt to be displayed in the dialog.

Default Value:

"Select an application:"

Result

The selected application, as an application object.

Signals a “user canceled” error if the user cancels the dialog. For an example of how to handle such errors, see “try Statements”.

Examples

set myApp to choose remote application with prompt "Choose a remote web browser:"

Discussion

The user may choose a remote machine using Bonjour or by entering a specific IP address. There is no way to limit the precise kind of application returned, so either limit your script to generic operations or validate the user’s choice. If you want your script to send application-specific commands to the resulting application, you will need a using terms from statement.

For information on targeting other machines, see “Remote Applications”.

Allows the user to specify a URL.

Syntax

Parameters

showing list (of service types or text)

A list that specifies the types of services to show, if available. The list can contain one or more of the following service types, or one or more text objects representing Bonjour service types (described below), or both:

• Web servers: shows http and https services

• FTP Servers: shows ftp services

• Telnet hosts: shows telnet services

• File servers: shows afp, nfs, and smb services

• News servers: shows nntp services

• Directory services: shows ldap services

• Media servers: shows rtsp services

• Remote applications: shows eppc services

A text object is interpreted as a Bonjour service type—for example, "_ftp._tcp" represents the file transfer protocol. These types are listed in Technical Q&A 1312: Bonjour service types used in Mac OS X.

Default Value:

File servers

editable URL boolean

Allow user to type in a URL? If you specify editable URL false, the text field in the dialog is inactive.

choose URL does not attempt to verify that the user-entered text is a valid URL. Your script should be prepared to verify the returned value.

Default Value:

true: the user can enter a text string. If false, the user is restricted to choosing an item from the Bonjour-supplied list of services.

Result

The URL for the service, as a text object. This result may be passed to open location or to any application that can handle the URL, such as a browser for http URLs.

Signals a “user canceled” error if the user cancels the dialog. For an example of how to handle such errors, see “try Statements”.

Examples

The following script asks the user to choose an URL, either by typing in the text input field or choosing one of the Bonjour-located servers:

set myURL to choose URL

tell application Finder to open location myURL

Returns information about the current clipboard contents.

Syntax

Parameters

for class

Restricts returned information to only this data type.

Default Value:

None; returns information for all types of data as a list of lists, where each list represents a scrap flavor.

Result

A list containing one entry {class, size} for each type of data on the clipboard. To retrieve the actual data, use the the clipboard command.

Examples

clipboard info

clipboard info for Unicode text

Closes a file opened with the open for access command.

Syntax

Parameters

(alias | file | file descriptor)

The alias or file specifier or integer file descriptor of the file to close. A file descriptor must be obtained as the result of an earlier open for access call.

Result

None.

Signals an error if the specified file is not open.

Examples

You should always close files that you open, being sure to account for possible errors while using the open file:

set aFile to choose file

set fp to open for access aFile

try

    --file reading and writing here

on error e number n

    --deal with errors here and don't resignal

end

close access fp

Discussion

Any files left open will be automatically closed when the application exits.

Copies one or more values, storing the result in one or more variables. This command only copies AppleScript values, not application-defined objects.

Syntax

Parameters

expression

The expression whose value is to be copied.

to variablePattern

The name of the variable or pattern of variables in which to store the value or pattern of values. Patterns may be lists or records.

Result

The new copy of the value.

Examples

As mentioned in the Discussion, copy creates an independent copy of the original value, and it creates a deep copy. For example:

set alpha to {1, 2, {"a", "b"}}

copy alpha to beta

set item 2 of item 3 of alpha to "change" --change the original list

set item 1 of beta to 42 --change a different item in the copy

{alpha, beta}

--result: {{1, 2, {"a", "change"}}, {42, 2, {"a", "b"}}}

Each variable reflects only the changes that were made directly to that variable. Compare this with the similar example in set.

See the set command for examples of using variable patterns. The behavior is the same except that the values are copied.

Discussion

The copy command may be used to assign new values to existing variables, or to define new variables. See “Declaring Variables with the copy Command” for additional details.

Using the copy command creates a new value that is independent of the original—a subsequent change to that value does not change the original value. The copy is a “deep” copy, so sub-objects, such as lists within lists, are also copied. Contrast this with the behavior of the set command.

When using copy with an object specifier, the specifier itself is the value copied, not the object in the target application that it refers to. copy therefore copies the object specifier, but does not affect the application data at all. To copy the object in the target application, use the application’s duplicate command, if it has one.

Special Considerations

The syntax put expression into variablePattern is also supported, but is deprecated. It will be transformed into the copy form when you compile the script.

Counts the number of elements in another object.

Syntax

Parameters

expression

An expression that evaluates to an object with elements, such as a list, record, or application-defined container object. count will count the contained elements.

Result

The number of elements, as an integer.

Examples

In its simplest form, count, or the equivalent pseudo-property number, counts the item elements of a value. This may be an AppleScript value, such as a list:

set aList to {"Yes", "No", 4, 5, 6}

count aList  --result: 5

number of aList  --result: 5

…or an application-defined object that has item elements:

tell application "Finder" to count disk 1  --result: 4

If the value is an object specifier that evaluates to a list, count counts the items of that list. This may be an “Every” specifier:

count every integer of aList  --result: 3

count words of "hello world"  --result: 2

tell application "Finder" to count folders of disk 1  --result: 4

…or a “Filter” specifier:

tell application "Finder"

    count folders of disk 1 whose name starts with "A"  --result: 1

end tell

…or similar. For more on object specifiers, see “Object Specifiers”.

Returns the current date and time.

Syntax

Result

The current date and time, as a date object.

Examples

current date  --result: date "Tuesday, November 13, 2007 11:13:29 AM"

See the date class for information on how to access the properties of a date, such as the day of the week or month.

Waits for a specified number of seconds.

Syntax

Parameters

number

The number of seconds to delay. The number may be fractional, such as 0.5 to delay half a second.

Default Value:

0

Result

None.

Examples

set startTime to current date

delay 3  --delay for three seconds

set elapsedTime to ((current date) - startTime)

display dialog ("Elapsed time: " & elapsedTime & " seconds")

Discussion

delay does not make any guarantees about the actual length of the delay, and it cannot be more precise than 1/60th of a second. delay is not suitable for real-time tasks such as audio-video synchronization.

Displays a standardized alert containing a message, explanation, and from one to three buttons.

Syntax

Parameters

text

The alert text, which is displayed in emphasized system font.

message text

An explanatory message, which is displayed in small system font, below the alert text.

as alertType

The type of alert to show. You can specify one of the following alert types:

• informational: the standard alert dialog

• warning: the alert dialog dialog is badged with a warning icon

• critical: currently the same as the standard alert dialog

Default Value:

informational

buttons list (of text)

A list of up to three button names.

If you supply one name, a button with that name serves as the default and is displayed on the right side of the alert dialog. If you supply two names, two buttons are displayed on the right, with the second serving as the default button. If you supply three names, the first is displayed on the left, and the next two on the right, as in the case with two buttons.

Default Value:

{"OK"}: One button labeled “OK”, which is the default button.

default button (text or integer)

The name or number of the default button. This may be the same as the cancel button.

Default Value:

The rightmost button.

cancel button (text or integer)

The name or number of the cancel button. See “Result” below. This may be the same as the default button.

Default Value:

None; there is no cancel button.

giving up after integer

The number of seconds to wait before automatically dismissing the alert.

Default Value:

None; the dialog will wait until the user clicks a button.

Result

If the user clicks a button that was not specified as the cancel button, display alert returns a record that identifies the button that was clicked—for example, {button returned: "OK"}. If the command specifies a giving up after value, the record will also contain a gave up:false item.

If the display alert command specifies a giving up after value, and the dialog is dismissed due to timing out before the user clicks a button, the command returns a record indicating that no button was returned and the command gave up: {button returned:"", gave up:true}

If the user clicks the specified cancel button, the command signals a “user canceled” error. For an example of how to handle such errors, see “try Statements”.

Examples

set alertResult to display alert "Insert generic warning here." ¬

    buttons {"Cancel", "OK"} as warning ¬

    default button "Cancel" cancel button "Cancel" giving up after 5

For an additional example, see the Examples section for the try statement.

Displays a dialog containing a message, one to three buttons, and optionally an icon and a field in which the user can enter text.

Syntax

Parameters

text

The dialog text, which is displayed in emphasized system font.

default answer text

The initial contents of an editable text field. This edit field is not present unless this parameter is present; to have the field present but blank, specify an empty string: default answer ""

Default Value:

None; there is no edit field.

hidden answer boolean

If true, any text in the edit field is obscured as in a password dialog: each character is displayed as a bullet.

Default Value:

false: text in the edit field is shown in cleartext.

buttons list (of text)

A list of up to three button names.

Default Value:

If you don’t specify any buttons, by default, Cancel and OK buttons are shown, with the OK button set as the default button.

If you specify any buttons, there is no default or cancel button unless you use the following parameters to specify them.

default button (text | integer)

The name or number of the default button. This button is highlighted, and will be pressed if the user presses the Return or Enter key.

Default Value:

If there are no buttons specified using buttons, the OK button. Otherwise, there is no default button.

cancel button (text | integer)

The name or number of the cancel button. This button will be pressed if the user presses the Escape key or Command-period.

Default Value:

If there are no buttons specified using buttons, the Cancel button. Otherwise, there is no cancel button.

with title text

The dialog window title.

Default Value:

None; no title is displayed.

with icon (text | integer)

The resource name or ID of the icon to display.

with icon (stop | note | caution)

The type of icon to show. You may specify one of the following constants:

• stop (or 0): Shows a stop icon

• note (or 1): Shows the application icon

• caution (or 2): Shows a warning icon, badged with the application icon

with icon (alias | file)

An alias or file specifier that specifies a .icns file.

giving up after integer

The number of seconds to wait before automatically dismissing the dialog.

Default Value:

None; the dialog will wait until the user presses a button.

Result

A record containing the button clicked and text entered, if any. For example:

{text returned:"Cupertino", button returned:"OK"}

If the dialog does not allow text input, there is no text returned item in the returned record.

If the user clicks the specified cancel button, the command signals a “user canceled” error. For an example of how to handle such errors, see “try Statements”.

If the display dialog command specifies a giving up after value, and the dialog is dismissed due to timing out before the user clicks a button, it returns a record indicating that no button was returned and the command gave up: {button returned:"", gave up:true}

Examples

The following example shows how to use many of the parameters to a display dialog command, how to process possible returned values, and one way to handle a user cancelled error. The dialog displays two buttons and prompts a user to enter a name, giving up if they do not make a response within fifteen seconds. It shows one way to handle the case where the user cancels the dialog, which results in AppleScript signaling an “error” with the error number -128. The script uses additional display dialog commands to show the flow of logic and indicate where you could add statements to handle particular outcomes.

set userCanceled to false

try

    set dialogResult to display dialog ¬

        "What is your name?" buttons {"Cancel", "OK"} ¬

        default button "OK" cancel button "Cancel" ¬

        giving up after 15 ¬

        default answer (long user name of (system info))

on error number -128

    set userCanceled to true

end try

if userCanceled then

    -- statements to execute when user cancels

    display dialog "User cancelled."

else if gave up of dialogResult then

    -- statements to execute if dialog timed out without an answer

    display dialog "User timed out."

else if button returned of dialogResult is "OK" then

    set userName to text returned of dialogResult

    -- statements to process user name

    display dialog "User name: " & userName

end if

end

The following example displays a dialog that asks for a password. It supplies a default answer of "wrong", and specifies that the default answer, as well as any text entered by the user, is hidden (displayed as a series of bullets). It gives the user up to three chances to enter a correct password.

set prompt to "Please enter password:"

repeat 3 times

    set dialogResult to display dialog prompt ¬

        buttons {"Cancel", "OK"} default button 2 ¬

        default answer "wrong" with icon 1 with hidden answer

    set thePassword to text returned of dialogResult

    if thePassword = "magic" then

        exit repeat

    end if

end repeat

if thePassword = "magic" or thePassword = "admin" then

    display dialog "User entered valid password."

end if

The password text is copied from the return value dialogResult. The script doesn’t check for a user cancelled error, so if the user cancels AppleScript stops execution of the script.

Executes a shell script using the sh shell.

Syntax

Parameters

text

The shell script to execute.

asclass

Specifies the desired type of the result. The raw bytes returned by the command will be interpreted as the specified class.

Default Value:

«class utf8»: UTF-8 text. If there is no as parameter and the output is not valid UTF-8, the output will be interpreted as text in the primary encoding.

administrator privileges boolean

Execute the command as the administrator? Once a script is correctly authenticated, it will not ask for authentication again for five minutes. The elevated privileges and the grace period do not extend to any other scripts or to the rest of the system. For security reasons, you may not tell another application to do shell script with administrator privileges. Put the command outside of any tell block, or put it inside a tell me block.

Default Value:

false

user name text

The name of an administrator account. You can avoid a password dialog by specifying a name in this parameter and a password in the password parameter. If you specify a user name, you must also specify a password.

password text

An administrator password, typically used in conjunction with the administrator specified by the user name parameter. If user name is omitted, it is assumed to be the current user.

altering line endings boolean

Should the do shell script command change all line endings in the command output to Mac-style and trim a trailing one? For example, the result of do shell script "echo foo; echo bar" is "foo\rbar", not the "foo\nbar\n" that the shell script actually returned.

Default Value:

true

Result

The output of the shell script.

Signals an error if the shell script exits with a non-zero status. The error number will be the status, the error message will be the contents of stderr.

Examples

do shell script "uptime"

Discussion

For additional documentation and examples of the do shell script command, see Technical Note TN2065, do shell script in AppleScript.

Evaluates an object specifier and returns the result.

The command name get is typically optional—expressions that appear as statements or operands are automatically evaluated as if they were preceded by get. However, get can be used to force early evaluation of part of an object specifier.

Syntax

Parameters

specifier

An object specifier to be evaluated. If the specifier refers to an application-defined object, the get command is sent to that application. Technically, all values respond to get, but for all values other than object specifiers, get is an identity operation: the result is the exact same value.

as class

The desired class for the returned data. If the data is not of the desired type, AppleScript attempts to coerce it to that type.

Default Value:

None; no coercion is performed.

Result

The value of the evaluated expression. See “Reference Forms” for details on what the results of evaluating various object specifiers are.

Examples

get can get properties or elements of AppleScript-defined objects, such as lists:

get item 1 of {"How", "are", "you?"}  --result: "How"

…or of application-defined objects:

tell application "Finder" to get name of home  --result: "myname"</