Mac Automation Scripting Guide: Using Script Libraries

A script library is a collection of handlers, which can be loaded and used by other scripts. For example, a scripter might compile a set of commonly-used text-processing handlers into a text library. This library could then be shared by multiple scripts that need to perform text processing operations.

Writing Script Libraries

To write a script library, create a Script Editor document that contains one or more handlers, such as the one shown in Listing 14-1 and Listing 14-2, and save it in script format, as shown in Figure 14-1.

image: ../Art/scripteditor_savescriptlibrary_2x.png

APPLESCRIPT

Open in Script Editor

Listing 14-1AppleScript: Handler that converts text to uppercase or lowercase

on changeCaseOfText(theText, theCaseToSwitchTo)
if theCaseToSwitchTo contains "lower" then
set theComparisonCharacters to "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
set theSourceCharacters to "abcdefghijklmnopqrstuvwxyz"
else if theCaseToSwitchTo contains "upper" then
set theComparisonCharacters to "abcdefghijklmnopqrstuvwxyz"
set theSourceCharacters to "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
else
return theText
end if
set theAlteredText to ""
repeat with aCharacter in theText
set theOffset to offset of aCharacter in theComparisonCharacters
if theOffset is not 0 then
set theAlteredText to (theAlteredText & character theOffset of theSourceCharacters) as string
else
set theAlteredText to (theAlteredText & aCharacter) as string
end if
end repeat
return theAlteredText
end changeCaseOfText

JAVASCRIPT

Open in Script Editor

Listing 14-2JavaScript: Function that converts text to uppercase or lowercase

function changeCaseOfText(text, caseToSwitchTo) {
var alteredText = text
if (caseToSwitchTo === "lower") {
alteredText = alteredText.toLowerCase()
}
else if (caseToSwitchTo === "upper") {
alteredText = alteredText.toUpperCase()
}
return alteredText
}

Move the saved script to one of the following folders on your Mac, creating the folder if it doesn’t already exist:

~/Library/Script Libraries/
/Library/Script Libraries/
/Resources/ folder inside a script or app bundle.

For additional information about writing script libraries, see Creating a Library in AppleScript Language Guide and Libraries in JavaScript for Automation Release Notes.

Using Script Libraries

Once a script library is installed, your other scripts can target its handlers at any time.

To target a script library in AppleScript, use a tell statement, as shown in Listing 14-3.

APPLESCRIPT

Open in Script Editor

Listing 14-3AppleScript: Targeting a handler in a script library

tell script "My Text Processor"
changeCaseOfText("scripting is awesome!", "upper")
end tell
--> Result: "SCRIPTING IS AWESOME!"

To target a script library in JavaScript, use the Library command to reference the library. Then, you can target handlers in the referenced library, as shown in Listing 14-4.

JAVASCRIPT

Open in Script Editor

Listing 14-4JavaScript: Targeting a function in a script library

textProcessor = Library("My Text Processor")
textProcessor.changeCaseOfText("scripting is awesome!", "upper")
// Result: "SCRIPTING IS AWESOME!"