Commands Reference (original) (raw)

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.

Table 7-1 AppleScript commands

activate

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

Syntax

Parameters

application

The application to activate.

Result

None.

Examples

Discussion

The activate command does not launch applications on remote machines. For examples of other ways to specify an application, see the [application](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-SW2) class and Remote Applications.

ASCII character

Returns the character for a specified number.

Syntax

Parameters

integer

The character code, an integer between 0 and 255.

Result

A [text](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCIAHJF) object containing the character that corresponds to the specified number.

Signals an error if integer is out of range.

Examples

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.

ASCII number

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](#//apple%5Fref/doc/uid/TP40000983-CH216-SW21) for details.

beep

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:

choose application

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

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.

choose color

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):

choose file

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](#//apple%5Fref/doc/uid/TP40000983-CH216-SW14).

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](#//apple%5Fref/doc/uid/TP40000983-CH216-SW14).

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

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)](#//apple%5Fref/doc/uid/TP40000983-CH216-SW19) to begin browsing in the user’s Pictures folder:

choose file name

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](#//apple%5Fref/doc/uid/TP40000983-CH216-SW4) 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:

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.

choose folder

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 contents boolean

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:

The following example gets a POSIX path to a chosen folder and uses the quoted form property (of the [text](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCIAHJF) 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/'"

choose from list

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](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCDBHIE) of the chosen [number](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCBJDGC) and/or [text](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCIAHJF) 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).

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.

choose remote application

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](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-SW2) 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.

choose URL

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 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](#//apple%5Fref/doc/uid/TP40000983-CH216-SW54) 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:

clipboard info

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](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCDBHIE) containing one entry {class, size} for each type of data on the clipboard. To retrieve the actual data, use the [the clipboard](#//apple%5Fref/doc/uid/TP40000983-CH216-SW28) command.

Examples

close access

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](#//apple%5Fref/doc/uid/TP40000983-CH216-SW31) 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:

Discussion

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

copy

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:

Each variable reflects only the changes that were made directly to that variable. Compare this with the similar example in [set](#//apple%5Fref/doc/uid/TP40000983-CH216-SW52).

See the [set](#//apple%5Fref/doc/uid/TP40000983-CH216-SW52) 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](#//apple%5Fref/doc/uid/TP40000983-CH216-SW52) 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.

count

Counts the number of elements in another object.

Syntax

Parameters

expression

An expression that evaluates to an object with elements, such as a [list](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCDBHIE), [record](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCDGEAH), or application-defined container object. count will count the contained elements.

Result

The number of elements, as an [integer](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCHBDCJ).

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:

…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:

…or a Filter specifier:

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

current date

Returns the current date and time.

Syntax

Result

The current date and time, as a [date](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCGECID) object.

Examples

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

See the [date](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCGECID) class for information on how to access the properties of a date, such as the day of the week or month.

delay

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

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.

display alert

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

For an additional example, see the Examples section for the [try](ASLR%5Fcontrol%5Fstatements.html#//apple%5Fref/doc/uid/TP40000983-CH6g-129232) statement.

display dialog

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.

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.

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.

display notification

Posts a notification using the Notification Center, containing a title, subtitle, and explanation, and optionally playing a sound.

Syntax

Parameters

text

The body text of the notification. At least one of this and the title must be specified.

with title text

The title of the notification. At least one of this and the body text must be specified.

subtitle text

The subtitle of the notification.

sound name text

The name of a sound to play when the notification appears. This may be the base name of any sound installed in Library/Sounds.

Result

None.

Examples

display notification "Encoding complete" subtitle "The encoded files are in the folder " & folderName

Discussion

Exactly how the notification is presented is controlled by the “Notifications” preferences in System Preferences. Users may opt to display a reduced form of notification, turn off the sound, or even not display them at all.

do shell script

Executes a shell script using the sh shell.

Syntax

Parameters

text

The shell script to execute.

as class

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

get

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"

As noted above, the get is generally optional. For example, these statements are equivalent to the above two:

However, an explicit get can be useful for forcing early evaluation of part of an object specifier. Consider:

This fails because Finder does not know about elements of text, such as words. AppleScript does, however, so the script has to make Finder get only the name of ... part:

The explicit get forces that part of the specifier to be evaluated; Finder returns a text result, from which AppleScript can then get word 1.

For more information on specifiers, see Object Specifiers.

get eof

Returns the length of a file, in bytes.

Syntax

Parameters

(alias | file | file descriptor)

The file to obtain the length for, as an alias, a file specifier, or an [integer](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCHBDCJ) file descriptor. A file descriptor must be obtained as the result of an earlier [open for access](#//apple%5Fref/doc/uid/TP40000983-CH216-SW31) call.

Result

The logical size of the file, that is, the length of its contents in bytes.

Examples

This example obtains an alias to a desktop picture folder and uses get eof to obtain its length:

get volume settings

Returns the sound output and input volume settings.

Syntax

Result

A record containing the sound output and input volume settings. All the integer settings are between 0 (silent) and 100 (full volume):

output volume (an [integer](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCHBDCJ))

The base output volume.

input volume (an integer)

The input volume.

alert volume (an integer)

The alert volume. 100 for this setting means “as loud as the output volume.”

output muted (a [boolean](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCIBBGG))

Is the output muted? If true, this overrides the output and alert volumes.

Examples

info for

Return information for a file or folder.

Syntax

Parameters

(alias | file)

An alias or file specifier for the file or folder.

size boolean

Return the size of the file or folder? For a file, its “size” is its length in bytes; for a folder, it is the sum of the sizes of all the files the folder contains.

Default Value:

true: Because getting the size of a folder requires getting the sizes of all the files inside it, size true may take a long time for large folders such as /System. If you do not need the size, ask to not get it using size false. Alternatively, target the Finder or System Events applications to ask for the specific properties you want.

Result

A record containing information about the specified file or folder, with the following fields. Some fields are only present for certain kinds of items:

name (a [text](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCIAHJF) object)

The item’s full name, as it appears in the file system. This always includes the extension, if any. For example, "OmniOutliner Professional.app".

displayed name (a [text](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCIAHJF) object)

The item’s name as it appears in Finder. This may be different than the name if the extension is hidden or if the item has a localized name. For example, "OmniOutliner Professional".

short name ( a [text](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCIAHJF) object, applications only)

The application’s CFBundleName, which is the name displayed in the menu bar when the application is active. This is often, but not always, the same as the displayed name. For example, "OmniOutliner Pro".

name extension (a [text](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCIAHJF) object)

The extension part of the item name. For example, the name extension of the file “foo.txt” is "txt".

bundle identifier (a [text](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCIAHJF) object)

The package’s bundle identifier. If the package is an application, this is the application’s id.

type identifier (a [text](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCIAHJF) object)

The item’s type, as a Uniform Type Identifier (UTI). This is the preferred form for identifying item types, and may be used with choose file.

kind (a [text](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCIAHJF) object)

The item’s type, as displayed in Finder. This may be localized, and should only be used for display purposes.

default application (an [alias](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-SW3) object)

The application that will open this item.

creation date (a [date](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCGECID) object)

The date the item was created.

modification date (a [date](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCGECID) object)

The date the item was last modified. Folder modification dates do not change when an item inside them changes, though they do change when an item is added or removed.

file type (a [text](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCIAHJF) object)

The item’s type, as a four-character code. This is the classic equivalent of the type identifier, but less accurate and harder to interpret; use type identifier if possible.

file creator (a [text](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCIAHJF) object)

The item’s four-character creator code. For applications, this is the classic equivalent of the bundle identifier, and will work for referencing an application by id. For files, this can be used to infer the default application, but not reliably; use default application if possible.

short version (a [text](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCIAHJF) object)

The item’s short version string, as it appears in a Finder “Get Info” window. Any item may have this attribute, but typically only applications do.

long version (a [text](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCIAHJF) object)

The item’s long version string, as it appears in a Finder “Get Info” window. Any item may have this attribute, but typically only applications do.

size (an [integer](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCHBDCJ))

The item’s size, in bytes. For more details, see the size parameter.

alias (a [boolean](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCIBBGG))

Is the item an alias file?

folder (a [boolean](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCIBBGG))

Is the item a folder? This is true for packages, such as application packages, as well as normal folders.

package folder (a [boolean](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCIBBGG))

Is the item a package folder, such as an application? A package folder appears in Finder as if it is a file.

extension hidden (a [boolean](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCIBBGG))

Is the item’s name extension hidden?

visible (a [boolean](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCIBBGG))

Is the item visible? Typically, only special system files are invisible.

locked (a [boolean](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCIBBGG))

Is the item locked?

busy status (a [boolean](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCIBBGG))

Is the item currently in use?

If true, the item is reliably busy. If false, the item may still be busy, because this status may not be supported by some applications or file systems.

folder window (rectangle, folders only)

The folder’s window’s bounding rectangle, as list of four integers: {top, left, bottom, right}.

Examples

Special Considerations

Because info for returns so much information, it can be slow, and because it only works on one file at a time, it can be difficult to use. The recommended technique is to use System Events or Finder to ask for the particular properties you want.

launch

Launches an application, if it is not already running, but does not send it a run command.

If an application is already running, sending it a launch command has no effect. That allows you to open an application without performing its usual startup procedures, such as opening a new window or, in the case of a script application, running its script. For example, you can use the launch command when you don’t want an application to open and close visibly. This is less useful in AppleScript 2.0, which launches applications as hidden by default (even with the [run](#//apple%5Fref/doc/uid/TP40000983-CH216-SW57) command).

See the [application](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-SW2) class reference for information on how to use an application object’s is running property to determine if it is running without having to launch it.

Syntax

Parameters

application

The application to launch.

Result

None.

Examples

Discussion

The launch command does not launch applications on remote machines. For examples of other ways to specify an application, see the [application](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-SW2) class.

Many applications also support the reopen command, which reactivates a running application or launches it if it isn’t running. If the application is already running, this command has the same effect as double-clicking the application icon in the Finder. Each application determines how it will implement the reopen command—some may perform their usual startup procedures, such as opening a new window, while others perform no additional operations.

list disks

Returns the names of the currently mounted volumes.

Syntax

Result

A [list](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCDBHIE) of text objects, one for each currently mounted volume.

list folder

Returns the names of the items in a specified folder.

Syntax

Parameters

(alias | file)

Specifies the folder to list.

invisibles boolean

Show invisible files and folders?

Default Value:

true

Result

A [list](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCDBHIE) of [text](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCIAHJF) objects, one for each item in the specified folder.

load script

Returns a script object loaded from a specified file.

Syntax

Parameters

(alias | file)

An alias or file specifier that specifies a script object. The file must be a compiled script (with extension scpt) or script bundle (with extension scptd).

Result

The script object. You can get this object’s properties or call its handlers as if it were a local script object.

Examples

For examples, see Parameter Specifications in About Handlers.

localized string

Returns the localized text for the specified key.

Syntax

Parameters

text

The key for which to obtain the localized text.

from table text

The name of the strings file excluding the .strings suffix.

Default Value:

"Localizable"

in bundle (alias | file)

An alias or file specifier that specifies the strings file.

Default Value:

The current script bundle for a document-based script (a scptd bundle); otherwise, the current application.

Result

A [text](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCIAHJF) object containing the localized text, or the original key if there is no localized text for that key.

Examples

In order for localized string to be useful, you must create localized string data for it to use:

1. Save your script as an application bundle or script bundle.
2. Create lproj folders in the Resources directory of the bundle for each localization: for example, English.lproj, French.lproj. Create files named Localized.strings in each one. When you are done, the folder structure should look like this:
   Figure 7-1 Bundle structure with localized string data
   
3. Add key/value pairs to each Localized.strings file. Each pair is a line of text "key" = "value";, for example:
   Figure 7-2 Key/value pair for localized string data
   

Now localized string will return the appropriate values, as defined in your files. For example, when running in French:

localized string "hello" --result: "bonjour"

log

In Script Editor, displays a value in the Event Log History window or in the Event Log pane of a script window.

Syntax

Parameters

value

The value to display. Expressions are evaluated but object specifiers are not resolved.

The displayed value is enclosed in block comment characters—for example, (*window 1*).

If you do not specify a value, log will display just the comment characters: (**).

Result

None.

Examples

The following shows a simple use of logging:

Log statements can be useful for tracking a script’s progress. For an example that shows how to log statements in a repeat loop, see Logging.

mount volume

Mounts the specified network volume.

Syntax

Parameters

text

The name or URL (for example, afp://server/volume/) of the volume to mount.

on server text

The server on which the volume resides; omit if URL path provided in direct parameter.

in AppleTalk zone text

The AppleTalk zone in which the server resides; omit if URL path provided.

as user name text

The user name with which to log in to the server; omit for guest access.

with password text

The password for the user name; omit for guest access.

Result

None.

Examples

Discussion

The mount volume command can connect to any file server that is supported by the Finder’ “Connect To...” command, including Windows (smb), Samba, and FTP servers. On some kinds of servers, the as user name and with password parameters may not bypass the login dialog, but encoding the name and password in the URL (for example, smb://myname:passwd@server.domain.com/sharename) will mount it silently.

offset

Finds one piece of text inside another.

Syntax

Parameters

of text

The source text to find the position of.

in text

The target text to search in.

Result

An [integer](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCHBDCJ) value indicating the position, in characters, of the source text in the target, or 0 if not found.

Examples

Discussion

offset compares text as the equals operator does, including considering and ignoring conditions. The values returned are counted the same way character elements of text are counted—for example, offset of "c" in "école" is always 2, regardless of whether "école" is in Normalization Form C or D. The result of matching part of a character cluster is undefined.

open for access

Opens a file for reading and writing.

Syntax

Parameters

(alias | file)

An alias or file specifier that specifies the file to open. You can only use an alias if the file exists.

write permission boolean

Should writing to the file be allowed?

Default Value:

false: write and set eof commands on this file will fail with an error.

Result

A file descriptor, as an [integer](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCHBDCJ). This file descriptor may be used with any of the other file commands: [read](#//apple%5Fref/doc/uid/TP40000983-CH216-SW32), [write](#//apple%5Fref/doc/uid/TP40000983-CH216-SW34), [get eof](#//apple%5Fref/doc/uid/TP40000983-CH216-SW30), [set eof](#//apple%5Fref/doc/uid/TP40000983-CH216-SW33), and [close access](#//apple%5Fref/doc/uid/TP40000983-CH216-SW29).

Examples

The following example opens a file named "NewFile" in the specified location path to desktop, but does not ask for write access:

To open the file with write access, you would substitute the following line:

set referenceNumber to open for access theFile with write permission

Discussion

Opening a file using open for access is not the same as opening a file using Finder. It is “open” only in the sense that AppleScript has access to read (and optionally write) its contents; it does not appear in one of the target application’s windows, and it does not even have to be one of the target application’s files. open for access and the associated file commands (read, write, get eof, set eof) are typically used with text files. They can also read and write arbitrary binary data, but this is not recommended unless you create the file yourself or have detailed knowledge of the file format.

Calling open for access on a file returns an integer, termed a file descriptor, which represents an open communication channel to the file’s data. This file descriptor remains open until the script calls close access on it (or on the same file). Each file descriptor maintains a file pointer, which marks the current position within the file and is initially set to the beginning of the file. read and write commands begin reading or writing at the file pointer, unless instructed otherwise using a from or starting at parameter, and advance the file pointer by the number of bytes read or written, so the next operation will begin where the previous one left off.

A single file may be opened more than once, and therefore have several different file descriptors. Each file descriptor maintains its own file pointer, and each must be closed separately. If you open more than one channel at once with write permission, behavior is unspecified.

It is not strictly necessary to use open for access—all the other file commands can accept an alias; if the file is not open, they will open it, do the operation, and then close it. Explicitly opening and closing the file does have two potential advantages, however.

One is performance: if you are performing a number of operations on the same file, opening and closing it repeatedly could become expensive. It is cheaper to explicitly open the file, do the work, and then explicitly close it.

Two is ease of sequential read and write operations: because the file pointer tracks the progress through the file, reading or writing several pieces of data from the same file is a simple matter. Doing the same thing without using the file pointer requires calculating the data size yourself, which is not even possible in some cases.

open location

Opens a URL with the appropriate program.

Syntax

Parameters

text

The URL to open.

error reporting boolean

This parameter exists only for historical reasons; it is no longer supported.

Result

None.

Examples

This example opens an Apple web page:

open location "http://www.apple.com"

path to (application)

Returns the location of the specified application.

Syntax

Parameters

application

The application to locate. See the [application](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-SW2) class reference for possible ways to specify an application. You may also use one of the following identifiers:

current application

The application executing the script, such as Script Editor.

frontmost application

The frontmost application.

me

The script itself. For script applications, this is the same as current application, but for script documents, it is the location of the document.

Note: Some older applications may treat me identically to current application.

it

The application of the current target.

Default Value:

it

as class (alias | text)

The class of the returned location. If specified, must be one of alias or text.

Default Value:

[alias](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-SW3)

Result

The location of the specified application, as either an alias or a text object containing the path.

Examples

path to (folder)

Returns the location of the specified special folder.

Syntax

Parameters

folder constant

The special folder for which to return the path. You may specify one of the following folders:

The following folders are also defined, but are only meaningful when used with from Classic domain:

from domain constant

The domain in which to look for the specified folder. You may specify one of the following domains:

system domain

A folder in /System.

local domain

A folder in /Library.

network domain

A folder in /Network.

user domain

A folder in ~, the user’s home folder.

Classic domain

A folder in the Classic Mac OS system folder. Only meaningful on systems that support Classic.

Default Value:

The default domain for the specified folder. This varies depending on the folder.

as class (alias | text)

The class of the returned location.

Default Value:

[alias](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-SW3)

folder creation boolean

Create the folder if it doesn’t exist? Your script may not have permission to create the folder (for example, asking to create something in the system domain), so your script should be prepared for that error.

Default Value:

true

Result

The location of the specified folder, as either an alias or a text object containing the path.

Examples

path to resource

Returns the location of the specified resource.

Syntax

Parameters

text

The name of the requested resource.

in bundle (alias | file)

An alias or file specifier that specifies the bundle containing the resource.

Default Value:

The current script bundle for a document-based script (a scptd bundle); otherwise, the current application.

in directory text

The name of a subdirectory in the bundle’s Resources directory.

Result

The location of the specified resource, as an [alias](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-SW3).

Examples

The following example shows how you can get the path to a .icns file—in this case, in the Finder application.

random number

Returns a random number.

Syntax

Parameters

from number

The lowest number to return. Can be negative.

Default Value:

0.0

to number

The highest number to return. Can be negative.

Default Value:

1.0

with seed integer

An initial seed for the random number generator. Once called with any particular seed value, random number will always generate the same sequence of numbers. This can be useful when testing randomized algorithms: you can force it to behave the same way every time.

Result

A number between the from and to limits, including the limit values. Depending on the limit values, the result may be an integer or a real. If at least one limit is specified, and all specified limits are integers, the result is an integer. Otherwise, the result is a real, and may have a fractional part.

Examples

Discussion

Random numbers are, by definition, random, which means that you may get the same number twice (or even more) in a row, especially if the range of possible numbers is small.

The numbers generated are only pseudo-random, and are not considered cryptographically secure.

If you need to select one of a set of objects in a relationship, use some object rather than object (random number from 1 to count objects). See the Arbitrary reference form for more details.

read

Reads data from a file.

Syntax

Parameters

(alias | file | file descriptor)

The file to read from, as an alias, a file specifier, or an [integer](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCHBDCJ) file descriptor. A file descriptor must be obtained as the result of an earlier [open for access](#//apple%5Fref/doc/uid/TP40000983-CH216-SW31) call.

from integer

The byte position in the file to start reading from. The position is 1-based, so 1 is the first byte of the file, 2 the second, and so on. Negative integers count from the end of the file, so -1 is the last byte, -2 the second-to-last, and so on.

Default Value:

The current file pointer (see [open for access](#//apple%5Fref/doc/uid/TP40000983-CH216-SW31)) if the file is open, or the beginning of the file if not.

for integer

The number of bytes to read.

Default Value:

Read until the end of the file.

to (integer | eof)

Stop reading at this byte position in the file; use eof to indicate the last byte. The position is 1-based, like the from parameter.

before text

A single character; read up to the next occurrence of that character. The before character is also read, but is not part of the result, so the next read will start just after it.

until text

A single character; read up to and including the next occurrence of that character.

using delimiter text

A delimiter, such as a tab or return character, used to separate the data read into a list of text objects. The resulting items consist of the text between occurrences of the delimiter text. The delimiter is considered a separator, so a leading or trailing delimiter will produce an empty string on the other side. For example, the result of reading "axbxcx" using a delimiter of "x" would be {"a", "b", "c", ""}.

Default Value:

None; read returns a single item.

using delimiters list of text

As using delimiter above, but all of the strings in the list count as delimiters.

as class

Interpret the raw bytes read as this class. The most common ones control the use of three different text encodings:

text or string

The primary text encoding, as determined by the user’s language preferences set in the International preference panel. (For example, Mac OS Roman for English, MacJapanese for Japanese, and so on.)

Unicode text

UTF-16.

«class utf8»

UTF-8. (See Double Angle Brackets for information on chevron or “raw” syntax.)

Any other class is possible, for example date or list, but is typically only useful if the data was written using a write statement specifying the same value for the as parameter.

Default Value:

text

Result

The data read from the file. If the file is open, the file pointer is advanced by the number of bytes read, so the next read command will start where the previous one left off.

Examples

The following example opens a file for read access, reads up to (and including) the first occurrence of ".", closes the file, and displays the text it read. (See the Examples section for the [write](#//apple%5Fref/doc/uid/TP40000983-CH216-SW34) command for how to create a similar file for reading.)

To read all the text in the file, replace set myText to read fp until "." with set myText to read fp.

Discussion

At most one of to, for, before, and until is allowed. Use of before, until, or using delimiter(s) will interpret the file first as text and then coerce the text to whatever is specified in the as parameter. Otherwise, it is treated as binary data (which may be interpreted as text if so specified.)

read cannot automatically detect the encoding used for a text file. If a file is not in the primary encoding, you must supply an appropriate as parameter.

When reading binary data, read always uses big-endian byte order. This is only a concern if you are reading binary files produced by other applications.

round

Rounds a number to an integer.

Syntax

Parameters

real

The number to round.

rounding roundingDirection

The direction to round. You may specify one of the following rounding directions:

up

Rounds to the next largest integer. This is the same as the math “ceiling” function.

down

Rounds down to the next smallest integer. This is the same as the math “floor” function.

toward zero

Rounds toward zero, discarding any fractional part. Also known as truncation.

to nearest

Rounds to the nearest integer; .5 cases are rounded to the nearest even integer. For example, 1.5 rounds to 2, 0.5 rounds to 0. Also known as “unbiased rounding” or “bankers’ rounding.” See Discussion for details.

as taught in school

Rounds to the nearest integer; .5 cases are rounded away from zero. This matches the rules commonly taught in elementary mathematics classes.

Default Value:

to nearest

Result

The rounded value, as an [integer](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCHBDCJ) if it is within the allowable range (±229), or as a [real](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCJECEC) if not.

Examples

Rounding up or down is not the same as rounding away from or toward zero, though it may appear so for positive numbers. For example:

To round to the nearest multiple of something other than 1, divide by that number first, round, and then multiply. For example, to round a number to the nearest 0.01:

Discussion

The definition of to nearest is more accurate than as taught in school, but may be surprising if you have not seen it before. For example:

Rounding 1.5 to 2 should come as no surprise, but as taught in school would have rounded 0.5 up to 1. The problem is that when dealing with large data sets or with many subsequent rounding operations, always rounding up introduces a slight upward skew in the results. The round-to-even rule used by to nearest tends to reduce the total rounding error, because on average an equal portion of numbers will round down as will round up.

run

Executes the run handler of the specified target.

To run an application, it must be on a local or mounted volume. If the application is already running, the effect of the run command depends on the application. Some applications are not affected; others repeat their startup procedures each time they receive a run command.

The run command launches an application as hidden; use [activate](#//apple%5Fref/doc/uid/TP40000983-CH216-SW60) to bring the application to the front.

For a script object, the run command causes either the explicit or the implicit run handler, if any, to be executed. For related information, see run Handlers.

Syntax

Parameters

runTarget script

A [script](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-SW5) or [application](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-SW2) object.

Default Value:

it (the current target)

Result

The result, if any, returned by the specified object’s run handler.

Examples

For information about using the run command with script objects, see Sending Commands to Script Objects.

Discussion

To specify an application to run, you can supply a string with only the application name, as shown in the Examples section. Or you can specify a location more precisely, using one of the forms described in Aliases and Files. For examples of other ways to specify an application, see the [application](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-SW2) class.

It is not necessary to explicitly tell an application to run before sending it other commands; AppleScript will do that automatically. To launch an application without invoking its usual startup behavior, use the [launch](#//apple%5Fref/doc/uid/TP40000983-CH216-SW51) command. For further details, see Calling a Script Application From a Script.

run script

Runs a specified script or script file.

See also [store script](#//apple%5Fref/doc/uid/TP40000983-CH216-SW38).

Syntax

Parameters

(text | alias | file)

The script text, or an alias or file specifier that specifies the script file to run.

with parameters list of anything

A list of parameter values to be passed to the script.

in text

The scripting component to use.

Default Value:

"AppleScript"

Result

The result of the script’s run handler.

Examples

The following script targets the application Finder, escaping the double quotes around the application name with the backslash character (for more information on using the backslash, see the Special String Characters section in the [text](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCIAHJF) class description):

run script "get name of front window of app "Finder"" --result: a window name

This example executes a script stored on disk:

say

Speaks the specified text.

Syntax

Parameters

text

The text to speak.

displaying text

The text to display in the feedback window, if different from the spoken text. This parameter is ignored unless Speech Recognition is turned on (in System Preferences).

using text

The voice to speak with—for example: "Zarvox".

You can use any of the voices from the System Voice pop-up on the Text to Speech tab in the Speech preferences pane.

Default Value:

The current System Voice (set in the Speech panel in System Preferences.

waiting until completion boolean

Should the command wait for speech to complete before returning? This parameter is ignored unless Speech Recognition is turned on (in System Preferences).

Default Value:

true

saving to (alias | file)

An alias or file specifier to an AIFF file (existing or not) to contain the sound output. You can only use an alias specifier if the file exists. If this parameter is specified, the sound is not played audibly, only saved to the file.

Default Value:

None; the text is spoken out loud, and no file is saved.

Result

None.

Examples

say "You are not listening to me!" using "Bubbles" -- result: spoken in Bubbles

The following example saves the spoken text into a sound file:

scripting components

Returns a list of the names of all currently available scripting components, such as the AppleScript component.

Syntax

Result

A [list](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCDBHIE) of [text](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCIAHJF) items, one for each installed scripting component.

Examples

scripting components --result: {"AppleScript"}

Discussion

A scripting component is a software component, such as AppleScript, that conforms to the Open Scripting Architecture (OSA) interface. The OSA provides an abstract interface for applications to compile, execute, and manipulate scripts without needing to know the details of the particular scripting language. Each scripting language corresponds to a single scripting component.

set

Assigns one or more values to one or more variables.

Syntax

| | set | variablePattern | required | | ----- | ----------------- | -------- | | | to | expression | optional |

Parameters

variablePattern

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

to expression

The expression whose value is to be set. It can evaluate to any type of object or value.

Result

The value assigned.

Examples

set may be used to create new variables:

...assign new values to existing variables:

set myWeight to myWeight + 23

...change properties or elements of objects, such as lists:

...or application-defined objects:

tell application "Finder" to set name of startup disk to "Happy Fun Ball"

As mentioned in the Discussion, setting one variable to another makes both variables refer to the exact same object. If the object is mutable, that is, it has writable properties or elements, changes to the object will appear in both variables:

Both variables show the same changes, because they both refer to the same object. Compare this with the similar example in [copy](#//apple%5Fref/doc/uid/TP40000983-CH216-SW53). Assigning a new object to a variable is not the same thing as changing the object itself, and does not affect any other variables that refer to the same object. For example:

set can assign several variables at once using a pattern, which may be a list or a record. For example:

tell application "Finder" to set {x, y} to position of front window

Since position of front window evaluates to a list of two integers, this sets x to the first item in the list and y to the second item.

You can think of pattern assignment as shorthand for a series of simple assignments, but that is not quite accurate, because the assignments are effectively simultaneous. That means that you can use pattern assignment to exchange two variables:

To accomplish the second statement using only simple assignments, you would need a temporary third variable.

For more information on using the set command, including a more complex pattern example, see Declaring Variables with the set Command.

Discussion

Using the set command to assign a value to a variable causes the variable to refer to the original value. In a sense, it creates a new name for the same object. If multiple variables refer to a mutable object (that is, one with writable properties or elements, such as a list or script object), changes to the object are observable through any of the variables. If you want a separate copy, use the [copy](#//apple%5Fref/doc/uid/TP40000983-CH216-SW53) command. This sharing only applies to values in AppleScript itself; it does not apply to values in other applications. Changing the object a variable refers to is not the same as altering the object itself, and does not affect other variables that refer to the same object.

set eof

Sets the length of a file, in bytes.

Syntax

Parameters

(alias | file | file descriptor)

The file to set the length of, as an alias, a file specifier, or as an integer file descriptor, which must be obtained as the result of an earlier [open for access](#//apple%5Fref/doc/uid/TP40000983-CH216-SW31) call.

to integer

The new length of the file, in bytes. If the new length is shorter than the existing length of the file, any data beyond that position is lost. If the new length is longer, the contents of the new bytes are unspecified.

Result

None.

Signals a “write permission” error if the file was opened using open for access without write permission.

Examples

If you want to completely replace the contents of an existing file, the first step must be to change its length to zero:

set the clipboard to

Places data on the clipboard.

Syntax

Parameters

anything

The data (of any type) to place on the clipboard.

Result

None.

Examples

The following script places text on the clipboard, then retrieves the text in TextEdit with a [the clipboard](#//apple%5Fref/doc/uid/TP40000983-CH216-SW28) command:

Discussion

It is not necessary to use the clipboard to move data between scriptable applications. You can simply get the data from the first application into a variable and set the appropriate data in the second application.

set volume

Sets the sound output, input, and alert volumes.

Syntax

Parameters

number

The sound output volume, a real number from 0 to 7.

Important: This parameter is deprecated; if specified, all other parameters will be ignored.

output volume integer

The sound output volume, an integer from 0 to 100.

Default Value:

None; the output volume is not changed.

input volume integer

The sound input volume, an integer from 0 to 100.

Default Value:

None; the input volume is not changed.

alert volume integer

The alert input volume, an integer from 0 to 100.

Default Value:

None; the alert volume is not changed.

output muted boolean

Should the sound output be muted?

Default Value:

None; the output muting is not changed.

Result

None.

Examples

The following example saves the current volume settings, before increasing the output volume, saying some text, and restoring the original value:

store script

Stores a script object into a file.

See also [run script](#//apple%5Fref/doc/uid/TP40000983-CH216-SW36).

Syntax

Parameters

script

The script object to store.

in (alias | file)

An alias or file specifier that specifies the file to store the script object in.

Default Value:

None; a standard Save As dialog will be presented to allow the user to choose where to save the script object.

replacing replacingConstant

Allow overwriting an existing file? You may specify one of the following constants:

yes

Overwrite without asking.

no

Never overwrite; signal an error if the file exists.

ask

Present a dialog asking the user what to do; the options are Replace (overwrite the file), Cancel (signal a “user canceled” error), or Save As (save to a different location).

Default Value:

ask

Result

None.

Examples

This example stores a script on disk, using the Save As dialog to specify a location on the desktop and the name storedScript. It then creates an alias to the stored script and runs it with run script:

The store script command stores only the contents of the script—in this case, the one statement, display dialog "Test". It does not store the beginning and ending statements of the script definition.

summarize

Summarizes the specified text or text file.

Syntax

Parameters

textSpecifier

The [text](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCIAHJF), or an [alias](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-SW3) to a text file, to summarize.

in integer

The number of sentences desired in the summary.

Default Value:

1

Result

A [text](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCIAHJF) object containing a summarized version of the text or file.

Examples

This example summarizes Lincoln’s famous Gettysburg Address down to one sentence—a tough job even for AppleScript:

system attribute

Get environment variables or attributes of this computer.

Syntax

Parameters

attribute

The attribute to test: either a Gestalt value or a shell environment variable name. Gestalt values are described in Gestalt Manager Reference.

Default Value:

If the attribute is omitted, system attribute will return a list of the names of all currently defined environment variables.

has integer

For Gestalt values, an integer mask that is bitwise-ANDed with the Gestalt response. If the result is non-zero, system attribute returns true, otherwise false.

For environment variables, this parameter is ignored.

Default Value:

None; system attribute returns the original Gestalt response code.

Result

If the attribute specified is a Gestalt selector, either the Gestalt response code or true or false depending on the has parameter.

If the attribute specified is an environment variable, the value of that variable, or an empty string ("") if it is not defined.

If no attribute is supplied, a list of all defined environment variables.

Examples

To get the current shell:

system attribute "SHELL" --result: "/bin/bash" (for example)

To get a list of all defined environment variables:

system info

Gets information about the system.

Syntax

Result

A record containing various information about the system and the current user. This record contains the following fields:

AppleScript version (a [text](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCIAHJF) object)

The version number of AppleScript, for example, "2.0". This can be useful for testing for the existence of AppleScript features. When comparing version numbers, use considering numeric strings to make them compare in numeric order, since standard lexicographic ordering would consider "1.9" to come after "1.10".

AppleScript Studio version (a [text](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCIAHJF) object)

The version number of AppleScript Studio, for example, "1.5".

Note: AppleScript Studio is deprecated in OS X v10.6.

system version (a [text](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCIAHJF) object)

The version number of OS X, for example, "10.5.1".

short user name (a [text](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCIAHJF) object)

The current user’s short name, for example, "hoser". This is set in the Advanced Options panel in the Accounts preference pane, or in the “Short Name” field when creating the account. This is also available from System Events using name of current user.

long user name (a [text](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCIAHJF) object)

The current user’s long name, for example, "Random J. Hoser". This is the “User Name” field in the Accounts preference pane, or in the “Name” field when creating the account. This is also available from System Events using full name of current user.

user ID (an [integer](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCHBDCJ))

The current user’s user ID. This is set in the Advanced Options panel in the Accounts preference pane.

user locale (a [text](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCIAHJF) object)

The current user’s locale code, for example "en_US".

home directory (an [alias](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-SW3) object)

The location of the current user’s home folder. This is also available from Finder’s home property, or System Events’ home folder property.

boot volume (a [text](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCIAHJF) object)

The name of the boot volume, for example, "Macintosh HD". This is also available from Finder or System Events using name of startup disk.

computer name (a [text](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCIAHJF) object)

The computer’s name, for example "mymac". This is the “Computer Name” field in the Sharing preference pane.

host name (a [text](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCIAHJF) object)

The computer’s DNS name, for example "mymac.local".

IPv4 address (a [text](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCIAHJF) object)

The computer’s IPv4 address, for example "192.201.168.13".

primary Ethernet address (a [text](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCIAHJF) object)

The MAC address of the primary Ethernet interface, for example "00:1c:63:91:4e:db".

CPU type (a [text](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCIAHJF) object)

The CPU type, for example "Intel 80486".

CPU speed (an [integer](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCHBDCJ))

The clock speed of the CPU in MHz, for example 2400.

physical memory (an [integer](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCHBDCJ))

The amount of physical RAM installed in the computer, in megabytes (MB), for example 2048.

Examples

system info --result: long record of information

the clipboard

Returns the contents of the clipboard.

Syntax

Parameters

as class

The type of data desired. the clipboard will attempt to find that “flavor” of data on the clipboard; if it is not found, it will attempt to coerce whatever flavor is there.

Result

The data from the clipboard, which can be of any type.

Examples

The following script places text on the clipboard, and then appends the clipboard contents to the frontmost TextEdit document:

Discussion

It is not necessary to use the clipboard to move data between scriptable applications. You can simply get the data from the first application into a variable and set the appropriate data in the second application.

time to GMT

Returns the difference between local time and GMT (Greenwich Mean Time) or Universal Time, in seconds.

Syntax

Result

The [integer](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCHBDCJ) number of seconds difference between the current time zone and Universal Time.

Examples

The following example computes the time difference between the current location and Cupertino:

write

Writes data to a specified file.

Syntax

Parameters

anything

The data to write to the file. This is typically text, but may be of any type. When reading the data back, the read command must specify the same type, or the results are undefined.

to ( alias | file | file descriptor)

The file to write to, as an alias, a file specifier, or an [integer](ASLR%5Fclasses.html#//apple%5Fref/doc/uid/TP40000983-CH1g-BBCHBDCJ) file descriptor. A file descriptor must be obtained as the result of an earlier [open for access](#//apple%5Fref/doc/uid/TP40000983-CH216-SW31) call.

starting at (integer | eof)

The byte position in the file to start reading from. The position is 1-based, so 1 is the first byte of the file, 2 the second, and so on. Negative integers count from the end of the file, so -1 is the last byte, -2 the second-to-last, and so on. The constant eof is the position just after the last byte; use this to append data to the file.

Default Value:

The current file pointer (see [open for access](#//apple%5Fref/doc/uid/TP40000983-CH216-SW31)) if the file is open, or the beginning of the file if not.

for integer

The number of bytes to write.

Default Value:

Write all the data provided.

as class

Write the data as this class. The most common ones control the use of three different text encodings:

text or string

The primary text encoding, as determined by the user’s language preferences set in the International preference panel. (For example, Mac OS Roman for English, MacJapanese for Japanese, and so on.)

Unicode text

UTF-16.

«class utf8»

UTF-8.

Any other class is possible, for example date or list, but is typically only useful if the data will be read using a read statement specifying the same value for the as parameter.

Default Value:

The class of the supplied data. See Special Considerations.

Result

None. If the file is open, write will advance the file pointer by the number of bytes written, so the next write command will start writing where the last one ended.

Signals an error if the file is open without write permission, or if there is any other problem that prevents writing to the file, such as a lack of disk space.

Examples

The following example opens a file with write permission, creating it if it doesn’t already exist, writes text to it, and closes it.

Special Considerations

As specified above, write with no as parameter writes as the class of the supplied data, which means that in AppleScript 2.0 write always writes text data using the primary encoding. Prior to 2.0, string and Unicode text were distinct types, which meant that it would use primary encoding for string and UTF-16 for Unicode text. For reliable results when creating scripts that will run on both 2.0 and pre-2.0, always specify the encoding explicitly using as text or as Unicode text, as appropriate.