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

FileMaker Pro 19.4.2 - Quickly build cus...
FileMaker Pro is the tool you use to create a custom app. You also use FileMaker Pro to access your app on a computer. Start by importing data from a spreadsheet or using a built-in Starter app to... Read more
Adobe Illustrator 26.0.3 - Professional...
You can download Adobe Illustrator for Mac as a part of Creative Cloud for only $20.99/month. Adobe Illustrator for Mac is the vector graphics classics in the design industry. It is a digital... Read more
WhatRoute 2.4.9 - Geographically trace o...
WhatRoute is designed to find the names of all the routers an IP packet passes through on its way from your Mac to a destination host. It also measures the round-trip time from your Mac to the router... Read more
Notion 2.0.20 - A unified workspace for...
Notion is the unified workspace for modern teams. Notion Features: Integration with Slack Documents Wikis Tasks Release notes were unavailable when this listing was updated. Download Now]]> Read more
Monterey Cache Cleaner 17.0.2 - Clear ca...
Monterey Cache Cleaner is an award-winning general-purpose tool for macOS X. MCC makes system maintenance simple with an easy point-and-click interface to many macOS X functions. Novice and expert... Read more
Firetask Pro 4.6.8 - Innovative task man...
Firetask Pro represents the next generation of easy-to-use, project-oriented task management apps. By combining David Allen's powerful Getting Things Done (GTD®) approach with classical task... Read more
Smultron 13.0.4 - Easy-to-use, powerful...
Smultron 13 is the text editor for all of us. Smultron is powerful and confident without being complicated. Its elegance and simplicity helps everyone being creative and to write and edit all sorts... Read more
Box Sync 4.0.8057 - Online synchronizati...
Box Sync gives you a hard-drive in the Cloud for online storage. Note: You must first sign up to use Box. What if the files you need are on your laptop -- but you're on the road with your iPhone? No... Read more
Audio Hijack 3.8.10 - Record and enhance...
Audio Hijack (was Audio Hijack Pro) drastically changes the way you use audio on your computer, giving you the freedom to listen to audio when you want and how you want. Record and enhance any audio... Read more
Direct Mail 6.0.1 - Create and send grea...
Direct Mail is an easy-to-use, fully-featured email marketing app purpose-built for macOS. Create, send, and track great looking email campaigns that get results. Start your newsletter by selecting... Read more

Latest Forum Discussions

See All

SwitchArcade Round-Up: ‘Pokemon Legends:...
Hello gentle readers, and welcome to the SwitchArcade Round-Up for January 28th, 2022. We’ve got a bunch of new releases to look at today, with a few big hitters, a few mid-level diversions, and a healthy supply of compost. Since it’s Friday, we... | Read more »
Phantom Blade: Executioners, S-Game...
S-Game has kicked off its first Closed Beta Test for Phantom Blade: Executioners, inviting a selected few to get first dibs on the upcoming KungFuPunk action RPG on mobile. The CBT officially begins this January 28th, and beta testers will receive... | Read more »
‘Infinite Galaxy’ First Anniversary: Cel...
Cultivating a new generation of valiant commanders across 240 countries worldwide, Infinite Galaxy has quenched players’ thirst to explore the vastness of space – and there are only more intergalactic adventures to embark on from here on out. Camel... | Read more »
War and Order: How to brave the cold in...
War and Order's 6th-anniversary celebrations are underway, and all in good time too - this season not only brings about fabulous festivities, but it also lets players experience the harsh winter in an entirely new way. [Read more] | Read more »
‘Hidden Folks+’ Is This Week’s New Apple...
The original Hidden Folks from Adriaan de Jongh is an excellent hidden objects game featuring hand drawn visuals. It is an absolute joy to play, and it has now released on Apple Arcade in the form of Hidden Folks+ () as an App Store great. If you’... | Read more »
Mini Metro’s First Big Update of 2022 Ad...
Last year saw great updates for Dinosaur Polo Club’s Mini Metro ($3.99) which is also available on Apple Arcade as an App Store Great. | Read more »
SwitchArcade Round-Up: ‘Gunvolt Chronicl...
Hello gentle readers, and welcome to the SwitchArcade Round-Up for January 27th, 2022. In today’s article, we’ve got a whole bunch of new releases to check out. It’s a dangerous one for the wallet today, as there are several interesting games to... | Read more »
SIEGE: Apocalypse lets you engage in mil...
Launching today to the delight of military enthusiasts across the globe, SIEGE: Apocalypse is a new 1v1 military battler from KIXEYE that's set in the early days of the War Commander universe. Players need to collect and upgrade unit cards to build... | Read more »
‘SIEGE: Apocalypse’, KIXEYE’s Military-T...
Military fans across the globe now have more reasons to dive into the War Commander universe as KIXEYE launches SIEGE: Apocalypse on both iOS and Android devices today. The 1v1 military battler pits two players against each other in intense real-... | Read more »
‘Yu-Gi-Oh! Master Duel’ Is Rolling Out N...
Following its launch on PC and all consoles last week, Yu-Gi-Oh! Master Duel has finally released on mobile platforms. Since launch, the game has exploded on multiple platforms with it having over 260k concurrent players on Steam. It has full... | Read more »

Price Scanner via MacPrices.net

Apple has clearance 2020 13″ MacBook Airs ava...
Apple has clearance, Certified Refurbished, 2020 13″ Intel-based MacBook Airs in stock today starting at only $719 and up to $370 off original MSRP. Each MacBook features a new outer case, comes with... Read more
The cheapest iPhones for sale today at Apple...
Apple has restocked Apple Certified Refurbished iPhone 8 models starting at only $359. Each refurbished iPhone comes with a fresh external case, standard Apple 1-year warranty, and free shipping.... Read more
14″ MacBook Pro with Apple M1 Max CPU now in...
Looking for a new 14″ MacBook Pro with an Apple M1 Max CPU? Stock is finally trickling into Apple resellers. B&H has Silver 14″ M1 Max MacBook Pros in stock today for $2899 including free 1-2 day... Read more
14″ MacBook Pros with Apple M1 Pro CPUs are i...
Amazon is reporting stock of 14″ MacBook Pros with M1 Pro CPUs today with a $50 discount. Shipping is free, and delivery is available by February 1st for most configurations. Be sure to make your... Read more
Apple has restocked 13″ M1 MacBook Pros for $...
Apple has restocked a full line of 13″ M1 MacBook Pros available Certified Refurbished, starting at only $1099 and up to $230 off original MSRP. These are the cheapest M1 MacBook Pros for sale today... Read more
Apple’s AirPods Max headphones are on sale fo...
Amazon has Silver, Blue, and Space Gray Apple AirPods Max headphones on sale today for $100 off MSRP. Shipping is free, and all models are in stock today. Their price is the lowest currently... Read more
Open a new line of service at Verizon and get...
Verizon is giving away 64GB Apple iPhone 12 minis or your choice of an iPhone 11 to customers who choose one of these phones and open a new line of service. Offer is available online only, and no... Read more
Open-box 13″ M1 MacBook Airs now available st...
QuickShip Electronics has open-box return 13″ M1 MacBook Airs in stock and on sale for $200-$400 off MSRP on their eBay store right now with free express delivery. According to QuickShip, “The item... Read more
Verizon’s 2022 iPad promo: $100-$310 off any...
Verizon has cellular-capable iPads on sale for $100-$310 off MSRP when purchased with an Unlimited service plan. Sale price is applied to your account monthly over a 24 or 30 month period, depending... Read more
Sunday Sale: Apple AirPods are on sale for up...
Amazon has Apple AirPods on sale for $10-$100 off MSRP today, depending on the model. All are in stock today with free delivery: – AirPods Max headphones (Blue): $449 $100 off MSRP – AirPods Max... Read more

Jobs Board

Registered Nurse (RN) Employee Health PSJH -...
…is calling for a Registered Nurse (RN) Employee Health PSJH to our location in Apple Valley, CA.** We are seeking a Registered Nurse (RN) Employee Health PSJH to be Read more
Systems Administrator - Pearson (United State...
…and troubleshoot Windows operating systems (workstation and server), laptop computers, Apple iPads, Chromebooks and printers** + **Administer and troubleshoot all Read more
IT Assistant Level 1- IT Desktop Support Anal...
…providing tier-1 or better IT help desk support in a large Windows and Apple environment * Experience using IT Service Desk Management Software * Knowledge of IT Read more
Human Resources Business Partner PSJH - Provi...
…**is calling a** **Human Resources Business Partner, PSJH** **to our location in Apple Valley, CA.** **Applicants that meet qualifications will receive a text with Read more
Manager Community Health Investment Programs...
…is calling a Manager Community Health Investment Programs PSJH to our location in Apple Valley, CA.** **Qualified candidates will be invited to do a self-paced video Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.