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. To be fully functional it requires Alpha 8 or greater and that the Tclapplescript.shlb shared library be present. It can work partially with Alpha7 though.


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 Alpha8 or greater to be fully functional because it needs to be able to load the Tclapplescript.shlb shared library. With Alpha7 though a minimal subset of the processing capacities is implemented and the editing capacities are complete. Note that the AppleScript Editor application does not have to be launched or even present on your computer for this mode to work. It relies on the Tclapplescript.shlb shared library which interacts directly with the MacOS Open Scripting Architecture. The Tclapplescript is part of the Alpha8's distribution.

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

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

After installing

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.

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

Compile
Compile the contents of the current selection (or the entire contents of the topmost window if no region is selected). If the window does not correspond yet to a file on disk (newly created script 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 text file.

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. The result of the execution is output in a window called "* AppleScript Results *".

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

Open Dictionary...
Get the scripting terminology of a scriptable application. This procedure takes care of several situations which are checked in the following order:
  • when the application accepts the "Get AETE" Apple Event. This 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.
  • when the application has resources of type 'aete'.

The dictionary information is output, in human readable form, in as many files as there are aete's reported.

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

Add Comment
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 Comments" preference is set (see Preferences below), AppleScript mode 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.

Scripts
This submenu contains the names of all the compiled scripts stored in the AppleScripts folder located at the same level as the Alpha application itself. If you click on any of them, it will be executed. If you open the submenu with the option-key down, all the items are prefixed with "•edit• " : this allows you to decompile and edit the script instead of executing it. The "Rebuild scripts list" item lets you update the menu when the contents of the AppleScripts folder have been modified.

File name conventions

By default, when compiling an edited script, the name of the compiled script will be the name of the edited window without its extension if it has one or with an additional ".scpt" suffix if the edited script has no extension.

When decompiling a script to edit its code, the editing window is named after the name of the script with an additional ".scpt" extension. This can easily be changed if necessary when you want to save the text script to disk.

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 instead of an ID number, this name is used.

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

 GetUSBPrinterSharingVersionNumber.scpt 
will be compiled under the name:
 GetUSBPrinterSharingVersi...umber

Scripting Contexts

There is an internal command called "Clear Contexts" which you can execute with the 'ctrl-a x' key combination. You should not have to worry about this command. Each time a script is loaded or compiled, a scripting context is created. Normally, the contexts are destroyed by AppleScript mode when they are not needed anymore. This command lets you clear the contexts in case you suspect a memory leak or want to release memory. The 'global' context is never destroyed. To know which contexts are currently opened, open a Tcl shell and type the following command :
 AppleScript info contexts

The Mark pop-up menu

The marking procedure marks all the function definitions, 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 "{}" pop-up menu (top right of your editing window).

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 AppleScripts folder which is at the same level as the Alpha application itself. 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 :

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 c'to compile the current window or selection
'ctrl-a d'to get the scripting terminology
'ctrl-a e'to execute (compile and run) the current window
'ctrl-a l'to insert the line continuation symbol (¬)
'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 x'to clear the scripting contexts

AppleScript Mode preferences

The "Preferences..." item in the "Mode Prefs" submenu of the "Config" menu allows you to edit specific preferences for the AppleScript Mode. The default choices should not have to be modified.

Set the "Include Comments" 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.

Version History

Known problems

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 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:

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 regents or 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.