Related Info: Apple Event Mgr

AppleScript 1.0 Overview

What is AppleScript and how does it work?

By Mark Minshull, Apple Computer, Inc.

About the author

Mark Minshull is the Engineering Manager of the Application Scripting Group at Apple Computer, Inc. When he's not managing the group he secretly writes AppleScript scripts. His E-mail addresses are minshull.m@applelink.apple.com and MINSHULL.M on AppleLink.

Although the AppleScript™ 1.0 Runtime and AppleScript Developer's Toolkit have been shipping since the end of April, there's still seems to be some uncertainty about just what AppleScript is. In this article I'll attempt to demystify AppleScript by covering the following topics:

• What's the relationship of AppleScript to Apple events, other scripting systems, and the Open Scripting Architecture?

• What does the AppleScript language look like?

• If you order AppleScript, just what do you get ?

This article does not cover the ins-and-outs of using AppleScript to script other applications.

AppleScript and the Open Scripting Architecture

In May 1991, Apple announced the Open Scripting Architecture (OSA), a standard for scripting technologies. The OSA specifies that for an application to be “OSA-compliant” (i.e., scriptable) it must support Apple Events, understand Apple Event object descriptors and, where possible, adhere to standard event suites as defined in the Apple Events Registry.

About 25 major applications are now OSA-compliant (including Excel, FileMaker Pro 2.0, Canvas) and many more will be shipping soon. Future Apple technologies - such as speech recognition - will depend on scriptable applications to deliver services, as well as be scriptable themselves.

AppleScript is system extension that allows users to control OSA-compliant applications through written scripts. It extends and complements the Macintosh graphical interface to offer automation, customization, and application integration capabilities-offering users a high degree of control over the way in which they work with their computers. It also extends the Open Scripting Architecture, as discussed below.

New Kinds of Script-aware Applications

Prior to the release of AppleScript commercial developers could make their applications scriptable as described in the previous section. With the shipment of AppleScript and the OSA Application Programmers Interface (API), two new types of script-aware applications are possible:

• Attachable applications are applications that are capable of triggering scripts. For example, an attachable application might hand off a script to AppleScript for execution in response to a specified condition, such as a change in data value, or in response to a user action, such as entering text in a particular field. In this way, applications that are attachable can act as front ends to other applications.

• Recordable applications are applications that are capable of sending Apple events to themselves to report user actions to the Apple Event Manager. Currently AppleScript can decompile these recorded Apple events into the form of a script. Thus a recordable application allows users to create and compile scripts simply by turning on a “record” mode button within the AppleScript Script Editor. (Recordable applications are implemented strictly through the Apple events 1.01 interface and are outside the scope of this article).

Introducing the OSA API

The OSA API provides an interface to developers to implement attachable applications. For example, the AppleScript Script Editor calls the OSA API to load, compile, run, and store scripts.

So what does this mean to you, the developer? Well... your application can now easily load, run, and store scripts that reside in memory, documents, or as external script files. Applications can direct these scripts at other scriptable applications - as does the AppleScript Script Editor - or at themselves to provide a powerful macro capability (provided your application is scriptable, of course!). An even more ambitious use of the OSA API is to allow customization of your application's user interface or behavior through the attachment of scripts to application objects.

I did say it was easy to load and run scripts...below is the complete code needed to connect to a scripting component, load a script, and execute it:

/* 1 */

instance = OpenDefaultComponent('osas','gnrc');
desc.descriptorType = 'scpt';
desc.dataHandle = Get1Resource('scpt', 128);
OSALoad(instance,&desc,0,&scriptID);
ReleaseResource(desc.dataHandle);
OSAExecute(instance,scriptID,kOSANullScript,0,&result);
OSADispose(scriptID);

What About Other Scripting Systems?

The “back end” of the OSA API is defined such that any scripting system can plug in under it. Therefore, your application doesn't have to worry about which scripting systems is installed; OSA calls are dispatched to the appropriate OSA scripting component based on a script's ID or signature.

So, for example, when the next version of Frontier ships you'll be able to attach and execute Frontier scripts through the identical API that you can now use with AppleScript. (A QuicKeys OSA scripting component is also under development).

There's a lot more provided by the OSA API than I can cover here; for example, it defines a software architecture for building “tinkerable” applications via a message-passing inheritance model. These and other details are described in the new Inside Mac IAC Volume (an electronic copy is included with the AppleScript Developer's Toolkit).

The AppleScript Scripting Component

Let's now take a look at the AppleScript language... Although the main design focus of AppleScript is to control other applications via scripted Apple events, it is itself a fully-featured programming language.

I'll first discuss AppleScript's control structures and subroutine definition syntax, and give examples of working with strings and lists. I'll also cover methods for writing modular scripts using script libraries, and touch on some advanced language features. Throughout I'll arbitrarily dive into the details on some topics, but this is by no means an exhaustive survey of the language.

AppleScript Control Structures and Subroutines

AppleScript has all of the standard control structures you know and love. Here's an assortment of repeat loops:

--       2

-- repeating "forever" or until a forced exit 
repeat
 if getX() > 10 then exit repeat
end repeat

-- repeating while a condition is true.
repeat while myString = "•"
 set myString to some word of anotherString
end repeat

-- repeating while a condition is false.  
set backedUp to false
repeat until backedUp
 set backedUp to doMyBackup()
end repeat

-- repeating with a looping variable
repeat with j from 10 to 1 by -2
 set negSum to negSum + j
end repeat

-- repeating in a list
repeat with i in {1,12,4}
 set x to item i of aList
end repeat

It supports simple and compound if statements:

--       3

-- Simple if statement
if wishes = horses then beggarsWouldRide()

-- Compound if statement
if backupdate < (current date) then
 performBackup(fileName)
else if (fileType of fileName) is folder then
 updateFolderLog(fileName)
else
 updateFileLog(fileName)
end if

Subroutines can be defined with either positional or labeled parameters and may contain local or global variables. By default variables have local scope unless declared global:

--       4

-- positional parameters
on getEnd(stringIn, searchString)
 global aString
 local x, y, z
 -- some statements
 return x + y + z
end getEnd
-- calling syntax:
getEnd("a string", "str")

-- labeled parameters
on insert into stringIn at searchString given ¬    insertString:insertText
 -- some statements
end insert
set myString to "this is a line of text"
-- calling syntax:
insert into myString at "line" given insertString:"*BIG* "

Error trapping, recovery, and error resignaling are supported.

--       5

try
 word 5 of "one two three"   -- word 5 doesn't exist
on error errtext number errNum
 display dialog "A horrible error has occurred: " & errtext ¬
 & "  Error number: " & errNum & ".Press \"OK\" to continue."
end try

There are also assorted block structures for modifying event time-outs and event sending modes

Working with Strings

String (text) manipulation is an important part of any language, and is especially so for AppleScript since it is often the data type that is passed and processed between applications. Strings are objects in AppleScript. String objects may be created by assigning a string literal to a script variable or script property, or by the result of a command. All string objects have two properties - class and length - and contain 0 or more character, word, or paragraph elements:

--       6

set myString to "this is a string literal"

class of myString
-- ==> string
length of myString
count of myString
number of myString
-- ==> all evaluate to 24

Strings objects may be concatenated using the "&" operator:

--       7

set myString to myString & ", OK?"
-- ==> "this is a string literal, OK?"

Escape Characters in String Literals

Special characters can be entered into string literals using the “\” character:

--       8

-- "\r" return character
-- "\t" tab character
-- "\\" backslash character
-- "\"" quote character
--

"Well, \"hello\" \\there\\"
-- ==> upon output, "Well, "hello" \there\"

Also, the special key words “return”, “tab”, and “space” may be used instead of escapes.

Object Reference Forms

One powerful feature of AppleScript is that a consistent set of reference forms are used to access all objects. For example, the reference forms described below for strings also apply when accessing lists, records, or application-defined objects.

Offset Reference Form

The offset reference form specifies the offset from the beginning or end of a container. A negative offset indexes from the end of the container. Compound offset reference forms are supported. International-aware text utilities are used to determine the definitions of characters, words, and paragraphs.

--       9

set testString to "This is a string that" & return & ¬
"spans exactly " & return & "three lines."

word 4 of testString
-- ==> "string"
word (-1) of testString
-- ==> "lines"
character 1 of word 2 of paragraph 3 of testString
-- ==> "l"

Numeric synonyms

“first, second, third...ninth, tenth” may be used as synonyms for offsets from 1 to 10. “st”, “nd”, “rd”, or “th” may be appended to any offset. Also, “front” is equivalent to “first”, and “last” and “back” are equivalent to an offset of -1.

--       10

first character of second word of third paragraph of testString
-- ==> "l"
23rd character of testString
-- ==> "s"
testString's last word
-- ==> "lines"

Range Reference Form

Substrings from within a string can be obtained by using the range reference form. The result of a range references is a list of strings.

--       11

paragraphs 1 thru 2 of testString
-- ==> {"This is a string that", "spans exactly "}

words 1 thru paragraph 2 of testString
-- ==>{"This", "is", "a", "string", "that", "spans", "exactly"}

characters 1 thru 5 of paragraph 2 of testString
-- ==> {"s", "p", "a", "n", "s"}

Continuous Text Ranges

You can obtain a continuous range of text from a string by using the “text” range form:

--       12

text 6 thru 16 of testString
text from character 6 to character 16 of testString
-- ==> both evaluate to "is a string"

text from word 3 to paragraph 2 of testString
-- ==> "a string that \rspans exactly "

testString's text from 2nd paragraph to last paragraph
-- ==> "spans exactly \rthree lines."

Boolean Operations on Strings

AppleScript supports <, ¾, =, , and > operators (or their synonyms) on strings. By default, character case is not considered in the comparison. (This can be modified using the “Considering” command, described below.) The ASCII collating sequence is used for < and > comparisons. If two strings have identical characters but one string is shorter than the other, than the shorter string evaluates to less than the larger string.

--       13

"FRED" = "fred"
"zzyzx" is greater than "aardvark"
"aa" < "aaaaa"
-- ==> all evaluate to true

Overriding Default Comparison Rules

The “Considering” and “Ignoring” statements allow one to specify what string attributes should be used during a comparison. Allowable string attributes are “case”, “white space”, “diacritical”, “hyphens”, and “punctuation”.

--       14

considering case
 "FRED" = "fred"
end considering
-- ==> false

ignoring punctuation and white space
 "a,    b.,,  ;!      c" = "ABC"
end ignoring
-- ==> true

considering case but ignoring punctuation and white space
 "a,    b.,,  ;!      c" = "ABC"
end considering
-- ==> false

Containment

You can determine if a string contains a substring using the “contains” operator:

--       15

set anotherString to "this is a line of text"

anotherString contains "line"
"is" is contained by anotherString
-- ==> both evaluate to true

considering case
 "abcdefg" contains "ABC"
end considering
-- ==> false

Beginning and Ending Tests

You can test the beginning or endings of two strings:

--       16

anotherString begins with "this is"
anotherString starts with "this is"
-- ==> both evaluate to true

anotherString ends with "t"
-- ==> true
anotherString does not end with "this"
-- ==> true

Working with Lists and Records

Remember everything we just covered about string reference forms and Boolean operations? It pretty much applies to lists and records if you take into account they contain list elements rather than characters, words, and paragraphs:

--       17

set myList to {1, "two", 3.0}

myList contains "two"
-- => true

second item of myList
-- => "two"

considering case
 myList is equal to {1, "Two", 3.0}
end considering
-- => false

myList & {4, 5, {6,7,8}}
-- => {1, "two", 3.0, 4, 5, {6,7,8}}

Again, one of the powerful features of AppleScript is that it allows the application of a uniform set of accessor forms and operations on a wide range of objects.

Records

The record data type in AppleScript is a special type of list whose items can be accessed according to user specified labels. This powerful data type allows a single command to return an (almost) arbitrary amount of complex data, rather than requiring a succession of special-purpose verb queries.

For example, the “info for” AppleScript command returns a record containing information about a file or folder. In the example below this record is placed in the variable “fileInfo” where it's elements can later be accessed by name:

--       18

set fileInfo to info for file "mac IIci:desktop folder:ResEdit"
-- =>
{creation date:date "Thursday, December 6, 1990 1:00:00 PM", modification 
date:date "Thursday, December 6, 1990 1:00:00 PM", locked:false, folder:false, 
file creator:"RSED", file type:"APPL", size:636448, short version:"2.1", 
long version:"2.1, ©Apple Computer, Inc. 1984-1990"}

file creator of fileInfo
-- => "RSED"
fileInfo's modification date
-- => "Thursday, December 6, 1990 1:00:00 PM"

Script Objects and Script Subroutine Libraries

So you want to write an AppleScript script, but you're wondering if it all has to be contained in one monolithic file. Absolutely not! Scripts are themselves a data type in AppleScript, and they can be loaded, executed, and saved to disk under script control. (They can also be passed as arguments to subroutines, and executed locally or remotely across the network!)

To understand how to write a modular script, we first need to learn a bit about script objects. A script object contains executable AppleScript statements. A variable or property which contains a script object is of class “script”. One way script objects are created is by using the “script” object definition syntax. In the example below a script object is created and placed into the variable “fred.”

--       19

script fred
 property firstName : "Fred"
 property lastName : "Foobar"
 
 on fullName()
 return "Mr. " & firstName & " " & lastName
 end fullName
 
 set response to "Well, my full name is " & fullName()
 return response
end script

class of fred
-- ==> script    

Accessing the Methods Within a Script Object

All of the methods (or subroutines) of “fred” are accessible by “Telling” the script object “fred” to execute the function. (This is identical to the scopeing method used when referring to applications). Consider the following example:

--       20

tell fred
 fullName()
end tell
-- ==> "Mr. Fred Foobar"

In addition to using a “Tell” block, the following forms (all equivalent) are allowed. You'll have to use one of these calling forms to access the script object from outside the scope of a “Tell fred” block.

--       21

tell fred to fullName()
fred's fullName()
fullName() of fred
-- ==>  all evaluate to "Mr. Fred Foobar"

The data (properties) stored within a script object are also accessible. Here's how you might check fred's properties:

--       22
fred's firstName
-- ==> "Fred"

set fred's lastName to "Framitz"
lastName of fred
-- ==> "Framitz"

The “Run" Handler

Like a script contained in a file, any AppleScript statements of a script object not contained within named handlers are implicitly within the “Run” handler. These statements can be executed as follows:

--23

tell fred to run
-- ==> "Well, my full name is Mr. Fred Framitz"

Using Subroutine Libraries

In the previous example, we explicitly created a script object using the “script - end script” block structure. The “load script” command can also be used to create a script object from any saved compiled script. (The saved compiled script itself does not have to be a script object).

For example, if the following script is saved as a compiled script or script application named “times lib” and placed in the “extensions” folder:

--       24

on timesTen(x)
 return x * 10
end timesTen

on timesFive(x)
 return x * 5
end timesFive

then this load script call creates a script object from which all the subroutines in “times lib” can be accessed

--       25

set timesLib to load script file ¬
  ((path to extensions as string) & "times lib") -- build folder path 
tell timesLib
 set advancedMath to timesTen(5) + timesFive(2) 
end tell
-- ==> 60

Persistent Storage of Script Libraries

Properties in AppleScript are persistent; in other words, data contained in properties is maintained between invocations of a script. Therefore, since script objects are a data type, they can be “bundled up” with a script and accessed as an embedded library.

In the example below, “load script” will only be called on the first execution of the script since the script “times lib” will thereafter be stored in the persistent script property “embeddedScriptObject”. (Since AppleScript is polymorphic, the type of “embeddedScriptObject” will automatically change to type “script” upon assignment). The example script could then be saved as a compiled script or script application and be distributed without the original “times lib” file.

--       26

property embeddedScriptObject : "null"

if embeddedScriptObject = "null" then
 set embeddedScriptObject to load script ¬
 (choose file with prompt ¬
 "Where is the compiled script \"times lib\"?")
end if

tell embeddedScriptObject
 timesFive(5)
end tell

Note that sharing a script library among several scripts by loading it at run-time is more disk-space efficient than embedding the library in each script.

It also worth noting that since scripts can be loaded and stored on demand under script control, and can contain arbitrary data - along with methods to extract that data - the script writer can effectively accomplish a wide variety of data management tasks solely using AppleScript.

Script Object Inheritance

Another significant feature of AppleScript script objects is that they support a “delegation”-style inheritance mechanism. Delegation means that script objects can override the methods of the parent or augment them and forward them on. This capability is especially helpful to developers of applications which allow attachment of scripts to hierarchical application objects.

Consider the following example where the script “bob” is a child of “fred.”

--       27

script fred
 property aValue : 3
 on foo(x)
 return aValue + x
 end foo
 on bar(y)
 return y + 1
 end bar
end script

script bob
 property parent : fred
 on foo(x)
 if x = 3 then set x to x + 2
 continue foo(x)
 end foo
end script


tell bob 
 foo(4)
-- => 7
 bar(3)
-- => 4
 aValue
-- => 3
end tell

Above the properties and handlers of “fred” act as if they are contained in bob. Note also fred's “foo” handler has been augmented by bob's:

Other AppleScript Features

My objective thus far has been to give the reader a sense of the depth of the AppleScript language as provided by the AppleScript OSA Scripting Component. Following are highlights of some additional AppleScript scripting component capabilities.

Reentrancy and Recursion

AppleScript and AppleScript script applications are fully reentrant. Recursive subroutine calls are supported, and the AppleScript component itself supports multiple clients and threaded applications. A garbage collected memory model is used by the component.

Dialect Independence

What's the point of embedding scripts in your attachable application if you can't then localize those scripts when you sell into foreign countries? Not to worry; although the previous examples have covered the English dialect of AppleScript, the scripting system is designed to support a variety of international dialects - easily and transparently. (For example, Japanese and French will be the first international versions of AppleScript available, with other language versions to follow.)

The dialect automatically changes to match the operating system being used on any given Macintosh, ensuring compatibility across operating system versions. So a compiled script written in the English dialect and then opened on a machine running the KanjiTalk operating system will not only run as it was intended to, it will automatically be displayed in the Japanese dialect.

Language Extendibility

We knew we weren't going to think of everything first time out... so the AppleScript syntax can be easily extended via the Scripting Addition mechanism. It works somewhat like XCMDs in HyperCard, (or UCMDs in Frontier) with the exception that each Scripting Addition - like scriptable applications - contain an AppleScript “Dictionary” (or aete resource) which describes their event syntax and data formats.

Scripting Additions are made available to AppleScript by placing them in the “Scripting Additions” folder (make sense, huh?) inside the “Extensions folder.” Currently 12 Scripting Additions are preinstalled with AppleScript 1.0.

So why didn't we just build these capabilities directly into AppleScript? Well, we've generally used Scripting Additions to access services not yet made available through an Apple event interface. For example, the terminology of the “File Commands” Scripting Addition - as displayed by the Script Editor's terminology browser - is shown below in Figure 1.

Full Scripting Addition developer documentation and sample code is available on the AppleScript Developer's Toolkit. We expect to significantly grow the standard Scripting Addition set in our next release.

Figure 1. "File Commands" Terminology

Footprint

Since the AppleScript OSA component is an enabling technology for other applications we tried hard to keep it's footprint small enough so that it wouldn't crowd your application for memory or disk space. We think we've succeeded; AppleScript takes less than 300K on disk. When not in use its RAM footprint is under 1K. It to loads on demand and uses about 250K of System heap for the first client, and about 25K for each additional client.

Scripts themselves execute in the host's application heap. The memory hit varies with the script, but I've run some pretty complicated ones (like recursive folder reconciliation) in 50K.

AppleScript PrODuctS

I said I'd answer the question: “If you order AppleScript, just what do you get?” There are currently two AppleScript products; the AppleScript Runtime and the AppleScript Developer's ToolKit. Both products require System 7.0 or above.

AppleScript Runtime

You can think of the AppleScript Runtime product as a way to get your hands on future system software, now. As with the QuickTime release, AppleScript will almost certainly be rolled into the next major system software release. And like QuickTime, it's cheap. So in addition to a “Getting Started” guide and a bunch of sample scripts, here's what you get for your $20:

• AppleScript 1.0 and Apple Events 1.01

Got to have it or nothing works. A nice feature of Apple events 1.01 is that it enables recording and breaks the infamous 64K Apple event message-size barrier. (You're now limited by the receiving application's heap space.)

• Script Editor

Note it's not called the “AppleScript Editor.” Since it uses the OSA API, it can edit scripts for any OSA-compliant scripting system. We've positioned it as a minimal script editing utility, because that's what it is. (I like to think of it as the “MacPaint of AppleScript editors”; it shows off the underlying toolbox, but isn't intended to be best-of-class.)

• Language at a Glance

Very handy on-line documentation of the AppleScript language (shown in Figure 2). It also has cut-and-pasteable examples for every syntax item. (Requires the HyperCard Player).

Figure 2 Language at a Glance On-line Documentation

• Scriptable Text Editor

It's the world's most capable scriptable and recordable word processor (OK, it's currently the world's only scriptable and recordable word processor). Sort of a scriptable TeachText on steroids. It's used in many of the scripting examples in the Language Reference Manual. And try running this script against Microsoft Word:

--       28

tell window 1 of application "Scriptable Text Editor"
 copy underline to style of every word whose length > 5
end tell

Apple plans to license the AppleScript Runtime software to commercial developers for shipment with their products. The company will also offer site licenses of these software components to solutions developers for distribution with their custom solutions. For more information on licensing, developers worldwide should contact Apple Software Licensing at (408) 974-4667.

AppleScript Developer’s Toolkit

The AppleScript Developer's Toolkit is targeted at commercial developers and includes the AppleScript Runtime software described above. It also has a complete technical documentation, including a 400 page hard-copy version of the AppleScript Language Reference Manual, and electronic copies of Inside Macintosh IAC Chapters. Header files, developer tools, debugging aids, and sample code are provided on the AppleScript Developer's Toolkit CD-ROM.

To learn more about AppleScript and scriptable applications, Apple is offering courses through Developer University. In addition, there is an AppleLink discussion board specifically for AppleScript (AppleLink path: Developer Support: AppleScript Talk). Apple also watches com.sys.mac.programmer on the internet.

Ordering Information

The AppleScript Developer's Toolkit is available worldwide and can be ordered immediately through APDA, for a suggested retail price of U.S. $199. The AppleScript Runtime Kit will also be available from APDA, for a suggested retail price of U.S. $20. APDA can be reached in the United States at (800) 282-2732; in Canada at (800) 637-0029; or internationally at (716) 871-6555.