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
- put the "applescriptMode.tcl" file 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.
- 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
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
- 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.
Known problems
- There is no way to check the syntax of a script before compiling it.
Just compile your script : all the error messages sent by the scripting
component will be reported.
- There is 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
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 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.