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

Result

None.

Examples

activate application "TextEdit"

tell application "TextEdit" to activate

Returns the character for a specified number.

Syntax

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

Returns the number associated with a specified character.

Syntax

Result

The character code of the specified character as an integer.

Examples

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

Plays the system alert sound one or more times.

Syntax

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

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

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

Syntax

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

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

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)

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

Syntax

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

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

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

Syntax

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

Allows the user to specify a URL.

Syntax

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

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

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

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

Syntax

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.

Counts the number of elements in another object.

Syntax

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

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

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

Syntax

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

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.

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

Syntax

Result

None.

Examples

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

Executes a shell script using the sh shell.

Syntax

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"

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

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:

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

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

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

tell application "Finder" to get word 1 of name of home

--Finder got an error: Can’t get word 1 of name of folder "myname" of folder "Users" of startup disk.

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:

tell application "Finder" to get word 1 of (get name of home)

--result: "myname"

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.

Returns the length of a file, in bytes.

Syntax

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:

set desktopPicturesFolderPath to ¬

     (path to desktop pictures folder as text) & "Flow 1.jpg" as alias

--result: alias "Leopard:Library:Desktop Pictures:Flow 1.jpg"

get eof desktopPicturesFolderPath --result: 531486

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)

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)

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

Examples

set volSettings to get volume settings

--result: {output volume:43, input volume:35, alert volume:78, output muted:false}

Return information for a file or folder.

Syntax

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

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

bundle identifier (a text object)

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

type identifier (a text 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 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 object)

The application that will open this item.

creation date (a date object)

The date the item was created.

modification date (a date 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 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 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 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 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)

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

alias (a boolean)

Is the item an alias file?

folder (a boolean)

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

package folder (a boolean)

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)

Is the item’s name extension hidden?

visible (a boolean)

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

locked (a boolean)

Is the item locked?

busy status (a boolean)

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

set downloadsFolder to path to downloads folder

    --result: alias "HD:Users:me:Downloads:"

info for downloadsFolder

    --result: {name:"Downloads", folder:true, alias:false, ...}

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 command).

See the application 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

Result

None.

Examples

launch application "TextEdit"

tell application "TextEdit" to launch

Returns the names of the currently mounted volumes.

Syntax

Result

A list of text objects, one for each currently mounted volume.

Returns the names of the items in a specified folder.

Syntax

Result

A list of text objects, one for each item in the specified folder.

Returns a script object loaded from a specified file.

Syntax

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.

Returns the localized text for the specified key.

Syntax

Result

A text 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:

   

3. Add key/value pairs to each Localized.strings file. Each pair is a line of text "key" = "value";, for example:

   

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

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

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

Syntax

Result

None.

Examples

The following shows a simple use of logging:

set area to 7 * 43 as square feet

log area -- result (in Event Log pane): (*square feet 301.0*)

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.

Mounts the specified network volume.

Syntax

Result

None.

Examples

mount volume "afp://myserver.com/" -- guest access

mount volume "http://idisk.mac.com/myname/Public"

mount volume "http://idisk.mac.com/somebody" ¬

    as user name "myname" with password "mypassword"

Finds one piece of text inside another.

Syntax

Result

An integer value indicating the position, in characters, of the source text in the target, or 0 if not found.

Examples

set myString to "Yours, mine, and ours"

offset of "yours" in myString  --result: 1, because case is ignored by default

offset of "mine" in myString  --result: 8

offset of "theirs" in myString  --result: 0, because "theirs" doesn't appear

considering case

    offset of "yours" in myString -- result: 0, because case is now considered

end considering

Opens a file for reading and writing.

Syntax

Result

A file descriptor, as an integer. This file descriptor may be used with any of the other file commands: read, write, get eof, set eof, and close access.

Examples

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

set theFile to (path to desktop as text) & "NewFile"

set referenceNumber to open for access theFile

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

set referenceNumber to open for access theFile with write permission

Opens a URL with the appropriate program.

Syntax

Result

None.

Examples

This example opens an Apple web page:

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

Returns the location of the specified application.

Syntax

Result

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

Examples

path to application "TextEdit"

    --result: alias "Leopard:Applications:TextEdit.app:"

path to  --result: alias "Leopard:Applications:AppleScript:Script Editor.app:"

path to me  --result: same as above

path to it  --result: same as above

path to frontmost application  --result: same as above

path to current application

    --result: same, but could be different for a script application

Returns the location of the specified special folder.

Syntax

Result

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

Examples

path to desktop --result: alias "Leopard:Users:johndoe:Desktop:"

path to desktop as string --result: "Leopard:Users:johndoe:Desktop:"

Returns the location of the specified resource.

Syntax

Result

The location of the specified resource, as an alias.

Examples

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

tell application "Finder"

set gearIconPath to path to resource "Gear.icns"

end

--result: alias "HD:System:Library:CoreServices:Finder.app:Contents:Resources:Gear.icns"

Returns a random number.

Syntax

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

random number  --result: 0.639215561057

random number from 1 to 10  --result: 8

Reads data from a file.

Syntax

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 command for how to create a similar file for reading.)

set fp to open for access file "Leopard:Users:myUser:NewFile"

set myText to read fp until "."

close access fp

display dialog myText

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

Rounds a number to an integer.

Syntax

Result

The rounded value, as an integer if it is within the allowable range (±2²⁹), or as a real 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:

round 1.1 rounding down --result: 1

round -1.1 rounding down --result: -2

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:

set x to 5.1234

set quantum to 0.01

(round x/quantum) * quantum --result: 5.12

round 1.5 --result: 2

round 0.5 --result: 0

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

Result

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

Examples

run application "TextEdit"

tell application "TextEdit" to run

run myScript --where myScript is a script object

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

Runs a specified script or script file.

See also store script.

Syntax

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

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

This example executes a script stored on disk:

set scriptAlias to "Leopard:Users:myUser:Documents:savedScript.scptd:" as alias

run script scriptAlias --result: script is executed

Speaks the specified text.

Syntax

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:

set soundFile to choose file name -- specify name ending in ".aiff"

    --result: a file URL

say "I love oatmeal." using "Victoria" saving to soundFile

    --result: saved to specified sound file

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

Syntax

Result

A list of text items, one for each installed scripting component.

Examples

scripting components --result: {"AppleScript"}

Assigns one or more values to one or more variables.

Syntax

Result

The value assigned.

Examples

set may be used to create new variables:

set myWeight to 125

...assign new values to existing variables:

set myWeight to myWeight + 23

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

set intList to {1, 2, 3}

set item 3 of intList to 42

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

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

set beta to alpha

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

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

{alpha, beta}

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

Both variables show the same changes, because they both refer to the same object. Compare this with the similar example in copy. 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 alpha to {1, 2, 3}

set beta to alpha --result: beta refers to the same object as alpha

set alpha to {4, 5, 6}

    --result: assigns a new object to alpha; this does not affect beta.

{alpha, beta}

--result: {{4, 5, 6}, {1, 2, 3}}

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:

set {x, y} to {1, 2} --now x is 1, and y is 2.

set {x, y} to {y, x} --now x is 2, and y is 1.

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.

Sets the length of a file, in bytes.

Syntax

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 theFile to choose file with prompt "Choose a file to clobber:"

set eof theFile to 0

Places data on the clipboard.

Syntax

Result

None.

Examples

The following script places text on the clipboard, then retrieves the text in TextEdit with a the clipboard command:

set the clipboard to "Important new text."

tell application "TextEdit"

    activate  --make sure TextEdit is running

    set clipText to the clipboard  --result: "Important new text."

    --perform operations with retrieved text

end tell

Sets the sound output, input, and alert volumes.

Syntax

Result

None.

Examples

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

set savedSettings to get volume settings

-- {output volume:32, input volume:70, alert volume:78, output muted:false}

set volume output volume 90

say "This is pretty loud."

set volume output volume (output volume of savedSettings)

delay 1

say "That's better."

Stores a script object into a file.

See also run script.

Syntax

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:

script test

    display dialog "Test"

end script

store script test --specify "Leopard:Users:myUser:Desktop:storedScript"

set localScript to alias "Leopard:Users:myUser:Desktop:storedScript" run script localScript --result: displays dialog "Test"

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.

Summarizes the specified text or text file.

Syntax

Result

A text 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:

set niceSpeech to "Four score and seven years ago our fathers brought forth on this continent a new nation, conceived in Liberty, and dedicated to the proposition that all men are created equal.

Now we are engaged in a great civil war, testing whether that nation, or any nation, so conceived and so dedicated, can long endure. We are met on a great battle-field of that war. We have come to dedicate a portion of that field, as a final resting place for those who here gave their lives that that nation might live. It is altogether fitting and proper that we should do this.

But, in a larger sense, we can not dedicate—we can not consecrate—we can not hallow—this ground. The brave men, living and dead, who struggled here, have consecrated it, far above our poor power to add or detract. The world will little note, nor long remember what we say here, but it can never forget what they did here. It is for us the living, rather, to be dedicated here to the unfinished work which they who fought here have thus far so nobly advanced. It is rather for us to be here dedicated to the great task remaining before us—that from these honored dead we take increased devotion to that cause for which they gave the last full measure of devotion—that we here highly resolve that these dead shall not have died in vain—that this nation, under God, shall have a new birth of freedom—and that government of the people, by the people, for the people, shall not perish from the earth."

set greatSummary to summarize niceSpeech in 1

display dialog greatSummary --result: displays one inspiring sentence

Get environment variables or attributes of this computer.

Syntax

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 attribute

(* result: (for example)

{"PATH", "TMPDIR", "SHELL", "HOME", "USER", "LOGNAME", "DISPLAY", "SSH_AUTH_SOCK", "Apple_PubSub_Socket_Render", "__CF_USER_TEXT_ENCODING", "SECURITYSESSIONID", "COMMAND_MODE"}

*)

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

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

short user name (a text 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 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)

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

user locale (a text object)

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

home directory (an alias 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 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 object)

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

host name (a text object)

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

IPv4 address (a text object)

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

primary Ethernet address (a text object)

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

CPU type (a text object)

The CPU type, for example "Intel 80486".

CPU speed (an integer)

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

physical memory (an integer)

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

Examples

system info --result: long record of information

Returns the contents of the clipboard.

Syntax

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:

set the clipboard to "Add this sentence at the end."

tell application "TextEdit"

    activate  --make sure TextEdit is running

    make new paragraph at end of document 1 with data (return & the clipboard)

end tell

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

Syntax

Result

The integer 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:

set localOffset to time to GMT  --local difference, in seconds

set cupertinoOffset to -8.0 * hours

    --doesn't account for Daylight Savings; may actually be -7.0.

set difference to (localOffset - cupertinoOffset) / hours

display dialog ("Hours to Cupertino: " & difference)

Writes data to a specified file.

Syntax

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.

set fp to open for access file "HD:Users:myUser:NewFile" with write permission

write "Some text. And some more text." to fp

close access fp