TweetFollow Us on Twitter

AppleScript Code Libraries

Volume Number: 22 (2006)
Issue Number: 12
Column Tag: AppleScript Essentials

AppleScript Code Libraries

by Benjamin S. Waldie

If you have been reading my columns for a while (prior to my introductory series on scripting different applications), then you may know that I am somewhat of a subroutine handler fanatic. I feel that handlers are an extremely important part of AppleScript development, and that every AppleScripter should be using them quite often. Unfortunately, many AppleScript developers do not.

There are many benefits to using handlers in a script. Let's discuss a few of these briefly. Handlers provide a mechanism for modularizing AppleScript code into generic chunks, which can be called from multiple locations within a script. This can lead to more efficient script writing. Instead of spending time writing virtually the same code over and over again throughout a script, you can instead focus more time on writing a solid and reliable handler, which can be called numerous times throughout the script. Not only does this help to cut down on the total amount of code you need to write in a script, but it also helps to provide a more focused completed script. Because multiple sections of the script call the same handler code, there are typically fewer areas to troubleshoot if problems do occur during execution. Furthermore, if written modularly enough, it may even be possible to extract a handler from a script, and plug it into other scripts, potentially reducing script writing time in the future too. This leads me into the main focus of this month's column, AppleScript code libraries.

What is an AppleScript Code Library

What exactly is an AppleScript code library? An AppleScript code library, aka a script library, is an AppleScript file that contains pieces of code, usually handlers, which may be loaded and accessed by another script during its execution. AppleScript code libraries provide an excellent way to organize generic chunks of code, to be called by one or more scripts.

For example, suppose you often write scripts that automate tasks in QuarkXPress. The odds are probably pretty good that many of these scripts will perform similar tasks, and many may use similar or identical code. If this were the case, it would make sense to write much of your Quark code as generic handlers, which can then be merged together into a single script file to form a script library. This library of Quark handlers could then be saved into a central location, and then loaded by other scripts in the future, which can then call its handlers as needed.

Building a Script Library

Building a script library is really as straightforward as creating any AppleScript file. There aren't really any hardcore requirements. A script library will often contain handlers, but it doesn't need to. It can contain any thing that any other script can contain, including properties, globals, a run handler, etc. A script library can even load other script libraries.

Preparing to Follow Along

The example code that we will explore throughout this month's column will involve calling code within a script library file. To follow along with these examples, you'll need to create a script library file. Begin by creating a new Script Editor document, and entering the following code.

property someProperty : "Property Value"
display dialog "Running..."
on someHandler()
   display dialog "Handler executing..."
end someHandler
on displayProperty()
   display dialog someProperty
end displayProperty

As you can see, this code that will make up our script library contains a property, some run handler code, and some subroutine handlers. We will walk through the process of accessing each of these elements in our script library from within another script.

Next, we need to save our script library. To do this, just save the Script Editor document as a compiled script to your desktop, and name it My Library.scpt.

Loading a Script Library

Now that we have created our script library, we are ready to begin accessing it from another script. To do this, we will make use of a command that is included in the Scripting Commands suite of the Standard Additions scripting addition, called load script. The load script command accepts one direct parameter, a reference to a script file to be loaded. For example:

set theLibraryPath to alias ((path to desktop folder as string) & "My Library.scpt")
load script theLibraryPath
--> "script"

If you run the above example code, you will find that, in Script Editor's result pane, the result of the load script command is a reference to the newly loaded script library. Like any other result, this reference may be placed into a variable, for later reference throughout your script. For example:

set theLoadedScript to load script theLibraryPath

Types of Scripts that May Be Loaded

Momentarily, we will explore what you can do once you have loaded a script library file. However, I first want to mention the types of script library files that may be loaded. The load script command may be used to load compiled script files, script applications, script bundles, and script application bundles. It may not be used to load scripts that have been saved in text format. Also, if you are using an older version of Mac OS X (pre-10.3.x), then you will not be able to load script bundles or script application bundles. The ability to load these types of scripts was not possible prior to AppleScript version 1.9.2 in Mac OS X 10.3.

Running a Script Library

So, now that we have loaded a script library file, what do we do with it? One thing that we can do with it is run it. This can be done by simply telling the loaded script to run. For example:

set theLibraryPath to alias ((path to desktop folder as string) & "My Library.scpt")
set theLoadedScript to load script theLibraryPath
tell theLoadedScript to run
--> {button returned:"OK"}

If you test this example code, then you will find that telling the loaded script to run will result in the execution of any code located within the loaded script's run handler. See figure 1.



Figure 1. Running a Loaded Script Library

You will also find that, if the run handler of the loaded script produces a result, then that result will be passed back to the loading script as the result of the run command.

There are actually several syntactical variations to running a loaded script. Another way is to use the run command, followed by a reference to the loaded script as a direct parameter. For example:

run theLoadedScript

Yet another way to run a loaded script is to make use of the run script command, which is also found in the Scripting Commands suite in the Standard Additions scripting addition. This command is also followed by a reference to the loaded script as its direct parameter.

run script theLoadedScript

When using the run script command, it's also not actually necessary to load the script prior to running it. The run script command itself may be passed the path to a script file as its direct parameter. This will cause the script file to be loaded and run, all in one shot, as demonstrated here:

run script theLibraryPath

Calling Handlers within a Script Library

While running a loaded script is great, and can sometimes be very useful, the real power comes with the ability to trigger handlers within loaded script libraries. Once a script has been loaded, any of its handlers are at your disposal, and may be called as needed, throughout the loading script.

Handlers in a loaded script are called much in the same way that local handlers are called within a script. Unlike local handlers, however, they must just be directed to the loaded script. Often, this is done through the use of a simple tell statement. In other words, the loading script tells the loaded script to execute a specific handler. For example:

set theLibraryPath to alias ((path to desktop folder as string) & "My Library.scpt")
set theLoadedScript to load script theLibraryPath
tell theLoadedScript to someHandler()
--> {button returned:"OK"}

If you run the previous example code, you will find that the someHandler() handler within the loaded script is executed, as indicated by the dialog the handler displays. See figure 2.



Figure 2. Calling a Handler in a Loaded Script Library

As an alternative to using a tell statement to call a handler within a loaded script, another equally acceptable method is the following, which will perform in exactly the same manner as the previous example.

someHandler() of theLoadedScript

Accessing Properties within a Script Library

Referencing Properties in a Script Library

As one might expect, if a loaded script contains properties, then those properties may be accessed by any code, such as handlers, within the loaded script. For example, here is some example code that will execute a handler within our loaded script. This handler will display the value of a property in the loaded script. See figure 3.

set theLibraryPath to alias ((path to desktop folder as string) & "My Library.scpt")
set theLoadedScript to load script theLibraryPath
tell theLoadedScript to displayProperty()



Figure 3. Calling a Handler in a Loaded Script, to Display a Property Value

Properties within a loaded script may also be accessed by the loading script. This is done similarly to the process of calling handlers in a loaded script from within the loading script. For example:

set theLibraryPath to alias ((path to desktop folder as string) & "My Library.scpt")
set theLoadedScript to load script theLibraryPath
someProperty of theLoadedScript
--> "Property Value"

Modifying Properties in a Script Library

As you may know, when utilized in a script application, properties are persistent between executions of the script. In other words, if you modify the value of a property within a script application, then the modified property value will be retained until the property is modified again, or until the script is recompiled. Upon a recompile, the property will revert to its original value.

Properties in loaded scripts are handled slightly differently. If you modify a property in a loaded script, the modified property value will be retained as long as the script remains loaded. However, the next time the script is loaded, it will revert back to its original value. The modified property value is not retained between loads. This can be demonstrated via the following example code.

set theLibraryPath to alias ((path to desktop folder as string) & "My Library.scpt")
set theLoadedScript to load script theLibraryPath
tell theLoadedScript to displayProperty()
set someProperty of theLoadedScript to "New Property Value"
tell theLoadedScript to displayProperty()

If you run the example code above, you will find that the displayProperty() handler will be called twice. Once, immediately after the script has been loaded, and again, after the value of the property someProperty has been modified to a new value. The first time the displayProperty() handler is called, it will display a dialog indicating the property's original value, shown previously in figure 3. The second time the handler is called, it will display a dialog indicating the property's new value, showing that the property's value has actually been changed. See figure 4.



Figure 4. Calling a Handler in a Loaded Script, to Display a Modified Property Value

Now, to demonstrate that the modified property value is not retained between loads, try running the previous example code a second time. When you do this, you will find that the first time the displayProperty() handler is called, it displays the original unmodified value for property someProperty.

Storing a Modified Script Library

However, it is actually possible to retain a modified property value within a loaded script. To do this, the loaded script must be stored back into itself after the property has been modified. This is done using the store script command, which is found in the Scripting Commands suite in the Standard Additions scripting addition. For example:

set theLibraryPath to alias ((path to desktop folder as string) & "My Library.scpt")
set theLoadedScript to load script theLibraryPath
tell theLoadedScript to displayProperty()
set someProperty of theLoadedScript to "New Property Value"
store script theLoadedScript

In the example code above, notice that, while we have specified the loaded script to be stored, we have not specified where it should be stored. When the store script command is used with only a direct parameter, the script to be stored, you will be prompted to specify where the loaded script is to be stored. See figure 5.



Figure 5. Storing a Script Using a Specified Name and Location

To store the script back to its original file path, we can specify a file path for the store script command's optional in labeled parameter. For example:

store script theLoadedScript in theLibraryPath

When used in this manner to store a script back to its original path, the store script command will attempt to overwrite the existing script file. Because of this, another dialog will be displayed, asking whether the existing file should be replaced. See figure 6.



Figure 6. Storing a Script With or Without Replacing an Existing Script

To allow the loaded script to be stored back to its original path without displaying this dialog, we can make use of another optional labeled parameter for the store script command, replacing. For example:

store script theLoadedScript in theLibraryPath with replacing

Running this example code will now result in our loaded script being stored back to its original path, with no dialog being displayed. If you now load the script again and call the displayProperty() handler, you will find that the new property value has been retained. The modified property value will continue to be retained until it is modified again, or until the script library file is opened and recompiled.

In Closing

Hopefully, you're starting to see the benefits of using script libraries, especially for sharing subroutine handlers among multiple scripts. The example code throughout this column should provide you with a good foundation for starting to create and access your own libraries. Once you feel comfortable using the techniques that we have discussed, you may want to consider exploring some other interesting ways of utilizing script libraries.

Try saving a script library as a stay opened application and pre-launching it to reduce loading time. Then, allow multiple scripts to call the code within the running script library. Also, we've discussed accessing properties in loaded scripts. For extra credit, try also exploring how globals work in loaded libraries. Can globals be shared between the loading script and the loaded script? Perform some tests on your own to find out.

Until next time, keep scripting!


Ben Waldie is the author of the best selling books "AppleScripting the Finder" and the "Mac OS X Technology Guide to Automator", available from <http://www.spiderworks.com>, as well as an AppleScript Training CD, available from <http://www.vtc.com>. Ben is also president of Automated Workflows, LLC, a company specializing in AppleScript and workflow automation consulting. For years, Ben has developed professional AppleScript-based solutions for businesses including Adobe, Apple, NASA, PC World, and TV Guide. For more information about Ben, please visit <http://www.automatedworkflows.com>, or email Ben at <ben@automatedworkflows.com>.

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

OmniOutliner Pro 4.2 - Pro version of th...
OmniOutliner Pro is a flexible program for creating, collecting, and organizing information. Give your creativity a kick start by using an application that's actually designed to help you think. It's... Read more
VLC Media Player 2.2.1 - Popular multime...
VLC Media Player is a highly portable multimedia player for various audio and video formats (MPEG-1, MPEG-2, MPEG-4, DivX, MP3, OGG, ...) as well as DVDs, VCDs, and various streaming protocols. It... Read more
Nisus Writer Pro 2.1.1 - Multilingual wo...
Nisus Writer Pro is a powerful multilingual word processor, similar to its entry level products, but brings new features such as table of contents, indexing, bookmarks, widow and orphan control,... Read more
Tinderbox 6.2.0 - Store and organize you...
Tinderbox is a personal content management assistant. It stores your notes, ideas, and plans. It can help you organize and understand them. And Tinderbox helps you share ideas through Web journals... Read more
OmniOutliner 4.2 - Organize your ideas,...
OmniOutliner is a flexible program for creating, collecting, and organizing information. Give your creativity a kick start by using an application that's actually designed to help you think. It's... Read more
Things 2.5.4 - Elegant personal task man...
Things is a task management solution that helps to organize your tasks in an elegant and intuitive way. Things combines powerful features with simplicity through the use of tags and its intelligent... Read more
NeoOffice 2014.10 - Mac-tailored, OpenOf...
NeoOffice is a complete office suite for OS X. With NeoOffice, users can view, edit, and save OpenOffice documents, PDF files, and most Microsoft Word, Excel, and PowerPoint documents. NeoOffice 3.x... Read more
iPhoto Library Manager 4.2 - Manage mult...
iPhoto Library Manager allows you to organize your photos among multiple iPhoto libraries, rather than having to store all of your photos in one giant library. You can browse the photos in all your... Read more
Web Snapper 3.3.8 - Capture entire Web p...
Web Snapper lets you capture Web pages exactly as they appear in your browser. You can send them to a file as images or vector-based, multi-page PDFs. It captures the whole Web page - eliminating the... Read more
TeamViewer 10.0.41404 - Establish remote...
TeamViewer gives you remote control of any computer or Mac over the Internet within seconds, or can be used for online meetings. Find out why more than 200 million users trust TeamViewer! Free for... Read more

Chainsaw Warrior: Lords of the Night has...
It's time to put the Darkness back in its place now that Chainsaw Warrior: Lords of the Night has officially made it to iOS. | Read more »
A World of Ice and Fire Lets You Stalk 2...
George R. R. Martin’s A World of Ice and Fire, by Random House, is a mobile guide to the epic series. The new update gives you the Journeys map feture that will let you track the movements of 25 different characters. But don't worry, you can protect... | Read more »
Gameloft Announces Battle Odyssey, a New...
Battle Odyssey, Gameloft's newest puzzle RPG, is coming to the App Store next week. Set in the world of Pondera, you will need to control the power of the elements to defend the world from evil. You'll be able to entlist over 500 allies to aid you... | Read more »
Fusion - HDR Camera (Photography)
Fusion - HDR Camera 1.0.0 Device: iOS Universal Category: Photography Price: $1.99, Version: 1.0.0 (iTunes) Description: Fusion creates HDR (high dynamic range) photos by capturing different exposures and then combining them into one... | Read more »
Sago Mini Toolbox (Education)
Sago Mini Toolbox 1.1 Device: iOS Universal Category: Education Price: $2.99, Version: 1.1 (iTunes) Description: Come build with the Sago Mini friends! Use a wrench, try a saw, or hammer some nails. From sewing hand puppets to... | Read more »
You Should Probably Grab Hitman GO While...
Hitman GO is a surprisingly cool (yet also incredibly drastic) departure from the Hitman series. It's well worth playing for any puzzle game fans out there, and at the moment you can get your hands - or garrotte if you will - on it for a mere $0.99... | Read more »
IFTTT is Bringing Do Button and Do Note...
IFTTT has announced Do Button and Do Note for the Apple Watch. Do Button lets you make your own personalized button that can connect to things like your Google Drive, control the temperature in your home with Nest Thermostat, or turn the lights on... | Read more »
How Many Days, Hours, and Minutes Are Le...
Countdown, by Yves Tscherry, is now available on the App Store. The app keeps track of countdowns to your favorite things such as someones birthday or days till the New Year. You can display the time in seconds, minutes, hours, days, weeks, months,... | Read more »
The All-New Misfit 2.0 App is Available...
Misfit has just given their app a complete overhaul. Misfit 2.0 now has a brand new interface with a sleek design and is easier to navigate. You'll be able to sync your Misfit device and look up health and fitness information faster than ever before... | Read more »
Halo: Spartan Strike (Games)
Halo: Spartan Strike 1.0 Device: iOS Universal Category: Games Price: $5.99, Version: 1.0 (iTunes) Description: Delve into 30 challenging missions through cities and jungles using a devastating arsenal of weapons, abilities and... | Read more »

Price Scanner via MacPrices.net

TigerText Introduces First Secure Enterprise...
TigerText, a provider of secure, real-time messaging for the enterprise, has announced the launch of TigerText for the Apple Watch. TigerText for the Apple Watch enables users to securely send and... Read more
The Conservation Fund Partners with Apple To...
The Conservation Fund has announced that it will partner with Apple to help protect working forests in the United States. The Apple initiative will conserve more than 36,000 acres of working... Read more
Clearance 13-inch 2.6GHz Retina MacBook Pro a...
B&H Photo has clearance 2014 13″ 2.6GHz/128GB Retina MacBook Pros now available for $1099, or $200 off original MSRP. Shipping is free, and B&H charges NY sales tax only. Read more
Apple refurbished 2014 13-inch Retina MacBook...
The Apple Store has Apple Certified Refurbished 2014 13″ Retina MacBook Pros available for up to $400 off original MSRP, starting at $979. An Apple one-year warranty is included with each model, and... Read more
iMacs on sale for up to $205 off MSRP, NY tax...
B&H Photo has 21″ and 27″ iMacs on sale for up to $205 off MSRP including free shipping plus NY sales tax only: - 21″ 1.4GHz iMac: $1019 $80 off - 21″ 2.7GHz iMac: $1189 $110 off - 21″ 2.9GHz... Read more
Sale! 16GB iPhone 5S for $1 with service
Best Buy is offering 16GB iPhone 5Ss for $1.00 with 2-year activation at a participating cellular provider. Choose free home shipping and activation, or buy online and activate during in-store pickup... Read more
Apple refurbished 2014 MacBook Airs available...
The Apple Store has Apple Certified Refurbished 2014 MacBook Airs available starting at $679. An Apple one-year warranty is included with each MacBook, and shipping is free. These are currently the... Read more
27-inch 3.5GHz 5K iMac on sale for $2349, sav...
 Adorama has the 27″ 3.5GHz 5K iMac in stock today and on sale for $2349 including free shipping plus NY & NJ sales tax only. Their price is $150 off MSRP. For a limited time, Adorama will... Read more
Save up to $380 on an iMac with Apple refurbi...
The Apple Store has Apple Certified Refurbished iMacs available for up to $380 off the cost of new models. Apple’s one-year warranty is standard, and shipping is free: - 27″ 3.5GHz 5K iMac – $2119 $... Read more
iFixIt Teardown Awards 12-IInch Retina MacBoo...
iFixIt has posted its illustrated teardown of the new 12-inch MacBook Retina. They note that this new MacBook is less than half the thickness of the last Apple notebook called just “MacBook” back in... Read more

Jobs Board

*Apple* Solutions Consultant - Retail Sales...
**Job Summary** As an Apple Solutions Consultant (ASC) you are the link between our customers and our products. Your role is to drive the Apple business in a retail Read more
*Apple* Solutions Consultant - Retail Sales...
**Job Summary** As an Apple Solutions Consultant (ASC) you are the link between our customers and our products. Your role is to drive the Apple business in a retail Read more
*Apple* Watch SW Application Project Manager...
**Job Summary** The Apple Watch software team is looking for an Application Engineering Project Manager to work on new projects for Apple . The successful candidate Read more
*Apple* Solutions Consultant - Retail Sales...
**Job Summary** As an Apple Solutions Consultant (ASC) you are the link between our customers and our products. Your role is to drive the Apple business in a retail Read more
*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.