AppleScript Help

- Introduction
- Installation
  - Automatic installation
  - Manual installation
  - After installing
- Description of the AppleScript menu
- File name conventions
- Working directory
- Memory management
- The Mark pop-up menu
- The Functions pop-up menu
- Option clicking the title bar
- Completions
- Key bindings
- AppleScript Mode preferences
- Version History
- Known problems
- License and Disclaimer

> This is a help file for the AppleScript mode in Alpha. This file should be located in the Help subfolder of Alpha's folder to show up automatically in the Help menu when Alpha is loaded.

## Introduction

AppleScript mode is a mode for the text editor Alpha: it is designed to facilitate editing, compiling, decompiling, executing and processing of scripts written in the AppleScript language, with all the powerful editing facilities provided by Alpha.

Once you are in AppleScript mode, there is a new menu (designated by the AppleScript editor icon) in the menu bar giving access to all the features described below.

AppleScript mode requires the Tclapplescript extension to be present on your system. It is, for instance, distributed with the Batteries Included Tcl/Tk distribution. Note that the AppleScript Editor application does not have to be launched or even present on your computer for this mode to work. AppleScript mode relies entirely on the Tclapplescript extension which interacts directly with the MacOS Open Scripting Architecture.

The AppleScript mode is identified, in the modes pop-up menu at the right of the status bar, by the four-letters code Scrp.

## Installation

If you have Apple Script Mode as a part of the distribution of Alpha, you do not have anything to do: it is installed with the whole system. If you received it as a separate package, follow the instructions below which describe two methods of installation.

### Automatic installation

Open the OPEN TO INSTALL file. Opening this file indicates to Alpha that a new package has to be installed: the procedure is automatic. Alpha knows where to store the different elements of your AppleScript Mode package.

### Manual installation

- put the Applescript Mode folder in the Modes subfolder of the Tcl folder which is located at the same level as your Alpha application

- put the AppleScript Help file in the Help folder located at the same level as your Alpha application. Next time you launch Alpha, you will have an AppleScript Help item in the Help menu to edit this file.

- put the files AppleScript-Example and AppleScript-Example.tcl in the Examples folder located at the same level as your Alpha application.

- if there is an AppleScripts folder (containing sample scripts), it should be located at the same level as Alpha itself.

- launch Alpha. You have to rebuild the package indices and the Tcl ones. Rebuild Package Indices is in the Config--Packages menu, and Rebuild Tcl Indices is in the Tcl menu.
- quit Alpha and relaunch it: that's all there is to it.

### After installing

Read the AppleScript Tutorial which can be opened directly from the AppleScript menu. For reference info, read the AppleScript Help file accessed from the Help menu. Have a look at the mode specific preferences: create or open any AppleScript source file and choose Preferences... in the Mode Prefs submenu of the Config menu (or simply hit F12 when in AppleScript mode).

## Description of the AppleScript menu

Here is the description of the AppleScript menu items:

New Script

Open a new editing window in AppleScript mode. This does not create a file on disk until you save the window.

Decompile A Script...

Brings up a dialog to select a compiled script: the script is decompiled and edited in a new window in AppleScript mode.

Run A Script...

Brings up a dialog to select a compiled script and run it. The result of the excution is output in the AppleScript Results window.

Apple Script Flags

This submenu contains various flags concerning scripts compilation and some preferences. See the AppleScript Mode Tutorial for various examples. These flags are synchronized with the corresponding mode preferences (see AppleScript mode preferences below).

Augment Context

This flag supposes that you are compiling the current window as a context: if it has already been compiled and if this flag is set, then the new instructions will be added to the already existing context. Otherwise they replace what is already in the context.

Include Description

Add an environment at the beginning of the source script to specify a descriptive comment which will be stored in the compiled script.

Inherit From Parent

When compiling a script as a context, this flag lets you specify another context script from which it will inherit: all the properties, handlers, variables etc. (bindings in the AppleScript parlance) stored in the parent will be available to the new context.

Launch To Get Terminology

This flag affects the Open a dictionary command. If it is set, the command will first look for dynamic terminology in the application whose dictionary you open: if there is dynamic terminology, the application has to be launched in order to provide this terminology. This flag lets you specify if you accept that the application be launched. Otherwise, AppleScript Mode will look for static terminology which does not require the application to be launched: if dynamic terminology is available, AppleScript mode will print a warning to let you know anyway. Not all applications have dynamic terminology: it concerns mainly applications supporting plugins and extensions (Alpha8 has dynamic terminology, Alpha7 does not).

Make Context

Compile the current window as a context script. This script can be used later to compile another script in this context. Note that when you compile a script with this flag set, it is immediately executed in order to make its data available: for an ordinary script, executing some action rather than defining data, this is generally not what you want.

Run In Context

This flag lets you run a script in a specific context. The context can be selected by opening, with the Control key held down, the Scripts submenu in the AppleScript menu.

Compile

Compile the contents of the current selection (or the entire contents of the topmost window if no region is selected). In AppleScript Mode, this means compiling as binary code and storing the result on disk. If the window does not correspond yet to a file on disk (for instance if it is a new script created using the New Script item), the compiled script will be written in the AppleScripts folder in Alpha's folder. Otherwise the compiled script will be in the same folder as the source file. If there is no selection, the entire contents of the current window are compiled; otherwise only the selection is compiled.

Execute

This is equivalent to compiling and running the script edited in the topmost window. In this case the script is just compiled internally: it is not written on disk and the compiled script is freed from memory as soon as its execution completes. The result of the execution is sent to the AppleScript Results window. If there is no selection, the entire contents of the current window are executed; otherwise only the selection is executed.

Run

Run the script edited in the current window. It must have been previously compiled. If it is not compiled yet or if it has been changed since the last compilation, Alpha will let you know and offer to compile or recompile the script before running it. The result is sent to the AppleScript Results window.

Check Syntax

Check the syntax of the script edited in the current window. Any error will be reported in the AppleScript Results window.

Apple Script Utils

This submenu contains subsidiary features.

Add Description

Insert a special comment at the beginning of the edited script to give a description the script. This comment is stored in the compiled script. In AppleScript Editor, it is shown in the Description edit field at the top of the editing window. In Alpha, we display it in a comment with the following structure:

     (* Description
     	    Text of the comment here
     *)

This comment must be located at the beginning of the script prior to any instruction. If the Include Description preference is set (see Preferences below), Alpha will display the comment if one is found when editing a compiled script or it will write the comment into the compiled script at compilation time. If the preference is not set, the description comment will not be taken into account.

If the Option key is pressed, the item Add Description is changed to Delete Description. This will delete the descriptive comment from the edited script if there is one. You'll have to recompile to have it deleted from the compiled script too.

Line Continuation

Insert the line continuation symbol (¬) which is not always easy to find on the keyboard, especially on international keyboards.

Open A Dictionary...

Get the scripting terminology of a scriptable application. This procedure takes care of various possible situations which are checked in the following order:

- does the application accept the Get AETE Apple Event? If yes, it means that it has an 'scsz' resource and is able to provide its scripting terminology at runtime. This is useful for applications which accept external plug-ins which are also scriptable.
- does the application have resources of type 'aete'?

The terminology information (aka scripting dictionary) is output, in human readable form, in as many files as there are 'aete' resources reported.

Colour and Mark Dictionary

Just as it says. Events, classes, keywords etc. are colored. The events and classes are marked: marks are accessible, in alphabetical order, in the Marks popup menu on the right border of the window.

Dump Mem Info

Output information about the scripts and contexts which have been compiled during the current session and stored in memory.

Clear Memory

Frees the memory occupied by compiled scripts and contexts. Once the memory is cleared, the scripts are not available anymore for immediate execution and have to be recompiled. This concerns only the scripts you want to run manually with the Run command. Scripts you run from the Scripts submenu or with the Run A Script... item are handled directly by AppleScript mode.

AppleScript Bindings

Display the key bindings available in AppleScript Mode.

AppleScript Tutorial

Open the AppleScript Mode tutorial in a shell window.

Scripts Folder

This submenu contains the names of all the compiled scripts stored in the current working folder, i-e the folder designated by the AppleScripts Folder preference (by default it is a folder called AppleScripts and located at the same level as the Alpha application itself). The submenu behaves differently depending on the modifier key which is pressed as you open it:

- if no modifier key is pressed, the first item is "Rebuild scripts list" which lets you update the menu when the contents of the AppleScripts folder have been modified. If you click on the name of a script, it will be executed.
- if the option-key is pressed, all the items are prefixed with the word •edit•: this allows you to decompile and edit the script instead of executing it. In this case the first item in the submenu becomes Reveal scripts folder which switches to the Finder and opens the corresponding folder.
- if the control-key is pressed, the menu lets you specify a script to be used as a context script. The selected script is marked with a bullet. It will be used if the Run in context flag is set in the Apple Script Flags submenu. In this case the first item in the submenu becomes Select a context and brings an info dialog window.
- if the shift-key is pressed, the menu lets you specify a context script to be used as a parent for the script you want to compile. The selected script is marked with a diamond. It will be used only if the flags Make context and Inherit from parent are both set in the Apple Script Flags submenu. In this case the first item in the submenu becomes Select a parent context and brings an info dialog window.

Mnemonic tip: control for context, shift for parent.

## File name conventions

By default, when compiling the source of a script, the name of the compiled script is set like this:

- if it has no extension, an .scpt extension is added;
- if it has an extension different from .scpt, this extension is replaced by .scpt;
- if it already has an .scpt extension, then you are asked to give a name yourself for the compiled script.

This name is remembered by Alpha (until the moment when you quit Alpha), so that you are not asked over again each time you recompile your script.

When decompiling a script to edit its source code, the editing window is named after the name of the script with an additional .scr extension. This can be changed if necessary when you decide to save the source script.

Concerning terminology dictionaries, the output files are named after the name of the application followed by a .dict extension and a sequential numbering in case there are several Apple Event Terminology resources. If the resource has a name (and not only an ID number), this name is used.

In any case, the file names will be truncated and shortened so that they do not excess a 32 chars limit. For instance a script editing window called

     GetUSBPrinterSharingVersionNumber.scpt

will be compiled under the name:

     GetUSBPrinterSharingVersi...umber

## Working directory

The Scripts submenu shows the contents of the working directory: this is the folder where your scripts will be stored when you compile them. This folder can be set and modified (see preferences below). The default name and location of the working folder is AppleScripts in the same folder as Alpha itself.

If this folder can't be found (if it has been deleted or renamed for instance), AppleScript mode will create a new one automatically when necessary.

## Memory management

When you recompile a script, Alpha warns you if the script has already been compiled previously and no changes have been made since the last compilation. On the other hand, when you try to run the current window, Alpha warns you if the script has not yet been compiled or if it has been modified since the last compilation.

Each time a script is loaded or compiled, it is kept in memory and a token is returned to identify it for later reference. AppleScript Mode keeps track of these tokens so that you don't have to bother about them. Thanks to this internal mechanism, you don't have to recompile a script each time you want to run it. The same is true for scripts compiled as contexts.

You can use the Dump Mem Info to know which compiled scripts are currently stored in memory: it outputs a list indicating the token and the corresponding script file on disk. If you want to free the memory occupied by these compiled scripts, use the Clear memory command in the Apple Script Utils submenu: this will destroy all the script tokens (except for the global context which is never destroyed).

To know which scripts or contexts are currently in memory, open a Tcl shell and type one of the following commands:

     AppleScript info scripts
     AppleScript info contexts

## The Mark pop-up menu

The marking procedure marks all the function definitions (aka handlers in AppleScripts parlance), i-e all the statements of the form:

     on functname(params)
         -- instructions
     end functname

The error statements (on error etc.) are not marked though by the procedure since they do not correspond to function definitions.

## The Functions pop-up menu

There is no mode specific behaviour for the functions pop-up menu (top right of your editing window, with a pair of braces icon).

## Option clicking the title bar

If you Option-Click on a the title bar, you get a list of all the compiled script files present in the current working folder. Clicking on any of them will decompile it and edit it in a new window.

## Completions

There is a set of completion procedures in AppleScript mode. To enable them, you must activate the elecCompletion package (in "Config--" Preferences--" Features") and choose your completion key (default is F1).

There is a set of electric abbreviations. Just type one of the following abbreviations and hit the completion key to have them expanded to a complete structure:

- tell
- on
- if
- try
- repeat

For instance tell will result in:

     tell application "|"
     |
     end tell

You can also type the first letters of an AppleScript keyword and hit the completion key. If it is recognized as a keyword, it will be completed. If there are different possible completions, they will be listed in the status bar: hit the completion key again and you will have a list of all the possibilities from which you can select the one you want.

## Key bindings

A few mode specific key bindings are defined in AppleScript mode: all of them use the combination 'ctrl-a' followed by a letter. For instance, to decompile and edit a script, hit 'ctrl-a' and then the letter 'o'. The following bindings are available:

'ctrl-a b' | to display the info about bindings
'ctrl-a c' | to compile the current window or selection
'ctrl-a d' | to get a scripting dictionary
'ctrl-a e' | to execute (compile and run) the current window
'ctrl-a f' | to free compiled scripts stored in memory
'ctrl-a l' | to insert the line continuation symbol (¬)
'ctrl-a m' | to dump memory info
'ctrl-a n' | to create a new script
'ctrl-a o' | to decompile and open a script
'ctrl-a r' | to select and run a script
'ctrl-a s' | to check the syntax of the current window

## AppleScript Mode preferences

The Preferences... item in the Mode Prefs submenu of the Config menu allows you to edit specific preferences defined in the AppleScript mode.

The AppleScripts Folder preference lets you set your working directory where your compiled scripts will be stored. You can access any script in this folder from the Scripts submenu as described above. The working folder can be changed at will. If it has been deleted, moved or renamed, Alpha will recreate it as necessary.

Set the Include Description preference if you want AppleScript mode to take care of the description comment which is stored in compiled scripts. See above the Add Comment menu item for a description of the syntax of this comment.

The other preferences are

- Augment Context
- Inherit From Parent
- Launch To Get Terminology
- Make Context
- Run In Context

They have the same meaning as the corresponding flags in the Apple Script Flags submenu: preferences and submenu flags are synchronized. Settings made in the preferences will be remembered the next time you launch Alpha and will be reflected by the submenu.

## Version History

- 1.0.1 - 01/03/31 - Previous versions of AppleScript mode by John Sarapata sarapata_john@jpmorgan.com
- 2.0 - 02/03/12 - Complete rewriting of the AppleScript mode to take advantage of the Tclapplescript shared library and Alpha8.
- 2.1 - 02/06/07 - Added a preference to set the working directory.
- 2.2 - 02/09/25 - Modified ASTerminology to rely on TclAE library for parsing. Enhanced the mode to handle contexts and various compilation flags. Choice of format for tutorial. Doc updated.

## Known problems

- There is currently no possibility of recording.

Please e-mail any problem or bug you encounter: bdesgraupes@easyconnect.fr

Goto the Alpha utilities page:

http://webperso.easyconnect.fr/bdesgraupes/alpha.html

## License and Disclaimer

(c) Copyright: Bernard Desgraupes, 2002-2004 All rights reserved.

This software is free software and distributed under the terms of the new BSD license: Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
- Neither the name of Bernard Desgraupes nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

This software is provided by the copyright holders and contributors as is and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. In no event shall the contributors be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this software, even if advised of the possibility of such damage.