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

Latest Forum Discussions

See All

Can PokeMatch help you find love with Po...
The unofficial Pokemon GO companion app space has exploded almost as fast as the game itself over the last few weeks. Aspiring app developers, many of them working solo, have given us apps that locate Pokemon, keep track of the server status, and... | Read more »
How to get started with Prisma
If there's one thing people like to do more than taking pictures with their smartphones, it's tinkering with those photos in some way. Numerous apps have sprung up over the last several years that allow you to use filters and special effects to... | Read more »
6 Pokemon GO updates you can expect, acc...
Pokemon GO had a scheduled appearance at this year's San Diego Comic-Con for a while, but it was only relatively close to the show that it was upgraded to a spot in Hall H. That's the biggest venue at SDCC, one usually reserved for the largest... | Read more »
How to evolve Eevee in Pokemon GO
By now, almost everyone should be hip to how to evolve Pokemon in Pokemon GO (and if not, there's a guide for that). Just gather enough candy of the appropriate type, feed them all to the Pokemon, and evolution happens. It's a miracle that would... | Read more »
CSR Racing 2: Guide to all game modes
It might not seem like there are all that many ways to go fast in a straight line, but CSR Racing 2 begs to differ. [Read more] | Read more »
Bulb Boy (Games)
Bulb Boy 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: Multi-award winning 2D point & click horror adventure about a boy with a glowing head. | Read more »
5 top free emoji keyboard apps
If we're not at peak emoji yet as a society, it feels like we definitely should be. The emoji concept has gone far beyond what anyone in Japan could have envisioned when the people there unleashed it on an unsuspecting world, but the West has... | Read more »
How to unlock more characters in Disney...
One of the big charms of Disney Emoji Blitz is seeing a wide variety of beloved Disney and Pixar characters transformed into smiling emojis. Even someone like the sneaky Randall from Monsters Inc., who probably never cracked a smile on film, is... | Read more »
Cubway (Games)
Cubway 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: Cubway is a journey with an abstract story of lifecycle of rebirth, called Samsara. Guide the cube through the long way full of dangers... | Read more »
Colorcube (Games)
Colorcube 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: Turn pieces and blend colours in this minimal yet visually stunning puzzler.Over 200 handcrafted and challenging levels. Features... | Read more »

Price Scanner via MacPrices.net

Bare Bones Software Releases Free TextWrangle...
Bare Bones Software has announced the release and immediate availability of TextWrangler 5.5, a significant update to its powerful, free, general purpose text editor for Mac OS X. TextWrangler is a... Read more
Apple’s 2016 Back to School promotion: Free B...
Purchase a new Mac or iPad using Apple’s Education Store and take up to $300 off MSRP. All teachers, students, and staff of any educational institution qualify for the discount. Shipping is free, and... Read more
Apple refurbished iPad Air 2s available start...
Apple has Certified Refurbished iPad Air 2 available starting at $339. Apple’s one-year warranty is included with each model, and shipping is free: - 128GB Wi-Fi iPad Air 2: $499 - 64GB Wi-Fi iPad... Read more
13-inch 2.5GHz MacBook Pro available for $964...
Overstock has the 13″ 2.5GHz MacBook Pro available for $964.21 including free shipping. Their price is $135 off MSRP. Read more
External Keyboard Innovations For iPad Pro (1...
I’m an input device aficionado. With non-touchscreen computers, which includes all Macs, the keyboard and mouse or trackpad are the tactile points of interface between user and machine, and the... Read more
GSK Rheumatoid Arthritis Study Leverages iPho...
Global healthcare products company GlaxoSmithKline (GSK) says that since 2014 they have begun transforming the way they conduct research, by leveraging state-of-the-art digital technologies — a... Read more
Clearance 12-inch Retina MacBooks, Apple refu...
Apple has Certified Refurbished 2015 12″ Retina MacBooks available starting at $929. Apple will include a standard one-year warranty with each MacBook, and shipping is free. The following... Read more
13-inch Retina MacBook Pros on sale for up to...
B&H Photo has 13″ Retina MacBook Pros on sale for up to $150 off MSRP. Shipping is free, and B&H charges NY tax only: - 13″ 2.7GHz/128GB Retina MacBook Pro: $1199 $100 off MSRP - 13″ 2.7GHz/... Read more
13-inch 1.6GHz/128GB MacBook Air on sale for...
Amazon has the 13″ 1.6GHz/128GB MacBook Air on sale for $200 off MSRP for a limited time. Shipping is free: - 13″ 1.6GHz/128GB MacBook Air (sku MMGF2LL/A): $799.99 $200 off MSRP Their price is the... Read more
13-inch 1.6GHz/256GB MacBook Air on sale for...
Amazon has the 13″ 1.6GHz/256GB MacBook Air on sale for $200 off MSRP for a limited time. Shipping is free: - 13″ 1.6GHz/256GB MacBook Air (sku MMGG2LL/A): $999.99 $200 off MSRP Their price is the... Read more

Jobs Board

*Apple* Retail - Multiple Positions, Willow...
Job Description:SalesSpecialist - Retail Customer Service and SalesTransform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
*Apple* Evangelist - JAMF Software (United S...
The Apple Evangelist is responsible for building and cultivating strategic relationships with Apple 's small and mid-market business development field teams. This Read more
*Apple* Solutions Consultant - APPLE (United...
Job Summary As an Apple Solutions Consultant, you'll be the link between our future customers and our products. You'll showcase your entrepreneurial spirit as you Read more
*Apple* Professional Learning Specialist - A...
Job Summary The Apple Professional Learning Specialist is a full-time position for one year with Apple in the Phoenix, AZ area. This position requires a high Read more
*Apple* Picker - Apple Hill Orchard (United...
Apple Hill Orchard, Co. Rte. 21,Whitehall, NY 9/7/16-10/228/16. Pick fresh market or processing apples Productivity of 60 boxes and 80 boxes processing fruit per Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.