Creating a Library

The basic requirement for a script to be a script library is its location: it must be a script document in a “Script Libraries” folder in one of the following folders. When searching for a library, the locations are searched in the order listed, and the first matching script is used:

1. If the script that references the library is a bundle, the script’s bundle Resources directory. This means that scripts may be packaged and distributed with the libraries they use.

2. If the application running the script is a bundle, the application’s bundle Resources directory. This means that script applications (“applets” and “droplets”) may be packaged and distributed with the libraries they use. It also enables applications that run scripts to provide libraries for use by those scripts.

3. Any folders specified in the environment variable OSA_LIBRARY_PATH. This allows using a library without installing it in one of the usual locations. The value of this variable is a colon-separated list of paths, such as /opt/local/Script Libraries:/usr/local/Script Libraries. Unlike the other library locations, paths specified in OSA_LIBRARY_PATH are used exactly as-is, without appending “Script Libraries”. Supported in OS X v10.11 and later.

4. The Library folder in the user’s home directory, ~/Library. This is the location to install libraries for use by a single user, and is the recommended location during library development.

5. The computer Library folder, /Library. Libraries located here are available to all users of the computer.

6. The network Library folder, /Network/Library. Libraries located here are available to multiple computers on a network.

7. The system Library folder, /System/Library. These are libraries provided by macOS.

8. Any installed application bundle, in the application’s bundle Library directory. This allows distributing libraries that are associated with an application, or creating applications that exist solely to distribute libraries. Supported in OS X v10.11 and later.

Script libraries also have name, id, and version properties. It is recommended that you define all three, especially for libraries you plan to distribute publicly: doing so allows clients to unambiguously identify particular versions of libraries that have the functionality they need. These properties may be defined either as property definitions within the script itself, or, for script bundles, in the Info.plist file, which can be edited using the Bundle Contents drawer in Script Editor. For details, see the script class reference.

A script library may be a single-file (scpt) or bundle format (scptd). If a library is a bundle, it may define its own terminology.

Using a Library

A script library defines a script object, which a client script may then reference and then send commands to, as described in Sending Commands to Script Objects. Libraries are identified by name:

script "My Library"

AppleScript will search the various Script Library folders, as described above in Creating a Library, and create an instance of the library script. Unlike the result from load script, this instance is shared and persists for at least the lifetime of the client script, so you do not have to save it in a variable, and state will be preserved while the client script is running. For example, given this library script:

property name : "Counter"

property nextNumberProperty : 0

on nextNumber()

    set my nextNumberProperty to my nextNumberProperty + 1

    return my nextNumberProperty

end nextNumber

This client script, despite referencing the library in full both times, will log “1” and then “2”:

tell script "Counter" to log its nextNumber() -- logs "1"

tell script "Counter" to log its nextNumber() -- logs "2"

The AppleScript Inheritance Chain

The top-level script object is the parent of all other script objects, although any script object can specify a different parent object. The top-level script object also has a parent—AppleScript itself (the AppleScript component). And even AppleScript has a parent—the current application. The name of that application (which is typically Script Editor) can be obtained through the global constant current application. This hierarchy defines the inheritance chain that AppleScript searches to find the target for a command or the definition of a term.

Every script object has access to the properties, handlers, and script objects it defines, as well as to those defined by its parent, and those of any other object in the inheritance chain, including AppleScript. That’s why the constants and properties described in Global Constants in AppleScript are available to any script.

Defining Inheritance Through the parent Property

When working with script objects, inheritance is the ability of a child script object to take on the properties and handlers of a parent object. You specify inheritance with the parent property.

The object listed in a parent property definition is called the parent object, or parent. A script object that includes a parent property is referred to as a child script object , or child. The parent property is not required, though if one is not specified, every script is a child of the top-level script, as described in The AppleScript Inheritance Chain. A script object can have many children, but a child script object can have only one parent. The parent object may be any object, such as a list or an application object, but it is typically another script object.

The syntax for defining a parent object is

( property | prop ) parent : variable

variable

An identifier for a variable that refers to the parent object.

A script object must be initialized before it can be assigned as a parent of another script object. This means that the definition of a parent script object (or a command that calls a function that creates a parent script object) must come before the definition of the child in the same script.

Some Examples of Inheritance

The inheritance relationship between script objects should be familiar to those who are acquainted with C++ or other object-oriented programming languages. A child script object that inherits the handlers and properties defined in its parent is like a C++ class that inherits methods and instance variables from its parent class. If the child does not have its own definition of a property or handler, it uses the inherited property or handler. If the child has its own definition of a particular property or handler, then it ignores (or overrides) the inherited property or handler.

Listing 4-1 shows the definitions of a parent script object called Alex and a child script object called AlexJunior.

Listing 4-1  A pair of script objects with a simple parent-child relationship

script Alex

    on sayHello()

        return "Hello, " & getName()

    end sayHello

    on getName()

        return "Alex"

    end getName

end script

script AlexJunior

    property parent : Alex

    on getName()

        return "Alex Jr"

    end getName

end script

-- Sample calls to handlers in the script objects:

tell Alex to sayHello() --result: "Hello, Alex"

tell AlexJunior to sayHello() --result: "Hello, Alex Jr."

tell Alex to getName() --result: "Alex"

tell AlexJunior to getName() --result: "Alex Jr"

Each script object defines a getName() handler to return its name. The script object Alex also defines the sayHello() handler. Because AlexJunior declares Alex to be its parent object, it inherits the sayHello() handler.

Using a tell statement to invoke the sayHello() handler of script object Alex returns "Hello, Alex". Invoking the same handler of script object AlexJunior returns "Hello, Alex Jr"—although the same sayHello() handler in Alex is executed, when that handler calls getName(), it’s the getName() in AlexJunior that is executed.

The relationship between a parent script object and its child script objects is dynamic. If the properties of the parent change, so do the inherited properties of the children. For example, the script object JohnSon in the following script inherits its vegetable property from script object John.

script John

    property vegetable : "Spinach"

end script

script JohnSon

    property parent : John

end script

set vegetable of John to "Swiss chard"

vegetable of JohnSon

--result: "Swiss chard"

When you change the vegetable property of script object John with the set command, you also change the vegetable property of the child script object Simple. The result of the last line of the script is "Swiss chard".

Similarly, if a child changes one of its inherited properties, the value in the parent object also changes. For example, the script object JohnSon in the following script inherits the vegetable property from script object John.

script John

    property vegetable : "Spinach"

end script

script JohnSon

    property parent : John

    on changeVegetable()

        set my vegetable to "Zucchini"

    end changeVegetable

end script

tell JohnSon to changeVegetable()

vegetable of John

--result: "Zucchini"

When you change the vegetable property of script object JohnSon to "Zucchini" with the changeVegetable command, the vegetable property of script object John also changes.

The previous example demonstrates an important point about inherited properties: to refer to an inherited property from within a child script object, you must use the reserved word my or of me to indicate that the value to which you’re referring is a property of the current script object. (You can also use the words of parent to indicate that the value is a property of the parent script object.) If you don’t, AppleScript assumes the value is a local variable.

For example, if you refer to vegetable instead of my vegetable in the changeVegetable handler in the previous example, the result is "Spinach". For related information, see The it and me Keywords.

Using the continue Statement in Script Objects

In a child script object, you can define a handler with the same name as a handler defined in its parent object. In implementing the child handler, you have several options:

• The handler in the child script object can be independent of the one in its parent. This allows you to call either handler, as you wish.

• The handler in the child can simply invoke the handler in its parent. This allows the child object to take advantage of the parent’s implementation (as shown in the script objects below that contain a on identify handler).

• The handler in the child can invoke the handler in its parent, changing the values passed to it or executing additional statements before or after invoking the parent handler. This allows the child object to modify or add to the behavior of its parent, but still take advantage of the parent’s implementation.

Normally, if a child script object and its parent both have handlers for the same command, the child uses its own handler. However, the handler in a child script object can handle a command first, and then use a continue statement to call the handler for the same command in the parent.

This handing off of control to another object is called delegation. By delegating commands to a parent script object, a child can extend the behavior of a handler contained in the parent without having to repeat the entire handler definition. After the parent handles the command, AppleScript continues at the place in the child where the continue statement was executed.

The syntax for a continue statement is shown in continue.

The following script includes two script object definitions, Elizabeth and ChildOfElizabeth.

script Elizabeth

    property HowManyTimes : 0

    to sayHello to someone

        set HowManyTimes to HowManyTimes + 1

        return "Hello " & someone

    end sayHello

end script

script ChildOfElizabeth

    property parent : Elizabeth

    on sayHello to someone

        if my HowManyTimes > 3 then

            return "No, I'm tired of saying hello."

        else

            continue sayHello to someone

        end if

    end sayHello

end script

tell Elizabeth to sayHello to "Matt"

--result: "Hello Matt", no matter how often the tell is executed

tell ChildOfElizabeth to sayHello to "Bob"

--result: "Hello Bob", the first four times the tell is executed;

--   after the fourth time: "No, I’m tired of saying hello."

In this example, the handler defined by ChildOfElizabeth for the sayHello command checks the value of the HowManyTimes property each time the handler is run. If the value is greater than 3, ChildOfElizabeth returns a message refusing to say hello. Otherwise, ChildOfElizabeth calls the sayHello handler in the parent script object (Elizabeth), which returns the standard hello message. The word someone in the continue statement is a parameter variable. It indicates that the parameter received with the original sayHello command will be passed to the handler in the parent script.

A continue statement can change the parameters of a command before delegating it. For example, suppose the following script object is defined in the same script as the preceding example. The first continue statement changes the direct parameter of the sayHello command from "Bill" to "William". It does this by specifying the value "William" instead of the parameter variable someone.

script AnotherChildOfElizabeth

    property parent : Elizabeth

    on sayHello to someone

        if someone = "Bill" then

            continue sayHello to "William"

        else

            continue sayHello to someone

        end if

    end sayHello

end script

tell AnotherChildOfElizabeth to sayHello to "Matt"

--result: "Hello Matt"

tell AnotherChildOfElizabeth to sayHello to "Bill"

--result: "Hello William"

If you override a parent’s handler in this manner, the reserved words me and my in the parent’s handler no longer refer to the parent, as demonstrated in the example that follows.

script Hugh

    on identify()

        me

    end identify

end script

script Andrea

    property parent : Hugh

    on identify()

        continue identify()

    end identify

end script

tell Hugh to identify()

--result: «script Hugh»

tell Andrea to identify()

--result: «script Andrea»