What Is in a Script Object

When you enter AppleScript statements in script window in Script Editor, you are working in a top-level script object. All script object definitions follow the same syntax, except that a top-level script object does not have statements marking its beginning and end.

A script object can contain the following:

• Property definitions (optional):

  A property is a labeled container in which to store a value.

• An explicit run handler (optional):

  A run handler contains statements AppleScript executes when the script is run. (For more information, see run Handlers.)

• An implicit run handler (optional):

  An implicit run handler consists of any statements outside of any contained handlers or script objects.

• Additional handlers (optional):

  A handler is the equivalent of a subroutine. (For details, see About Handlers.)

• Additional script objects (optional):

  A script object can contain nested script objects, each of which is defined just like a top-level script object, except that a nested script object is bracketed with statements that mark its beginning and end. (For details, see Script Objects.)

Here is an example of a simple script with one property, one handler, one nested script object, and an implicit run handler with two statements:

property defaultClientName : "Mary Smith"

on greetClient(nameOfClient)

    display dialog ("Hello " & nameOfClient & "!")

end greetClient

script testGreet

    greetClient(defaultClientName)

end script

run testGreet --result: "Hello Mary Smith!"

greetClient("Joe Jones") --result: "Hello Joe Jones!"

The first statement in the run handler is run testGreet, which runs the nested script object testGreet. That script object calls the handler greetClient(), passing the property defaultClientName. The handler displays a dialog, greeting the default client, Mary Smith.

The second statement in the run handler calls greetClient() directly, passing the string "Joe Jones".

Properties

A property of an object is a characteristic that has a single value and a label, such as the name property of a window or the month property of a date. The definition for any AppleScript class includes the name and class for each of its properties. Property names must be unique within a class. Property values can be read/write or read only.

The AppleScript date class, for example, defines both read/write and read only properties. These include the weekday property, which is read only, and the month, day, and year properties, which are read/write. That’s because the value of the weekday property depends on the other properties—you can’t set an arbitrary weekday for an actual date.

The class of a property can be a simple class such as boolean or integer, a composite class such as a point class (made up of two integers), or a more complex class.

Most classes only support predefined properties. However, for the script class, AppleScript lets you to define additional properties. For information on how to do this, see Defining Properties. You can also define properties for record objects.

Elements

An element is an object contained within another object. The definition for any AppleScript class includes the element types it can contain. An object can typically contain zero or more of each of its elements.

For a given element type, an object can contain many elements or none, and the number of elements that it contains may change over time. For example, it is possible for a list object to contain no items (it can be an empty list). At a later time, the same list might contain many items.

Whether you can add elements to or remove elements from an object depends on the class and the element. For example, a text object is immutable—you cannot add or remove text once the object is created. For a list object, you cannot remove items, but you can use the set command to add an item to the beginning or end:

set myList to {1, "what", 3} --result: {1, "what", 3}

set beginning of myList to 0

set end of myList to "four"

myList --result: {0, 1, "what", 3, "four"}

What Is in an Object Specifier

An object specifier describes an object type, a location, and how to distinguish the object from other objects of the same type in that location. These three types of information—the type, or class; the location, or container; and the distinguishing information, or reference form—allow you to specify any object.

In the following example, the class of the object is paragraph. The container is the phrase of document 1. Because this phrase is inside a tell statement, the tell statement provides the top-level container, of application "TextEdit". The distinguishing information (the reference form) is the combination of the class, paragraph, and an index value, 1, which together indicate the first paragraph.

tell application "TextEdit"

    paragraph 1 of document 1

end tell

In addition to the index reference form, you can specify objects in a container by name, by range, by ID, and by the other forms described in Reference Forms.

Containers

A container is an object that contains one or more objects or properties. In an object specifier, a container specifies where to find an object or a property. To specify a container, use the word of or in, as in the following statement (from a Finder tell block):

folder "Applications" of startup disk

A container can be an object or a series of objects, listed from the innermost to the outermost containing object, as in the following:

tell application "Finder"

    first item of first folder of first disk

end tell

You can also use the possessive form ('s) to specify containers. In the following example, the innermost container is first window and the object it contains is a name property:

tell application "TextEdit"

    first window's name

end tell

In this example, the target of the tell statement ("TextEdit") is the outer container for the object specifier.

Absolute and Relative Object Specifiers

An absolute object specifier has enough information to identify an object or objects uniquely. It can be used unambiguously anywhere in a script. For a reference to an application object to be absolute, its outermost container must be the application itself, as in:

version of application "Finder" --result: "10.5.1"

In contrast, a relative object specifier does not specify enough information to identify an object or objects uniquely; for example:

name of item 1 of disk 2

When AppleScript encounters a relative object specifier in a tell statement, it attempts to use the default target specified by the statement to complete the object specifier. Though it isn’t generally needed, this implicit target can be specified explicitly using the keyword it, which is described in The it and me Keywords.

The default target of a tell statement is the object that receives commands if no other object is specified. For example, the following tell statement tells the Finder to get a name using the previous relative object specifier.

tell application "Finder"

    name of item 1 of disk 2

end tell

When AppleScript encounters a relative object specifier outside any tell statement, it tries to complete the object specifier by looking up the inheritance chain described in Inheritance in Script Objects.

Object Specifiers in Reference Objects

When you can create a reference object with the a reference to operator, it contains an object specifier. For example:

tell application "TextEdit"

    set docRef to a reference to the first document

    --result: document 1 of application "TextEdit"

        -- an object specifier

    name of docRef --result: "New Report.rtf"

        -- name of the specified object

end tell

In this script, the variable docRef is a reference whose object specifier refers to the first document of the application TextEdit—which happens to be named “New Report.rtf” in this case. However, the object that docRef refers to can change. If you open a second TextEdit document called “Second Report.rtf” so that its window is in front of the previous document, then run this script again, it will return the name of the now-frontmost document, “Second Report.rtf”.

You could instead create a reference with a more specific object specifier:

tell application "TextEdit"

    set docRef to a reference to document "New Report.rtf"

    --result: document "New Report.rtf" of application "TextEdit"

    name of docRef --result: "New Report.rtf"

end tell

If you run this script after opening a second document, it will still return the name of the original document, “New Report.rtf”, if the document exists.

After you create a reference object with the a reference to operator, you can use the contents property to get the value of the object that it refers to. That is, using the contents property causes the reference’s object specifier to be evaluated. In the following script, for example, the content of the variable myWindow is the window reference itself.

set myWindow to a ref to window "Q1.rtf" of application "TextEdit"

myWindow

    -- result: window "Q1.rtf" of application "TextEdit" (object specifier)

contents of myWindow

    --result: window id 283 of application "TextEdit" (an evaluated window)

get myWindow

    -- result: window "Q1.rtf" of application "TextEdit" (object specifier)

Note that the result of the get command is to return the reference’s object specifier, not to resolve the specifier to the object it specifies.

When it can, AppleScript will implicitly dereference a reference object (without use of the contents property), as in the following example:

set myWindow to a ref to window 1 of application "TextEdit"

name of myWindow --result: "Q1.rtf" (if that is the first window's name)

For related information, see the Discussion section for the reference class.

Types of Commands

Scripts can make use of the following kinds of commands:

• An AppleScript command is one that is built into the AppleScript language. There currently are five such commands: get , set, count, copy, and run. Except for copy , each of these commands can also be implemented by applications. That is, there is an AppleScript version of the command that works on AppleScript objects, but an application can define its own version that works on the object types it defines.

• A scripting addition command is one that is implemented through the mechanism described in Scripting Additions). Although anyone can create a scripting addition (see Technical Note TN1164, Scripting Additions for Mac OS X), this guide documents only the scripting addition commands from the Standard Additions, supplied by Apple as part of macOS. These commands are available to all scripts.

• A user-defined command is one that is implemented by a handler defined in a script object. To invoke a user-defined command outside of a tell statement, simply use its name and supply values for any parameters it requires. The command will use the current script as its target.

  To invoke a user-defined command inside a tell statement, see Calling Handlers in a tell Statement.

• An application command is one that is defined by scriptable application to provide access to a scriptable feature. They are typically enclosed in a tell statement that targets the application. You can determine which commands an application supports by examining its dictionary in Script Editor.

  Scriptable applications that ship with macOS, such as the Finder and System Events applications (located in /System/Library/CoreServices), provide many useful scripting commands.

  Third-party scriptable applications also provide commands you can use in scripts. Many support all or a subset of the Standard commands, described in Technical Note TN2106, Scripting Interface Guidelines. These include commands such as delete, duplicate, exists, and move, as well as application implementations of AppleScript commands, such as get and set.

Target

There are two ways to explicitly specify an object as the target of a command: by supplying it as the direct parameter of the command (described in the next section) or by specifying it as the target of a tell statement that contains the command. If a script doesn’t explicitly specify the target with a tell statement, and it isn’t handled by a handler in the script or by AppleScript itself, it is sent to the next object in the inheritance chain (see The AppleScript Inheritance Chain).

In the following script, the target of the get command is the object specifier name of first window. Because the enclosing tell statement specifies the Finder application, the full specifier is name of first window of application "Finder", and it is the Finder application which obtains and returns the requested information.

tell application "Finder"

    get name of first window

end tell

When a command targets an application, the result may be an application object. If so, subsequent statements that target the result object are sent to the application.

A script may also implicitly specify a target by using an application command imported using a Note statement. For example, the extract address command in the following script targets the Mail application because the command was imported from Mail:

use application "Mail"

extract address from "John Doe <jdoe@example.com>"

Direct Parameter

The direct parameter is a value, usually an object specifier, that appears immediately next to a command and specifies the target of the command. Not all commands have a direct parameter. If a command can have a direct parameter, it is noted in the command’s definition.

In the following statement, the object specifier last file of window 1 of application "Finder" is the direct parameter of the duplicate command:

duplicate last file of window 1 of application "Finder"

The direct parameter usually appears immediately after the command, but may also appear immediately before it. This can be easier to read for some commands, such as exists in this example:

if file "semaphore" of application "Finder" exists then

   -- continue processing...

end if

A tell statement specifies a default target for all commands contained within it, so the direct parameter is optional. The following example has the same result as the previous example:

tell last file of window 1 of application "Finder"

    duplicate

end tell

Parameters That Specify Locations

Many commands have parameters that specify locations. A location can be either an insertion point or another object. An insertion point is a location where an object can be added.

In the following example, the to parameter specifies the location to which to move the first paragraph. The value of the to parameter of the duplicate command is the relative object specifier before paragraph 4, which is an insertion point. AppleScript completes the specifier with the target of the tell statement, front document of application "TextEdit".

tell front document of application "TextEdit"

    duplicate paragraph 1 to before paragraph 4

end tell

The phrases paragraph 1 and before paragraph 4 are called index and relative references, respectively. For more information, see Reference Forms.

AppleScript Constant

The global constant AppleScript provides access to properties you can use throughout your scripts.

You can use the AppleScript identifier itself to distinguish an AppleScript property from a property of the current target with the same name, as shown in the section version.

The following sections describe additional properties of AppleScript.

set circleArea to pi * 7 * 7 --result: 153.9380400259

{"bread", "milk", "butter", 10.45}  as string

"breadmilkbutter10.45"

set AppleScript's text item delimiters to {", "}

{"bread", "milk", "butter", 10.45}  as string

"bread, milk, butter, 10.45"

set AppleScript's text item delimiters to {":"}

get last text item of "Hard Disk:CD Contents:Release Notes"

set savedDelimiters to AppleScript's text item delimiters

try

    set AppleScript's text item delimiters to {"**"}

    --other script statements...

    --now reset the text item delimiters:

    set AppleScript's text item delimiters to savedDelimiters

on error m number n

    --also reset text item delimiters in case of an error:

    set AppleScript's text item delimiters to savedDelimiters

    --and resignal the error:

    error m number n

end try

considering numeric strings

    if version of AppleScript as string ≥ "1.9" then

        -- Perform operations that depend on version 1.9 or greater

    else

        -- Handle case where version is not high enough

    end if

end considering

tell application "Finder"

    version --result: "10.5.1"

    version of AppleScript --result: "2.0"

end tell

current application Constant

The current application constant refers to the application that is executing the current AppleScript script (for example, Script Editor). Because the current application is the parent of AppleScript (see The AppleScript Inheritance Chain), it gets a chance to handle commands that aren’t handled by the current script or by AppleScript.

The current application constant is an object specifier—if you ask AppleScript for its value, the result is the object specifier:

get current application --result: current application

However, if you ask for name of current application, AppleScript resolves the object specifier and returns the current application’s name:

name of current application --result: "Script Editor"

missing value Constant

The missing value constant is a placeholder for missing or uninitialized information.

For example, the following statements use the missing value constant to determine if a variable has changed:

set myVariable to missing value

    -- perform operations that might change the value of myVariable

if myVariable is equal to missing value then

    -- the value of the variable never changed

else

    -- the value of the variable did change

end if

true, false Constants

AppleScript defines the Boolean constants true and false. These constants are described with the boolean class.

Specifying Paths

You can create alias objects and file objects by supplying a name specifier, where the name is the path to an item in the file system.

For alias and file specifiers, the path is an HFS path, which takes the form "disk:item:subitem:subsubitem:...:item". For example, "Hard_Disk:Applications:Mail.app" is the HFS path to the Mail application, assuming your boot drive is named "Hard_Disk".

HFS paths with a leading colon, such as ":folder:file", are resolved relative to the HFS working directory. However, their use is discouraged, because the location of the HFS working directory is unspecified, and there is no way to control it from AppleScript.

For POSIX file specifiers, the path is a POSIX path, which takes the form "/item/subitem/subsubitem/.../item". The disk name is not required for the boot disk. For example, "/Applications/Mail.app" is the POSIX path to the Mail application. You can see the POSIX path of an item in Finder in the "Where" field of its Get Info window. Despite the name, POSIX file specifiers may refer to folders or disks. Use of "~" to specify a home directory is not supported.

POSIX paths without a leading slash, such as "folder/file", are resolved relative to the POSIX working directory. This is supported, but only is useful for scripts run from the shell—the working directory is the current directory in the shell. The location of the POSIX working directory for applications is unspecified.

Working With Aliases

AppleScript defines the alias class to represent aliases. An alias can be stored in a variable and used throughout a script.

The following script first creates an alias to an existing file in the variable notesAlias, then uses the variable in a tell statement that opens the file. It uses a try statement to check for existence of the alias before creating it, so that the alias is only created once, even if the script is run repeatedly.

try

    notesAlias -- see if we've created the alias yet

on error

    -- if not, create it in the error branch

    set notesAlias to alias "Hard_Disk:Users:myUser:Feb_Notes.rtf"

end try

-- now open the file from the alias:

tell application "TextEdit" to open notesAlias

Finding the object an alias refers to is called resolving an alias. AppleScript 2.0 attempts to resolve aliases only when you run a script. However, in earlier versions, AppleScript attempts to resolve aliases at compile time.

Once you run the previous example, creating the alias, the script will be able to find the original file when you run it again, even if the file’s name or location changes. (However, if you run the script again after recompiling it, it will create a new alias.)

You can get the HFS path from an alias by coercing it to text:

notesAlias as text --result: "Hard_Disk:Users:myUser:Feb_Notes.rtf"

You can use the POSIX path property to obtain a POSIX-style path to the item referred to by an alias:

POSIX path of notesAlias --result: "/Feb_Notes.rtf"

If an alias doesn’t refer to an existing file system object then it is broken. You can’t create an alias to an object that doesn’t exist, such as a file you plan to create. For that you use a file object, described in the next section.

For a sample script that shows how a script application can process a list of aliases it receives when a user drops one or more file icons on it, see open Handlers.

Working With Files

AppleScript uses file objects to represent files in scripts. A file object can be stored in a variable and used throughout a script. The following script first creates a file object for an existing file in the variable notesFile, then uses the variable in a tell statement that opens the file:

set notesFile to POSIX file "/Users/myUser/Feb_Meeting_Notes.rtf"

tell application "TextEdit" to open notesFile

You can use a file object to specify a name and location for a file that may not exist:

set newFile to POSIX file "/Users/myUser/BrandNewFile.rtf"

Similarly, you can let a user specify a new file with the choose file name command, then use the returned file object to create the file. In the following example, if the user cancels the choose file name dialog, the rest of the script is not executed. If the user does supply a file name, the script opens the file, creating it if necessary, then uses a try statement to make sure it closes the file when it is finished writing to it.

set theFile to choose file name

set referenceNumber to open for access theFile with write permission

try

    -- statements to write to the file

on error

    close access referenceNumber

end try

close access referenceNumber

Typically, when you pass a file object to a command that uses it to operate on a new or existing item in the file system, the components of the path must exist for the command to succeed.

Enabling Remote Applications

For a script to send commands to a remote application, the following conditions must be satisfied:

• The computer that contains the application and the computer on which the script is run must be connected to each other through a network.

• Remote Apple Events (set in the Sharing preferences pane) must be enabled on the remote computer and user access must be provided (you can allow access for all users or for specified users only).

• If the specified remote application is not running, you must run it.

• You must authenticate as admin when you compile or run the script.

eppc-Style Specifiers

An eppc-style specifier takes the following format:

eppc://[user[:password]@]IP_address

ip_address

Either a numeric IP address in dotted decimal form (four numbers, from 0 to 255, separated by periods; for example, 123.23.23.123) or a hostname. A hostname can be a Bonjour name.

The following are examples of valid eppc-style specifiers. If you supply the user name and password, no authentication is required. If you do not supply it, authentication may be required.

"eppc://myCoolMac.local" -- hostname, no user or pwd

"eppc://myUserName:pwd@myCoolMac.local" -- user, pwd, and hostname

"eppc://123.23.23.123" -- IP address, no user or pwd

"eppc://myUserName:pwd@123.23.23.123" -- user, pwd, and IP address

"eppc://myUserName@server.company.com" -- server address, user

Targeting Remote Applications

You can target an application that is running on a remote machine and you can launch applications on remote machines that are not currently running.

The following example uses an eppc-style specifier to target the Finder on a remote computer. It includes a user name and password, so no authentication is required.

set remoteMachine to "eppc://userName:pwd@MacName.local"

tell app "Finder" of machine remoteMachine to close front window

In some cases, you’ll need to use a using terms from statement to tell AppleScript to compile against the local version of an application. The following example uses that technique in telling the remote Finder application to open the TextEdit application:

set remoteFinder to application "Finder" of machine ¬

    "eppc://myUserName:pwd@123.23.23.123"

using terms from application "Finder"

    tell remoteFinder

        open application file id "com.apple.TextEdit"

    end tell

end using terms from

If you omit the password (pwd) in the previous script, you will have to authenticate when you run the script.

Feedback From Your Script

You can insert various statements into a script to indicate the current location and other information. In the simplest case, you can insert a beep command in a location of interest:

beep 3 -- three beeps; a very important part of the script!

A display dialog command can display information about what’s happening in a script and, like a breakpoint, it halts execution until you dismiss it (or until it times out, depending on the parameters you pass). The following example displays the current script location and the value of a variable:

display dialog "In factorial routine; x = " & (x as string)

The say command can get your attention by speaking the specified text. In the following example, currentClient is a text object that stores a client name:

say "I'm in the clientName handler. The client is " & currentClient

Logging

Script Editor can display a log of the Apple events that are sent during execution of a script. In the Script Editor Preferences, you can also choose to keep a history of recent results or event logs.

In addition, you can insert log statements into a script. Log output is shown in the Event Log pane of a script window, and also in the Event Log History window, if it is open.

The following simple example logs the current word in a repeat with loopVariable (in list) statement:

set wordList to words in "Where is the hammer?"

repeat with currentWord in wordList

    log currentWord

    if contents of currentWord is equal to "hammer" then

        display dialog "I found the hammer!"

    end if

end repeat

The following shows how the words appear in the log when the script is run:

    (*Where*)

    (*is*)

    (*the*)

    (*hammer*)

Third Party Debuggers

If you need full-featured debugging capabilities, there are powerful, third-party AppleScript debuggers available.