Reference Forms

This chapter describes AppleScript reference forms. A reference form specifies the syntax for identifying an object or group of objects in an application or other container—that is, the syntax for constructing an object specifier (described in Object Specifiers).

For example, the following object specifier (from a script targeting the Finder) uses several index reference forms, which identify an object by its number within a container:

item 1 of second folder of disk 1

Specifies an arbitrary object in a container. This form is useful whenever randomness is desired.

Because an arbitrary item is, by its nature, random, this form is not useful for operations such as processing each item in a group of files, words, or other objects.

Syntax

some  class

Placeholders

class

The class for an arbitrary object.

Examples

The following creates a new Mail message with a random signature (and depends on the user having at least one signature):

tell application "Mail"

    activate

    set randomSignature to some signature

    set newMessage to make new outgoing message ¬

        at end of outgoing messages with properties ¬

        {subject:"Guess who?", content:"Welcome aboard.", visible:true}

    set message signature of newMessage to randomSignature

end tell

The following simply gets a random word from a TextEdit document:

tell application "TextEdit"

    some word of document 1 -- any word from the first document

end tell

Specifies every object of a particular class in a container.

Syntax

every  class 

pluralClass

Placeholders

class

A singular class (such as word or paragraph).

pluralClass

The plural form for a class (such as words or paragraphs).

Value

The value of an every object specifier is a list of the objects from the container. If the container does not contain any objects of the specified class, the list is an empty list: {}. For example, the value of the expression every word of {1, 2, 3} is the empty list {}.

Examples

The following example uses an every object specifier to specify every word contained in a text string:

set myText to "That's all, folks"

every word of myText --result: {"That's", "all", "folks"} (a list of three words)

The following object specifier specifies the same list:

words of myText

The following example specifies a list of all the items in the Users folder of the startup disk (boot partition):

tell application "Finder"

    every item of folder "Users" of startup disk

end tell

The following specifies the same list as the previous example:

tell application "Finder"

    items of folder "Users" of startup disk

end tell

Specifies all objects in a container that match a condition, or test, specified by a Boolean expression.

The filter form specifies application objects only. It cannot be used to filter the AppleScript objects list, record, or text. A term that uses the filter form is also known as a whose clause.

A filter reference form can often be replaced by a repeat statement, or vice versa. For example, the following script closes every TextEdit window that isn’t named "Old Report.rtf":

tell application "TextEdit"

    close every window whose name is not "Old Report.rtf"

end tell

You could instead obtain a list of open windows and set up a repeat statement that checks the name of each window and closes the window if it isn’t named "Old Report.rtf". However, a whose clause is often the fastest way to obtain the desired information.

The following is an abbreviated form of the previous script:

windows of application "TextEdit" whose name is not "Old Report.rtf"

For related information, see repeat Statements.

Syntax

objectSpecifier  ( whose | where )  booleanTest 

Placeholders

objectSpecifier

Specifies the container in which to look for objects that match the Boolean test.

whose | where

These words have the same meaning, and refer to all of the objects in the specified container that match the conditions in the specified Boolean expression.

booleanTest

Any Boolean expression (see the boolean class definition).

Value

The value of a filter reference form is a list of the objects that pass the test. If no objects pass the test, the list is an empty list: {}.

Examples

The following example shows an object specifier for all open Finder windows that do not have the name "AppleScript Language Guide".

tell application "Finder"

    every window whose name is not "AppleScript Language Guide"

end tell

every window whose zoomed is true

tell application "Finder"

    (files whose file type is not "APPL") in folder "HD:SomeFolder:"

end tell

tell application "Finder"

    it --result: application "Finder" (target of tell statement)

    set myFolder to path to home folder

        --result: alias "Leopard:Users:myUser:"

    files in myFolder --result: a list of Finder document files

    files in myFolder where name of it contains "AppleScript"

    (* result: document file "AppleScriptLG.pdf" of folder "myUser"

        of folder "Users" of startup disk of application "Finder"}*)

    files in myFolder where name contains "AppleScript" -- same result

    every file in myFolder whose name contains "AppleScript" -- same result

    every file in myFolder where name of it contains "AppleScript"

        -- same result

end tell

windows whose zoomed is true and floating is false

Specifies an object by the value of its id property.

You can use the ID reference form only with application objects that have an ID property.

Syntax

class id  expression

Placeholders

expression

The id value.

Examples

The following examples use the ID reference form to specify an application by ID and a disk object by ID.

tell application id "com.apple.finder"

-- specifies an application (Finder) by its ID

disk id -100 -- specifies a Finder disk object by ID

name of disk id -100 --result: "Leopard_GM" (gets name from ID specifier)

end tell

Specifies an object by describing its position with respect to the beginning or end of a container.

For related information, see Relative.

Syntax

class [ index ] integer

integer (st | nd | rd | th ) class

( first | second | third | fourth | fifth | sixth | seventh | eighth | ninth | tenth ) class

( last | front | back ) class

Placeholders

class

The class of the indexed object to obtain.

integer

An integer that describes the position of the object in relation to the beginning of the container (if integer is a positive integer) or the end of the container (if integer is a negative integer).

st | nd | rd | th

Appended to the appropriate integer to form an index. For example, 1st, 2nd, 3rd.

first | second | third | fourth | fifth | sixth | seventh | eighth | ninth | tenth

Specify one of the ordinal indexes.

The forms first, second, and so on are equivalent to the corresponding integer forms (for example, second word is equivalent to 2nd word). For objects whose index is greater than 10, you can use the forms 12th, 23rd, 101st, and so on. (Note that any integer followed by any of the suffixes listed is valid; for example, you can use 11rd to refer to the eleventh object.)

last | front | back

The front form (for example, front window) is equivalent to class 1 (window 1) or first class (first window). The last and back forms (for example, last word and back window) refer to the last object in a container. They are equivalent to class -1 (for example, window -1).

Examples

Each of the following object specifiers specifies the first item on the startup disk:

item 1 of the startup disk

item index 1 of the startup disk -- "index" is usually omitted

the first item of the startup disk

The following object specifiers specify the second word from the beginning of the third paragraph:

word 2 of paragraph 3

2nd word of paragraph 3

second word of paragraph 3

The following object specifiers specify the last word in the third paragraph:

word –1 of paragraph 3

last word of paragraph 3

The following object specifiers specify the next-to-last word in the third paragraph.

word –2 of paragraph 3

-2th word of paragraph 3

Specifies the middle object of a particular class in a container. This form is rarely used.

Syntax

middle  class 

Placeholders

class

The class of the middle object to obtain.

Examples

tell application "TextEdit"

    middle paragraph of front document

end tell

middle item of {1, "doughnut", 33} --result: "doughnut"

middle item of {1, "doughnut", 22, 33} --result: "doughnut"

middle item of {1, "doughnut", 11, 22, 33} --result: 11

Specifies an object by name.

Syntax

class  [ named ]  nameText 

Placeholders

class

The class for the specified object.

nameText

The value of the object’s name property.

Examples

The following statements identify objects by name:

document "Report.rtf"

window named "logs"

tell application "Finder"

    item 1 of disk "Hard Disk"

end tell

Specifies a property of an object.

Syntax

propertyLabel

Placeholders

propertyLabel

The label for the property.

Examples

The following example is an object specifier to a property of a Finder window. It lists the label for the window’s property (zoomed) and its container (front window). zoomed is a Boolean property.

zoomed of front window -- e.g., false, if the window isn't zoomed

For many objects, you can obtain a list of properties:

tell app "Finder"

     properties of window 1 --result: a list of properties and their values

end tell

The following example is an object specifier to the UnitPrice property of a record object. The label of the property is UnitPrice and the container is the record object.

UnitPrice of {Product:"Super Snack", UnitPrice:0.85, Quantity:10} --result: 0.85

Specifies a series of objects of the same class in the same container. You can specify the objects with a pair of indexes (such as words 12 thru 24) or with a pair of boundary objects (integers from integer 1 to integer 3).

Syntax

every  class  from  boundarySpecifier1  to  boundarySpecifier2 

pluralClass  from  boundarySpecifier1  to  boundarySpecifier2

class  startIndex  ( thru | through )  stopIndex 

pluralClass  startIndex  ( thru | through )  stopIndex

Placeholders

class

A singular class (such as window or word).

pluralClass

A plural class (such as windows or words).

boundarySpecifier1 and boundarySpecifier2

Specifiers to objects that bound the range. The range includes the boundary objects. You can use the reserved word beginning in place of boundarySpecifier1 to indicate the position before the first object of the container. Similarly, you can use the reserved word end in place of boundarySpecifier2 to indicate the position after the last object in the container.

startIndex and stopIndex

The indexes of the first and last object of the range (such as 1 and 10 in words 1 thru 10).

Though integer indexes are the most common class, the start and stop indexes can be of any class. An application determines which index classes are meaningful to it.

Value

The value of a range reference form is a list of the objects in the range. If the specified container does not contain objects of the specified class, or if the range is out of bounds, an error is returned. For example, the following range specifier results in an error because there are no words in the list:

words 1 thru 3 of {1, 2, 3} --result: an error

Examples

The following example shows the boundary object form of a range specifier. When you compile this statement, Script Editor converts from integer 1 to integer 2 to the form integers 1 thru 2.

set intList to integers from integer 1 to integer 2 of {17, 33, 24}

     --result: {17, 33}

In the next example, the phrase folders 3 thru 4 is a range specifier that specifies a list of two folders in the container startup disk:

tell application "Finder"

    folders 3 thru 4 of startup disk

end tell

--result: a list of folders (depends on contents of startup disk)

name of folders 2 thru 3 of startup disk

text from word 1 to word 4 of "We're all in this together"

--result: "We're all in this"

words 1 thru 4 of "We're all in this together"

--result: {"We're", "all", "in", "this"}

Specifies an object or an insertion point in a container by describing a position in relation to another object, known as the base, in the same container.

Syntax

[ class ] ( before | [in] front of ) baseSpecifier

[ class ] ( after | [in] back of | behind ) baseSpecifier

Placeholders

class

The class identifier of the specified object. If you omit this parameter, the specifier refers to an insertion point.

baseSpecifier

A specifier for the object.

before | [in] front of

These forms are equivalent, and refer to the object immediately preceding the base object.

after | [in] back of | behind

These forms are equivalent, and refer to the object immediately after the base.

beginning | front

These forms are equivalent, and refer to the first insertion point of the container (insertion point 1).

end | back

These forms are equivalent, and refer to the last insertion point of the container (insertion point -1).

Although terms such as beginning and end sound like absolute positions, they are relative to the existing contents of a container (that is, before or after the existing contents).

Examples

The two relative specifiers in the following tell block specify the same file by identifying its position relative to another file on a disk:

tell application "Finder"

    item before item 3 of startup disk --result: e.g., a specifier

    item after item 1 of startup disk --result: e.g., a specifier

end tell

The following example shows how to use various relative specifiers in a word processing document:

tell first document of application "TextEdit"

    copy word 1 to before paragraph 3

    copy word 3 to in back of paragraph 4

    copy word 1 of the last paragraph to behind the third paragraph

end tell