TweetFollow Us on Twitter

AppleScript Dynamic Debugging

Volume Number: 13 (1997)
Issue Number: 8
Column Tag: Scripting

Dynamic Debugging of AppleScript

by Cal Simone, Main Event

Special debugging techniques for a special language

Talking About AppleScript

AppleScript is the scripting language of the MacOS. Much of AppleScript's syntax resembles that of a human language -- in many cases, you can write grammatically correct, imperative sentences to control your computer. But the experience of debugging AppleScript scripts can differ significantly from that of debugging a regular application.

In this article, I'll discuss:

  • Debugging programs in traditional programming languages.
  • What's different about debugging AppleScript.
  • What comprises dynamic debugging
  • How to debug an AppleScript script using these techniques.
  • Special topics, such as debugging handlers, messages that originate from outside a script application, and AppleScript CGIs.
  • Some extra AppleScript debugging goodies.

Lather, Rinse, and Repeat (The Traditional Debugging Cycle)

In most traditional programming languages the debugging process goes something like this:

  • Type, copy, and paste in an editor to create and modify your source code.
  • Compile your program into executable 68000 or PowerPC machine code.
  • Run your program.
  • Discover a bug and figure out the problem.
  • Repeat this cycle until there are no more bugs.

For traditional programming languages, this edit-compile-run-debug cycle is normally fine. When you start your C program over each time to run it, you'll usually start over executing your program with a clean slate -- everything's gone when you start anew.

Debugging in AppleScript

AppleScript differs from most traditional programming languages in a number of ways:

  • AppleScript has a natural-language syntax. It often consists of human-readable constructs such as tell the application "WordPerfect" to print the second window. Because of this human-readability factor, AppleScript's audience includes more than hard-core software developers. Programmers possess the abilities to think logically, to pay very close attention to detail, and to work adeptly with abstract symbolic notation. But a much wider variety of experience and technical skills are found among scripters -- in fact, many people who write in AppleScript can't or don't program in regular programming languages; a great many don't even think of themselves as programmers. While they can think logically and do well with detail, they aren't comfortable translating more cryptic symbolic notation into a set of instructions. So, in addition to software developers, among scripters we find power users, system administrators, and the guy or gal who helps others in their department set up scripts to make their work a little easier. (Even the nomenclature is different in the AppleScript world -- we see terms such as "command", "handler", and "message", instead of words like "statement", "function", and "code".)
  • AppleScript does interapplication communication. A great deal of AppleScript's power is drawn by leveraging other existing applications, known in the AppleScript world as target applications. A single line of AppleScript can send an interapplication message (an Apple event) to a target application that may cause a thousand lines of C code to be executed in that application. What's different in a scripting scenario is that, when you encounter a bug, fix it, and run the script again from the beginning, you're not just starting the script over -- one or more target applications may be part way through a scenario. For example, the script may cause target applications to create or delete documents, files, or database records, and data (and visual representation of data) may be rearranged or transformed. Further, some of these applications may be on other computers. Each time you start your script from the beginning, these target applications must be reset to their respective starting points. If you're ever going to get done debugging, starting the script over each time isn't really an acceptable solution.
  • AppleScript is extensible. Because any application or scripting addition can extend the AppleScript language, the vocabulary and the meaning of that vocabulary can be different, depending on which application you're communicating with or controlling. So, while debugging, you must be able to probe the target applications as well as the script.

The Dynamic Debugging Experience

To me, the essence of dynamic debugging encompasses the ability to affect the scenario in which a program or script runs, while executing step by step, and the ability to affect the program or script's state when a bug is encountered, without the necessity of starting over. Some dynamic languages (and occasionally interpreted languages) do have dynamic debugging mechanisms. SmallTalk, LISP, and Dylan are examples of such dynamic languages.

Changing state

Nearly all development environments for compiled languages, whether dynamic or not, have facilities for watching the values of variables change as the program executes. Some also allow modification of data values in the middle of debugging, thereby affecting the program's state. To do proper debugging in AppleScript, you must be able to modify a script's variables.

Affecting the scenario

Some dynamic language environments provide the ability to execute individual statements on the fly while debugging a program, as if the statements were typed inline. Because of AppleScript's interapplication communication capabilities, there'll be times when you'll have to modify the scenario outside the script, including target applications that the script is communicating with or controlling.

Furthermore, depending on how you're using AppleScript, you may also have to handle messages that originate from sources outside the script. This is particularly necessary if a script is going to be used as a standalone application, such as an AppleScript CGI application for your Web server.

Because of the rich set of tools available, many of which were developed specifically for use with AppleScript, I'll be using Scripter to demonstrate the debugging techniques described in this article. (Information about Scripter is available from When Scripter was designed, the goal was to make the experience of debugging reflect the way AppleScript works. Also, the process of debugging scripts had to be made easily accessible to people who have never used a debugger before, and yet provide the serious scripter with advanced tools for perfecting larger production systems based on AppleScript.

Tackling the beast

In the Scripter environment, while stopped at a particular command in the script, you can fiddle with your script's variables, evaluate expressions, and execute commands.

In the Observe window, you can watch the values of variables and expressions as your script executes each step. More importantly, you can define or modify the value of any variable while stopped at a step. Note that the values you see or change are applicable to the scope of the handler currently being executed or the top level. (A handler is a routine that is either called like a regular subroutine or executed upon receiving an Apple event message from another application. The top level consists of commands that aren't in any handler and executes when you run the script.)

While stopped at a step, you can type, paste, or drag any AppleScript commands into the Instant window and execute them as though you had typed them inline. Those commands can use and modify variables as well as execute handlers in the script. This means you can often repair problems when you encounter them. Sometimes, by fixing things as you go, you can reach the bottom of the script in a single debugging session, having found all your problems. As in the Observe window, commands executing in the Instant window apply to the scope of the current handler or top level.

When you're done debugging, you have to go back and fix up your script's source code. I don't know about you, but I usually figure I've only got one or two problems to fix -- they'll take only 10 minutes -- and the script will be perfect, right? A few hours later, having found all the bugs, you emerge bleary-eyed, but triumphant, at the bottom of your script, something that might have taken you two or three days if you had to modify the source code and start over each time! However, now you've got to fix up your script, which means you have to remember what you did at the beginning of your debugging session. And naturally you always write everything down -- NOT!

To help you figure out what you need to modify, there's a Log window that shows you not only the commands you stepped through (and the results generated by each of those commands), but also your errors and the fixes you applied. So what you end up with is a guide to fixing up your source code after the debugging session.

Let's Do One (A Debugging Session)

Consider the following simple, yet problematic script:

global a

to BumpAndSquare(x)
  set temp to x + 1
  set temp to temp * temp
  return temp
end BumpAndSquare

set a to 1
set b to c
set b to the result
tell the application "Finder"
  close the front window
end tell

Before you start, close all the windows in the Finder (or you can use another application that supports the object model). You can watch the values of a, b, and c in the Observe window. As you step through the script (using the Step or Auto Step menu command in the Script menu), first a is set to 1, then you encounter an error on the second line, because you can't use c before it's been given an value. Figure 1 shows the Observe window when this error is encountered.

Figure 1. Watching variables.

You can double-click the "undefined" value for c and enter a number (for example, 6) to give c a new value. Now the second line will work, and you can continue stepping through your script without having to start over. Incidentally, if you step into a handler (by holding down the Shift key while stepping), then you can modify the values of variables that the handler has access to. In the example, while stepping inside the BumpAndSquare handler, you can see and modify the values of a, x, and temp, but not b or c. Clicking on the Observe window's twist-down triangle will show which hander you're currently in.

Later in the script you'll encounter another error because the target application has no windows to close. In the Instant window, you can tell the Finder to open the startup disk as shown in Figure 2. (If you're targeting a different application, tell it to make a new window or document.) Again, the line with the error will now work, and you can continue stepping through your script.

Figure 2. Executing a command "on-the-fly."

Next, if you open the Log window, and start your debugging session again, you'll see what you've executed, and when you apply the fixes, they are also shown. (See Figure 3.) Now you can use the log as a road map for adjusting your source code to fix the bugs you found and to handle problems you might encounter, such as finding out if the front window exists before attempting to close it.

Figure 3. A debugging session Log.


Along the way, the Command window offers a number of interesting possibilities for exploration. If you want to try out a series of single commands to see the cumulative effect, you can type a line of AppleScript in the Command window and execute it, then type another line and execute that, and see the effect of each new line on what came before it This experimentation can be carried on without affecting the scripts in other editing windows.

You can also associate the Command window with a particular application and have a "conversation" using AppleScript commands, to get information about that application's properties and objects, or to try out various possibilities to help you figure out the right way to express a particular action.

Debugging Handlers

In AppleScript any handler in a script can be called from within the script or from another application. Trying to debug a handler can be tricky. You could comment out the handler declaration (the to or on lines) and the end line, then type set commands to simulate the parameter passing, and step through the resulting script as if commands in the handler were top-level commands. Or you could type up a fake call and step into it from the top level of the script (as in the example above).

Both of these methods have drawbacks. First, having to change and reverse what you do each time you save the script is a pain. Also, you are breaking a cardinal rule of programming -- debugging a version of your script that's different from the final one you're going to use. Not only might things behave differently between your original and modified versions, but worse, if you forget, and save the script with your modifications, then you'll have extra top-level commands that you definitely don't want.

An integral part of the dynamic debugging scenario in Scripter is the Call Box. You can start a debugging session for a particular handler by typing and initiating a call. In the previous example, you'd type a call like BumpAndSquare(7 * 6). Upon calling the handler (see Figure 4), the step indicator in the script window points to the first line and you can step normally through the call. The Observe, Instant, and Log windows are available to you while debugging. When the call returns, the result will be appear in the Call Box, so you can see what your handler would return to the caller.

Figure 4. Calling a handler.

Calls from outside the script

Even more tricky is debugging Apple event messages sent to your script from another application. After clicking two check boxes (one in the Call Box and one in the script window), You are now set up to debug messages received by your script. To stimulate this, you can send an Apple event message to Scripter from Apple's Script Editor (or any application that could send Apple event messages), by executing the following script:

tell the application "Scripter"
   set x to 7
   set y to 6
   BumpAndSquare(x * y)
end tell

The message BumpAndSquare(42), complete with the parameter value 7 * 6 evaluated to 42, appears in the Call box. Then you can call the handler using this message, step through the handler, and the result will be returned back to the sender (in this case Apple's Script Editor, or whatever application sent the message) -- true interapplication message debugging!

If your script is going to be used as a standalone application, such as a CGI application, you can use a technique called "live editing" to arrange for the actual messages normally sent to that application to be sent to Scripter's Call Box. Real CGI data values from your Web server can appear in the Call Box. (See Figure 5.) So you can debug not only the parts of your script that handle messages, but the messages themselves.

Figure 5. A message sent to a CGI, captured in the Call Box.


In AppleScript, if a handler is executing and another message arrives, the first message is interrupted and the second message takes over, initiating a second handler call. If a third message arrives, the second message is interrupted, and so on. As each handler finishes, the next most recent message continues from where it was interrupted. You can simulate this behavior either by manually making calls in the Call Box, or by sending Apple events from another application.

Extra Bonuses


AppleScript scripts have special global variables (called properties), which can be initialized at compile time, and whose values persist between executions in applets (AppleScript applications). When an applet quits, any values for the properties that were changed while the applet was running are saved to disk. The next time the applet is launched, the properties are given the last saved values. When you're debugging, you have a choice between allowing property values to persist between executions or debugging sessions (to help simulate the script running in an applet), or automatically clearing them out each time you start.

Error handling

AppleScript has a mechanism for catching and handling runtime errors, known as a try block. Any errors encountered in the try part of the block will drop the script into the error handling part of the block. This allows you to gracefully handle errors encountered in your script.

However, AppleScript doesn't differentiate between a genuine runtime error and a bug in your script -- when you're debugging a script, you don't want bugs to be caught and handled by the error handler.

The example below shows what is a real runtime error, depending on the value of y. Normally you would want this error to be caught by the error handler:

   set x to 5 / y
on error
   set x to 0

On the other hand, this version is a bug in your script which you don't want to go into the error handler:

   set x to y / 0
on error
   set x to 0

You can turn off the error catching mechanism, step through the script, and if you encounter a bug, the script will stop as though the error handlers are not present. If you discover that the bug is really a genuine runtime error, then you can turn the error handling mechanism back on, and step into the error handler.


In recursion, a routine is called from inside itself. Recursion is used for simple factorial computations or to traverse through nested folders on a disk (which requires starting through a sub-folder while you're in the middle of going through a folder). It's interesting to watch the recursion build up and unwind.

Here's a standard factorial routine that calls itself, modified slightly so you can watch and play with the value of x:

on factorial(x)
   if x > 0 then
      factorial(x - 1)
      return x * result
      return 1
   end if
end factorial


You can watch the results returned as each level of recursion unwinds. In the Observe window, you can see what level of recursion you're in, and modify the value of x for the current level of recursion.

It's Addictive

These dynamic debugging techniques are instructive and fun. It'll take you less time to find your errors and perfect your scripts. And you'll find and fix bugs that you wouldn't have known you had, so you'll end up with higher quality scripts. Whether you're making scripts for your own desktop use, or providing scripts for those around you, you'll have a much higher degree of satisfaction and you'll accomplish a lot more with AppleScript.

Cal Simone,, President of Main Event Software, and founder of the AppleScript Language Association, defines the essence of user-authorability. He is relentless in his efforts to make AppleScript use as widespread as possible.


Community Search:
MacTech Search:

Software Updates via MacUpdate

1Password 6.3.5 - Powerful password mana...
1Password is a password manager that uniquely brings you both security and convenience. It is the only program that provides anti-phishing protection and goes beyond password management by adding Web... Read more
QuickBooks R9 - Financial ma...
QuickBooks helps you manage your business easily and efficiently. Organize your finances all in one place, track money going in and out of your business, and spot areas where you can save. Built for... Read more
TextMate 2.0-beta.12.25 - Code/markup ed...
TextMate is a versatile plain text editor with a unique and innovative feature set which caused it to win an Apple Design Award for Best Mac OS X Developer Tool in August 2006. A rapidly growing... Read more
TunnelBear 3.0.4 - Subscription-based pr...
TunnelBear is a subscription-based virtual private network (VPN) service and companion app, enabling you to browse the internet privately and securely. Features Browse privately - Secure your data... Read more
PDFpen 8.2.1 - $74.95
PDFpen allows users to easily edit PDF's. Add text, images and signatures. Fill out PDF forms. Merge or split PDF documents. Reorder and delete pages. Even correct text and edit graphics! Features... Read more
PDFpenPro 8.2.1 - $124.95
PDFpenPro allows users to edit PDF's easily. Add text, images and signatures. Fill out PDF forms. Merge or split PDF documents. Reorder and delete pages. Create fillable forms and tables of content... Read more
Cosmo Run 2.5.1 - Arcade game with ever-...
Cosmo Run is an arcade game with ever-changing aspect of the play-world. Survive long enough and you will meet special alternative paths - both hardcore and rewarding. Are you worthy to command the... Read more
Box Sync 4.0.7724 - 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
VueScan 9.5.59 - Scanner software with a...
VueScan is a scanning program that works with most high-quality flatbed and film scanners to produce scans that have excellent color fidelity and color balance. VueScan is easy to use, and has... Read more
Skype - Voice-over-internet p...
Skype allows you to talk to friends, family and co-workers across the Internet without the inconvenience of long distance telephone charges. Using peer-to-peer data transmission technology, Skype... Read more

Latest Forum Discussions

See All

5 apps for the budding mixologist
Creating your own cocktails is something of an art form, requiring a knack for unique tastes and devising interesting combinations. It's easy to get started right in your own kitchen, though, even if you're a complete beginner. Try using one of... | Read more »
5 mobile strategy games to try when you...
Strategy enthusiasts everywhere are celebrating the release of Civilization VI this week, and so far everyone seems pretty satisfied with the first full release in the series since 2010. The series has always been about ultra-addictive gameplay... | Read more »
Popclaire talk to us about why The Virus...
Humanity has succumbed to a virus that’s spread throughout the world. Now the dead have risen with a hunger for human flesh, and all that remain are a few survivors. One of those survivors has just called you for help. That’s the plot in POPCLAIRE’... | Read more »
Oceans & Empires preview build sets...
Hugely ambitious sea battler Oceans & Empires is available to play in preview form now on Google Play - but download it quickly, as it’s setting sail away in just a few days. [Read more] | Read more »
Rusty Lake: Roots (Games)
Rusty Lake: Roots 1.1.4 Device: iOS Universal Category: Games Price: $2.99, Version: 1.1.4 (iTunes) Description: James Vanderboom's life drastically changes when he plants a special seed in the garden of the house he has inherited.... | Read more »
Flippy Bottle Extreme! and 3 other physi...
Flippy Bottle Extreme! takes on the bottle flipping craze with a bunch of increasingly tricky physics platforming puzzles. It's difficult and highly frustrating, but also addictive. When you begin to master the game, the sense of achievement is... | Read more »
Plants vs. Zombies Heroes guide: How to...
Plants vs. Zombies Heroes surprised us all, presenting a deep deck building experience. It's a great CCG that stands up well to the competition. There are a lot of CCGs vying for players' attention at the moment, but PvZ Heroes is definitely one... | Read more »
Arcane Online takes Online RPG’s to anot...
If you think that you need a desktop to enjoy high quality MMO gaming then Arcane Online hopes to prove you emphatically wrong. An epic fantasy Online RPG set in the land of Eldine, Arcane Online offers an abundance of features and content that... | Read more »
It’s time to step up and start your spoo...
So you’ve just downloaded Seekers Notes: Hidden Mystery, and you obviously want to hit the ground running. Well you’re in luck because you just so happen to be reading our very useful guide to playing. First released in July last year, the game has... | Read more »
Diggy’s Adventure launches on Android an...
Diggy’s Adventure is the exciting new mobile app brought to you by Pixel Federation. Transporting you all the way to Egypt, you’ll join Diggy and his mates in their quest to find Diggy’s dear old dad – completing challenges put to you by the gods (... | Read more »

Price Scanner via

Check Apple prices on any device with the iTr...
MacPrices is proud to offer readers a free iOS app (iPhones, iPads, & iPod touch) and Android app (Google Play and Amazon App Store) called iTracx, which allows you to glance at today’s lowest... Read more
Apple, Samsung, Lead J.D. Power Smartphone Sa...
Customer satisfaction is much higher among smartphone owners currently subscribing to full-service wireless carriers, compared with those purchasing service through a non-contract carrier, according... Read more
Select 9-inch Apple WiFi iPad Pros on sale fo...
B&H Photo has select 9.7″ Apple WiFi iPad Pros on sale for up to $50 off MSRP, each including free shipping. B&H charges sales tax in NY only: - 9″ Space Gray 256GB WiFi iPad Pro: $799 $0 off... Read more
Apple refurbished 13-inch Retina MacBook Pros...
Apple has Certified Refurbished 13″ Retina MacBook Pros available for up to $270 off the cost of new models. An Apple one-year warranty is included with each model, and shipping is free: - 13″ 2.7GHz... Read more
Apple refurbished 15-inch Retina MacBook Pros...
Apple has Certified Refurbished 2015 15″ Retina MacBook Pros available for up to $380 off the cost of new models. An Apple one-year warranty is included with each model, and shipping is free: - 15″ 2... Read more
Apple refurbished 11-inch MacBook Airs availa...
Apple has Certified Refurbished 11″ MacBook Airs (the latest models), available for up to $170 off the cost of new models. An Apple one-year warranty is included with each MacBook, and shipping is... Read more
Apple refurbished Apple TVs available for up...
Apple has Certified Refurbished 32GB and 64GB Apple TVs available for up to $30 off the cost of new models. Apple’s standard one-year warranty is included with each model, and shipping is free: -... Read more
15-inch Retina MacBook Pros on sale for $200...
B&H Photo has 15″ Retina Apple MacBook Pros on sale for $200 off MSRP. Shipping is free, and B&H charges NY tax only: - 15″ 2.2GHz Retina MacBook Pro: $1799 $200 off MSRP - 15″ 2.5GHz Retina... Read more
Apple refurbished 2016 13-inch MacBook Airs a...
Apple has Certified Refurbished 2016 13″ MacBook Airs available starting at $849. An Apple one-year warranty is included with each MacBook, and shipping is free: - 2016 13″ 1.6GHz/8GB/128GB MacBook... Read more
Apple refurbished iMacs available for up to $...
Apple has Certified Refurbished 2015 21″ & 27″ iMacs available for up to $350 off MSRP. Apple’s one-year warranty is standard, and shipping is free. The following models are available: - 21″ 3.... Read more

Jobs Board

*Apple* Retail - Multiple Positions (Multi-L...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
*Apple* Retail - Multiple Positions- New Yor...
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
*Apple* Retail - Multiple Positions- Yonkers...
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
Senior Manager, Security Engineering - *Appl...
Changing the world is all in a day's work at Apple . If you love innovation, here's your chance to make a career of it. You'll work hard. But the job comes with more Read more
Manager, Threat Intelligence - *Apple* Info...
Changing the world is all in a day's work at Apple . If you love innovation, here's your chance to make a career of it. You'll work hard. But the job comes with more Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.