Appendix A. Standard Scripting Additions

Scripting additions are a powerful element of AppleScripting that give it almost infinite extensibility. These code libraries live inside the startup disk:System Folder:Scripting Additions folder in OS 9. Figure A-1 shows what their icons look like. Known among the scripting cognoscenti as osax (singular form, standing for Open Scripting Architecture Extension) or osaxen (a plural form), the scripting additions give you commands you can use almost anywhere in your script. Ever since Mac OS 8.5, Apple Computer has bundled a number of the most useful scripting additions into the Standard Additions file and installed this file with your operating system. In Mac OS X, the filepath for the Standard Additions file is /System/Library/ScriptingAdditions/StandardAdditions.osax.

Figure A-1. Scripting addition files in OS 9

In Mac OS X, if you want a scripting addition to be available to all users, then the administrator (the first user who installs Mac OS X, or somebody she designates as administrator) should place it in /Library/ScriptingAdditions/. This administrator should first create the Scripting Additions folder if it does not yet exist. If you want a scripting addition to only be used by one user, place it in this directory: /users/username/library/ScriptingAdditions/. You can create this directory yourself, in a particular user's Library folder, if the Scripting Additions folder does not yet exist there.

The Standard Additions include the following scripting additions:

ASCII character	mount volume
ASCII number	new file (OS 9 and prior OSes)
beep	offset
choose URL	open for access
choose application	open location
choose file	path to
choose file name (OS X only)	random number
choose folder	read
choose from list	round
clipboard info	run script
close access	say
current date	scripting components
delay	set eof
display dialog	set the clipboard to
get eof	set volume
handle CGI request	store script
info for	summarize
list disks	the clipboard
list folder	time to GMT
load script	write

Figure A-2 shows the Standard Addition's dictionary in Mac OS 9.

Figure A-2. Standard Addition's dictionary window

Any programmer, not just Apple's, can create a scripting addition. This mechanism has spawned numerous third-party osaxen (i.e., those not developed by Apple), which allow you to parse HTML or XML in scripts, use regular expressions in searches, negotiate a directory tree and do something with each encountered file (the walk folders command of Jon's Commands), and initiate many other tasks that you would otherwise have to program with your own code in AppleScript or not be able to accomplish with a script at all. Examples of some of these third-party scripting addition files are Akua Sweets, Jon's Commands, and XML Tools. The site http://osaxen.comcontains an osax database.

How do scripting additions work in Mac OS 9? When you use a command in a script, the application that ends up receiving the command depends on the command's script context. The command or Apple event could be sent to one of the following targets:

• The app identified in the "tell" block that contains the command. In other words, if AppleScript encounters:

  tell app "Photoshop 5.0" to do script "New_gif"

  then the script will send the do script command (or Apple event) to Photoshop. If the command inside the tell block could not be found in the program's dictionary, then AppleScript would look elsewhere for the command's handler, such as in the contents of the Scripting Additions folder.

• A subroutine that you have included in the script. If you have defined a subroutine called "TimesTwo" in your script and the command TimesTwo( ) appears in your script, then your script subroutine will handle the TimesTwo( ) call.

• A script object that has been loaded into the script where the command was used. See the load script description in this chapter and Chapter 9, for more information on script objects.

• A scripting addition file.

When AppleScript searches for the target of a script command it looks, among other places, inside the Scripting Additions folder for an application, an application alias, or a scripting addition file. For example, I have used the display dialog scripting addition in code samples throughout this book. This displays a modal dialog to the user and optionally allows you to request them to enter some information into a text field before they dismiss the dialog box by clicking a button (or before it closes if you specify that the window disappears after a certain number of seconds). The reason you can just randomly include display dialog in your script (with some exceptions explained later) is that AppleScript will search the Scripting Additions folder for the recipient or handler of this command and find it within the Standard Additions file in Mac OS 9. Some applications, such as ColorSync Extension, do not allow the use of display dialog within the "tell" blocks that target them (e.g., tell app "Colorsync Extension"...). You will receive a "no user interaction allowed" error message.

Example A-1 shows how two handy scripting additions, display dialog and offset, can be used in a script that involves different types of commands. Read the script comments to find out the targets of each command.

Example A-1. Using Standard Additions in a Script

(* AppleScript finds the display dialog osax inside the Standard Additions 
file, so you don't have to use any tell statements *)
display dialog "Enter your first and last names" default answer ""
set names to the text returned of the result (* names is set to a string like 
"Bruce Perry" or whatever the user enters. *)
(* 
AppleScript also finds the offset command inside Standard Additions. Offset 
searches for one string inside of another and returns the character position 
as an integer or zero if it doesn't find the string(in this case the searched 
for character is a space character). We are using it to locate the space 
character that separates the first and last names. 
*)
set sp to (offset of " " in names)
(* 
The first name is pulled out of the string by getting all the characters up to 
but not including the space character that follows the first name
*)
if sp  0 then (* if a space character is found, there must be at least two 
names in the string *)
set first_name to characters 1 thru (sp - 1) of names
   tell application "BBEdit 5.1"
      activate
      (* 
      'insert text' is a BBEdit command, so it receives the 'insert text' ¬
      *)
      insert text names
      (* 
      the display dialog command will not be sent to BBEdit, even though it¬
      *)
      display dialog (first_name as text)
   end tell
end if

As an AppleScripter, you will become very fond of some osaxen and use them all the time. You will also discover new ones and realize "hey, this makes scripting web page downloads (or whatever) much easier!" This chapter describes the commands and classes included with the Standard Additions collection found inside the startup disk:System Folder:Scripting Additions directory in OS 9. Again, the Mac OS X path for this file is /System/Library/ScriptingAdditions/StandardAdditions.osax. This group of scripting additions is installed with Mac OS 9 and Mac OS X. The classes described in this chapter are objects returned by certain commands, such as the file information object (a record type or associative array in AppleScript) returned by the info for command.