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

NetShade 8.3 - Browse privately using an...
NetShade is an anonymous proxy and VPN app+service for Mac. Unblock your Internet through NetShade's high-speed proxy and VPN servers spanning 17 countries. NetShade masks your IP address as you... Read more
Adobe Animate CC 2020 20.0.1 - Animation...
Animate CC 2020 is available as part of Adobe Creative Cloud for as little as $20.99/month (or $9.99/month if you're a previous Flash Professional customer). Animate CC 2020 (was Flash CC) lets you... Read more
Adobe Acrobat DC 19.021.20058 - Powerful...
Acrobat DC is available only as a part of Adobe Creative Cloud, and can only be installed and/or updated through Adobe's Creative Cloud app. Adobe Acrobat DC with Adobe Document Cloud services is... Read more
Adobe Acrobat Reader 19.021.20058 - View...
Adobe Acrobat Reader allows users to view PDF documents. You may not know what a PDF file is, but you've probably come across one at some point. PDF files are used by companies and even the IRS to... Read more
Adobe Flash Player 32.0.0.303 - Plug-in...
Adobe Flash Player is a cross-platform, browser-based application runtime that provides uncompromised viewing of expressive applications, content, and videos across browsers and operating systems.... Read more
Adobe InDesign CC 2019 15.0.1 - Professi...
InDesign CC 2019 is available as part of Adobe Creative Cloud for as little as $20.99/month (or $9.99/month if you're a previous InDesign customer). Adobe InDesign CC 2019 is part of Creative Cloud.... Read more
Adobe Lightroom Classic 9.1 - Import, de...
You can download Lightroom for Mac as a part of Creative Cloud for only $9.99/month with Photoshop, included as part of the photography package. The latest version of Lightroom gives you all of the... Read more
Shredo 1.2.7 - $6.99
Shredo is a beautiful, functional file-shredding and privacy scan utility. It permanently shreds files, folders, and external volumes' contents to keep information secure and impossible for anyone to... Read more
Visual Studio Code 1.41.0 - Cross-platfo...
Visual Studio Code provides developers with a new choice of developer tool that combines the simplicity and streamlined experience of a code editor with the best of what developers need for their... Read more
calibre 4.6.0 - Complete e-book library...
Calibre is a complete e-book library manager. Organize your collection, convert your books to multiple formats, and sync with all of your devices. Let Calibre be your multi-tasking digital librarian... Read more

Latest Forum Discussions

See All

King's Throne, the hugely ambitious...
King's Throne: Game of Lust is a deeply immersive medieval-set idle RPG which sees you playing as an ambitious prince, and sole heir to your father's kingdom. On a seemingly ordinary night whilst wandering the king's castle, you make the shocking... | Read more »
Abyssrium Pole is an upcoming aquarium b...
FleroGames' upcoming Abyssrium Pole has recently hit one million pre-registers, which is very impressive, particularly for a fairly casual looking game. Those who have pre-registered will receive 1000 Pearl when the game launches on 8th January... | Read more »
Two Spies is pretty fun, but it's h...
Two Spies just dropped on the App Store this week, and it looks pretty neat. The game has two players capturing various cities across Europe, with the goal of eventually spotting and striking the other spy down. It may be simple-looking, but after... | Read more »
Two Spies is a turn-based game for iOS t...
There aren't too many games that feature pass and play multiplayer and there are even less where you can only play against people you know, even when playing online. But Two Spies does both of those things and you can get it for iOS right now. [... | Read more »
Solve your way through new low-poly puzz...
The best escape-the-room games don’t just test your creative problem-solving skills – they look great, too. Released in October this year by Antler (the developer of the succesful VR puzzle SVRVIVE: The Deus Helix), Krystopia offers everything you... | Read more »
Get ready for an epic adventure with Pea...
Following a hugely successful pre-registration campaign, Pearl Abyss' much-hyped MMORPG, Black Desert Mobile, has finally arrived for iOS and Android. With some of the most impressive visuals on mobile, a vast open world to explore, an in-depth... | Read more »
Elder Scrolls: Blades has ditched chest...
Elder Scrolls: Blades started out as one of the most hyped mobile games of 2019, boasting some impressive visuals and no shortage of promise. Our hopes were somewhat dashed when it eventually launched and we all became privy to its mishandled... | Read more »
Hands-On with the Pocket City December U...
At the end of last month, Codebrew Games announced an update coming to their popular city-builder, Pocket City some time this month. In this update is the promise of expanding your city out into other regions, enacting policies, and more. The full... | Read more »
Black Desert Mobile is available for pre...
Pearl Abyss' stunning open-world MMORPG, Black Desert Mobile, is set to launch for iOS and Android on December 11th at 12 AM PST (8 AM UTC). However, those looking to get in early and test out the in-depth character customisation will be able to... | Read more »
Extraordinary Ones, NetEase's innov...
NetEase's inventive 5v5 anime MOBA, Extraordinary Ones, has now opened for pre-registration ahead of its global launch in early 2020. The game seems to have received a fairly warm reception from fans after its soft-launch earlier in the year,... | Read more »

Price Scanner via MacPrices.net

Apple Watch Series 3 models on sale at Amazon...
Amazon has Apple Watch Series 3 GPS models on sale for $20 off MSRP, starting at only $179. Their prices are the lowest available for these models from any Apple reseller. Choose Amazon as the seller... Read more
Sunday AirPods Sale: Amazon drops prices to a...
Amazon has new 2019 Apple AirPods on sale today ranging up to $30 off MSRP, starting at $139. Shipping is free: – AirPods Pro: $249 $0 off MSRP – AirPods with Wireless Charging Case: $168.95 $30 off... Read more
Holiday 2019 sale: 11″ iPad Pros for up to $2...
Amazon has new Apple 11″ iPad Pros in stock today and on sale for up to $200 off Apple’s MSRP as part of their Holiday 2019 sale. These are the same iPad Pros sold by Apple in its retail and online... Read more
B&H has 12.9″ WiFi iPad Pros on sale for...
B&H Photo has new 12.9″ WiFi iPad Pros on sale for up to $150 off Apple’s MSRP as part of their Holiday 2019 sale. Overnight shipping is free to many addresses in the US: – 12.9″ 64GB WiFi iPad... Read more
Find the best Holiday 2019 prices on Apple’s...
Our Apple award-winning price trackers are the best place to look for the best deals and lowest prices on Apple gear this 2019 Holiday shopping season. Scan our price trackers for the latest... Read more
13″ 2.4GHz/256GB Silver MacBook Pro on sale f...
Amazon has the Silver 13″ 2.4GHz/256GB 4-Core Touch Bar MacBook Pro on sale for $1499.99 shipped. Their price is $300 off Apple’s MSRP, and it’s the lowest price currently available for a 13″ 2.4GHz... Read more
Sams Club one day sales event December 14th:...
Through midnight Saturday night (December 14th), Sams Club online has several Apple Watch Series 5 models on sale for $40 off MSRP as part of their One Day sales event. Choose free shipping or free... Read more
Total Wireless offers iPhone 6S models for as...
Total Wireless has Apple 32GB iPhone 6S models available starting at $99: – 32GB iPhone 6S: $99.99 – 32GB iPhone 6S Plus: $149.99 A no-contract Total Wireless prepaid plan is required with your... Read more
Get a 4 or 6-core Mac Mini for up to $170 off...
B&H Photo has 4-Core and 6-Core Mac minis on sale for up to $170 off Apple’s standard MSRP as part of their Holiday 2019 sale. Overnight shipping is free to many US addresses: – 3.6GHz Quad-Core... Read more
Amazon restocks base 13″ 1.4GHz MacBook Pro f...
Amazon has restocked the base 13″ 1.4GHz/128GB Space Gray MacBook Pro for $1099.99 shipped. Their price is $200 off Apple’s MSRP, and it’s the cheapest price available for a new MacBook Pro. Amazon... Read more

Jobs Board

*Apple* Mobility Sales Professional - Best B...
**750138BR** **Job Title:** Apple Mobility Sales Professional **Job Category:** Store Associates **Store NUmber or Department:** 000471-Mt Vernon-Store **Job Read more
*Apple* Engineering Specialist (ITC ) - Gene...
…Suitability clearance, per contract requirements. Currently, we are seeking an Apple Engineering Specialist in Washington, DC The responsibilities for candidates in Read more
Senior *Apple* Endpoint Engineer - Leidos (...
…Medicaid Service (CMS) End User environment. Perform specific duties as an Apple Endpoint Engineer in support of the infrastructure operations, hardware, software Read more
Perioperative - RN - ( *Apple* Hill Surgical...
Perioperative - RN - ( Apple Hill Surgical Center) Tracking Code 59281 Job Description Monday - Friday - Part Time - Days Possible Saturdays General Summary: Under Read more
Lead DevOps Engineer - *Apple* - Theorem, L...
Job Summary Apple is looking for a seasoned Lead DevOps Engineer that can lead multiple projects and teams while delivering high quality and performant solutions in Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.