This is MPW Mode Help documenting the MPWS (Macintosh Programmer's Workshop and Shell) Mode in Alpha. For Alpha to find it, you must move this file to the Help folder located at the same level as the Alpha application itself.
MPW mode allows you to use Alpha as a frontend to MPW (Macintosh Programmer's Workshop) in order to write and to process scripts and commands written in the MPW language. It adds a new menu in the menu bar with all the necessary functionalities.
Main features are: syntax coloring, elaborate system of abbreviations and word completion, immediate help, executing command lines and scripts from within Alpha, retrieving the results in your script or in a separate window, getting or setting the value of all MPW variables and paths, browsing easily in the commands history etc.
MPW mode relies entirely on the capacities of the Tool Server application for communicating with MPW through Apple Events. ToolServer is a complete tool and script execution environment extracted from the MPW Shell that you can use to execute time-consuming, non interactive tools or scripts in the background or on a remote machine. Thus ToolServer can run most of the tools and scripts in the MPW tool suite and most tools and scripts which are written for MPW. The major exceptions are editor and Projector commands. ToolServer is primarily designed to be run using Apple events. As such, it can be run from Alpha.
For this mode to work properly, you must have installed MPW 3.3 or later and the ToolServer software. These programs can be found at
ftp://ftp.apple.com/devworld/Tool_Chest/Core_Mac_OS_Tools/MPW_etc./
Note that the mode here defined is refered to internally as MPWS. We will call it MPW mode in this document though. The reason for naming it MPWS is to avoid conflicts with an already declared MPW mode which is not, though, a standalone mode but is defined in the shellMode.tcl file apparently for technical reasons.
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 MPW Mode package. The icon though has to be installed manually using ResEdit (see below).
In versions of Alpha prior to 7.5, there is no MPW icon so the icon of the MPW application must be added to Alpha's resource fork: to do so, you must have a program to manipulate resources such as 'ResEdit' or 'Resorcerer'. ResEdit is a free software distributed by Apple. Resorcerer is a commercial product.
With ResEdit, open the mpwMode.rsrc file included in the distribution of mpwMode and open, also with ResEdit, the Alpha application (quit it before if it is running): copy and paste the icon resources ics#, ics4 and ics8 from mpwMode.rsrc to Alpha. All these resources have ID number 146 which is normally free.
If you do not fell like installing this icon, you will have to edit the mpwMode.tcl file and replace in the code all the occurences of '•146' (without the quotes) by the word MPW. It occurs only in three places.
You can install this menu permanently from "Config - Preferences - Menus".
Once the installion is completed, have a look at the mode specific preferences: see below.
For Tool Server to answer correctly to the requests sent by MPW mode, it is very important that it can find the various scripts and tools it needs: there is a user configureable variable called "Commands" which contains a list of all the directories searched for commands. The usual installation puts the 'Scripts' and 'Tools' folders as well as the ToolServer program itself in the 'MPW_Shell Folder' i-e at the same level as the MPW Shell program. In that case the "Commands" variable would have the following value:
:,{MPW}User Commands:,{MPW}Tools:,{MPW}Scripts:
where {MPW} designates the full pathname of the Macintosh Programmer's Workshop.
To check the current value of the "Commands" variable or to modify it, see below 'How to set the value of a variable'. If Tool Server complains that it cannot find a certain command, it generally means that the "Commands" variable is not set correctly. If you do not want to get involved in these settings, an easy workaround is to make aliases of the 'Tools' and of the 'Scripts' folders and put them (with the same name) in the same folder as the Tool Server application itself .
Another important point is the location of the 'MPW.Help' file: if Tool Server does not find it, the help requests will not work. If Tool Server complains that it can't find the MPW.Help file, put a copy (or an alias) of this file in the same folder as the Tool Server application itself. Another possible location for the MPW.Help file is in the MPW Preference folder (in the System Folder). Once again the best location for the Tool Server application and for the 'Tools' subfolder is at the same level as the MPW Shell itself.
Please also note that:
When you first start MPW, the current directory is {MPW} i-e MPW Shell's directory. To check which directory is presently the current directory, choose "Command Line..." in Alpha's MPW menu, type "directory", then press the "Execute" button.
There exists already an MPW mode in Alpha which is related to the Toolserver Shell (called with ctrl-cmd-Y). So the present MPW mode is in fact identified by the four letters 'MPWS' which stand for Macintosh Programmer's Workshop and Shell.
Now there are different ways of setting MPW mode:
%-*-MPWS-*-
There is a menu item to insert this magic line automatically. See "Set MPW Mode" in the MPW menu.
The MPW menu in the menu bar gives you full control on all the features of the MPW mode.
There are several ways of executing a command line. Your current window must be in MPW mode (see above). Put the cursor anywhere in the line you want to execute and hit the 'Enter' key or the 'Command-Return' combination (not Return alone which inserts a simple carriage return).
For instance, type the following line in your source file
date -s4
leave the cursor on the line and press Enter. A window named "* date -s4 *" is opened displaying the answer: for instance 4/07/2000 19:47:23. (Oh dear, I forgot to tell that today is the fourth of July and that it is now 7:47 pm).
You can also hilite the line you want to execute. If no region is hilited, MPW mode will take the entire line. On some PowerBooks, there is no Enter key, so use Command-Return instead.
Another possibility is to use the "Command Line..." menu item. It brings a window in which you can type a command line and execute it with the Execute button. This comes in handy when you want to execute a command but don't want to write it in your source file. Next time you call the "Command Line..." window, it will display the last command you typed. To experiment, type in for instance:
echo {SystemFolder}
The answer will be the location of the system folder on your installation. You can call the "Command Line..." window by just pressing the F5 key if you are already in MPW mode.
Choosing "Execute Lines" in the menu is equivalent to pressing Enter or Command-Return.
The result of the execution of a command line (if any) can be either displayed in a separate window or inserted at the cursor's current position in your script: there is a preference setting to choose between these two possibilities (see preferences below).
You can toggle the destination set in the preferences by holding the control key down. If the 'Send Result To Buffer' flag is set then the result is normally sent to the buffer: if you hold the control key down, it will be sent to a separate window instead. And vice-versa.
Similarly if you open the MPW menu with the control key down, the item "Execute Lines" is changed to "Execute and Toggle Target".
MPW users know the Commando Boxes. You can use Commando Boxes to execute a single command with all possible options in a very user friendly way. Use the "Commando Box..." menu item: you are prompted for the name of an MPW command. MPW mode switches to Tool Server and opens the corresponding 'Commando Box'. You can build there your command with all the options you wish: the result of the command is sent back to Alpha.
You can invoke the "Commando Box..." menu item by pressing the F4 key if you are already in MPW mode.
There is a third method to call a Commando Box which is traditionnaly implemented in the MPW application: type a word, then press option-Enter (or option-command-Return). It works here as well. Fourth method ; type your keyword followed by an ellipsis and press Enter.
In your source file you can also execute several lines consecutively: hilite them and press Enter or Command-Return. Beware that there is a size limitation for Apple Events: if you select too many instructions in a very long script (more than 32k), there might be an overflow. On the other hand, if the answer is too big, you might loose a part of it. In that case, you should consider using the "Execute the Buffer" or "Execute a Script..." menu items as explained below.
The "Built-in Commands" menu item contains a list of the main commands understood by MPW.
You can also launch any application on your hard disk by entering the applicationŐs name as a command. For example, if you have an application named BBEdit stored in the HD volume (or whatever its name is), you can start it by entering
HD:BBEdit
in the "Command Line..." window. If the application is in the MPW folder, you don't even have to write its full path name.
If your suite of instructions is too big or generates too big an output, the preceding methods might not work due to the limitations in data exchange through Apple Events (32k). The good method in that case is to have it executed as a script, i-e a separate file containing all the instructions you want to execute. To execute the current window, select "Execute the Buffer" in the MPW mode menu. To execute any script, select "Execute a Script..." in the MPW mode menu. You will be asked about parameters, options or flags to add: a script may require some parameters and accept some options or flags. If you choose 'Yes', you will have a window in which you type the additional information.
One should know that Tool Server doesn't have any console to show its output: its default behavior is to send its output to a file. For instance, if your current window is called Myscript, the output of your script will be sent to a file called Myscript.out. If there are any error messages, they are sent to a file called Myscript.err. These files are located normally in the same folder as your script Myfile.
There is however a possibility to write the .out and the .err files in different folders: the destination folder for these two files is contained in the variables 'BackgroundOut' and 'BackgroundErr'. MPW mode is aware of that and checks the value of these two variables to be able to open the .out or .err files when you use the "Open Out File" or "Open Err File" menu items. If your script doesn't generate any output, there will be of course no .out file. If there is no error in your script, there will be no .err file.
Note that you can also execute a script using a simple command line. Call the "Command Line..." menu item and type the full path name of your script with the necessary options: if you do not want to bother with typing an entire path name, there is a "script" button which allows you to navigate in the files hierarchy and designate the script you want to execute: its full pathname will be automatically inserted in the command line (with double quotes to avoid problems with whitespaces). Add any required options and press the Execute button.
When you execute a script like this, the output is sent directly to Alpha in a separate window: there is no issue about .out or .err files.
The MPW menu has submenus named "Built in Commands", "Internal Variables", "User Variables" and "Libraries Variables".
The former contains the names of the built-in commands: clicking on any of them inserts their name at the cursor's position in the current window. The other three menus contain respectively the variables defined by the MPW Shell (whose values are maintained dynamically by the MPW application), the variables used by the MPW Shell which are all configureable and the variables used for libraries and include files (they contain the pathname of the directory containing the corresponding libraries: their value can be set by the user).
Concerning the dynamic variables, when you select them from the submenu, they are included in the source file and enclosed with braces. This is because, since they are not configureable, you shall always use them to get their value. Enclosing a variable name with braces has the same meaning in MPW's syntax than the $ sign in Tcl: it returns the current value of the variable.
In these submenus you can make use of the option and control keys. The signification is as follows:
In that case, all the menu items in the submenus are prefixed with 'get '. This means that you want to know their current value. The answer is given in a separate info window or inserted in your script (see preferences below). For instance, 'MPWVersion' in the Internal Variables will be changed to 'get MPWVersion' if you hold the option key down. The answer could be '3.5' if you are using version 3.5 of MPW.
In that case, all the menu items in the submenus are prefixed with 'set '. This means that you want to give a new value to a certain variable. For instance, 'FontSize' in the "User Variables" submenu will be changed to 'set FontSize' if you hold the control key down. You will be prompted in a special dialog window to set the new value. For instance type '12' to fix a 12pt size used for new windows (note that this affects the font size in MPW, not in Alpha). If the value of a variable is a path, there will be a Browse button in the dialog window to help you navigate to the folder you want to choose so that you don't have to bother about typing a full path name.
For the 'Commands' and 'DirectoryPath' variables, the dialog window is more elaborate since they can contain a list of directories (not a single one). You can add or remove paths to these lists.
A very handy feature of MPW mode (like in many other modes in Alpha) is word completion. To enable it, you must load the elecCompletion package (in Config - Preferences - Features) and choose your completion key (default is F1). You can then type the first letters of a command or a keyword and then hit the F1 key: MPW mode will complete automatically.
For instance, type 'Scre' and hit the F1 key: it is completed immediately to 'ScreenUpdateDelay'.
Now type just 'All' then hit the F1 key: 'All' will become 'Allow'. Hit the F1 key again ; a window shows up with a list of all possible completions:
"AllowCmdsOnlyInWorkSheet" "AllowColorizing" "AllowColorUserExperience" "AllowDraggingOut" "AllowMultipleUndo" "AllowWhiteSpaceDelimiter".
Pick up the one you want to be inserted in the current window.
Note that, the MPW language being case insensitive, you can type everything in lowercase. Thus 'scre' will yield 'screenupdatedelay'.
Another aspect of completion is the use of abbreviations. If you type 'bg' and hit the F1 key, you get:
Begin • End •
the cursor being positioned at the place of the first bullet •: use the Tab key to jump to the next bullet. This works with 'for', 'loop', 'if' and 'ifel'. The latter expands to:
If • Else • End •
There are four contractions concerning the output redirections:
d'so Dev:StdOut d'se Dev:StdErr d'n Dev:Null d'c Dev:Console
Finally there is a very intuitive system of abbreviations for long variable names which are compound names, like 'ScreenUpdateDelay'. You can just type the initial letters (initials of the words composing the variable name): for instance here just type 'sud' and then hit the F1 key to get 'ScreenUpdateDelay'. There are only two ambiguous situations:
Here is the complete list of abbreviations:
ac AllowColorizing acoiws AllowCmdsOnlyInWorkSheet acue AllowColorUserExperience ado AllowDraggingOut ai AutoIndent amu AllowMultipleUndo awsd AllowWhiteSpaceDelimiter be BackgroundErr bo BackgroundOut bs BackgroundShell cfd CursorForDragging cod CheckOutDir cs CaseSensitive dcl DeleteCharLeft dcr DeleteCharRight deof DeleteEndOfFile deol DeleteEndOfLine dfs DontFlushServers dfv DontFlushVolumes dnr DuplicateNameRevisions dp DirectoryPath ds DynaScroll dsof DeleteStartOfFile dsol DeleteStartOfLine dwl DeleteWordLeft dwr DeleteWordRight ews ExtendWordSet fs FontSize get GetErrorText gfn GetFileName gli GetListItem hc HeapCheck hhk HideHelpKey icp IgnoreCmdPeriod imc InhibitMarkCopy lnr LockNameRevisions mcl MoveCharLeft mcr MoveCharRight mef MakeErrorFile meof MoveEndOfFile meol MoveEndOfLine mld MoveLineDown mlu MoveLineUp mpd MovePageDown mpu MovePageUp mro ModifyReadOnly msof MoveStartOfFile msol MoveStartOfLine mwl MoveWordLeft mwr MoveWordRight nkl NewKeyboardLayout nkm NewKeyMap nwr NewWindowRect onr ObsoleteNameRevisions opf ObsoleteProjectorFile pf PrefsFolder po PrintOptions pv ProjectorVersion rpf RenameProjectorFile sb SearchBackward scl SelectCharLeft scr SelectCharRight sd ShellDirectory sdg SuppressDialogs sdn ShutDown seof SelectEndOfFile seol SelectEndOfLine sf SystemFolder sld SelectLineDown slu SelectLineUp so StackOptions soc SaveOnClose spd SelectPageDown spu SelectPageUp ssof SelectStartOfFile ssol SelectStartOfLine sss SetShellSize st SearchType stf SysTempFolder sud ScreenUpdateDelay sw SearchWrap swl SelectWordLeft swr SelectWordRight tf TempFolder tfs TraceFailures to TileOptions tst ToolSleepTime twc TabWidthChar unr UnlockNameRevisions uonr UnObsoleteNameRevisions uopf UnObsoleteProjectorFile upd UpdateProjectorDatabase usf UseStandardFile usk UnSetKey ws WordSet zh ZoomHeight zw ZoomWidth zwr ZoomWindowRect
To get help about any built-in MPW command and about its syntax, you just have to command-double-click on its name: that is to say, double-click while pressing the command key down. For instance, command-double-clicking on the word 'date' will display a separate window with the following information (or insert the information at the cursor's location):
Date # write the date and time Date ([-a | -s | -s4 | -u] [-st] [-d | -t] [-c seconds | -utc]) | ([-n] [-utc]) | [-x date] -a # abbreviated date (e.g. Wed, Jun 14, 1995) -s # short date (e.g. 6/14/95) -s4 # short date, using 4-digit year (e.g. 6/14/1995) -u # uniform output format, "YYYY MM DD HH:MM:SS" -st # omit seconds from time format -d # write date only -t # write time only -c seconds # write date corresponding to seconds -x date # write seconds corresponding to date -n # write seconds since January 1, 1904 -utc # write output converted to Universal # Time Coordinates
As explained above, the Enter key and the Command-Return combination are used to execute a command line. If you press the Shift key simultaneously, the result will be inserted in the current window.
Use Ctrl-Cmd-Return to execute the buffer.
To enclose a variable name in braces, place the cursor anywhere in the word and use ctrl-( . To remove any encloser around a word or a region, hilite it and use ctrl-) .
Call the "Command Line..." window with the F5 key.
Call the "Commando Box..." window with the F4 key. Alternatively, type a keyword, then press Option-Enter or Option-Command-Return, to call up the Commando Box corresponding to this keyword.
The "Show Bindings" menu item displays a window with a summary of all the existing key bindings in MPW mode. Some of these functionalities are not accessible from the menu, only with the corresponding key binding.
Key combination |
Signification |
cmd-return or enter |
execute a line or a selection |
ctrl-cmd-return or ctrl-enter |
execute and toggle result's destination |
ctrl-cmd-enter |
execute the buffer as script |
opt-ctrl-cmd-return |
execute a script... |
opt-enter or opt-cmd-return |
open command's commando box |
F4 or ctrl-opt-k |
ask for commando box... |
F5 |
open command line window |
F6 |
open special chars palette |
ctrl-up |
browse up in commands history |
ctrl-down |
browse down in commands history |
ctrl-" |
surround with " " |
ctrl-' |
surround with ' ' |
ctrl-` |
surround with ` ` |
ctrl-( |
surround with ( ) |
ctrl-opt-( |
surround with { } |
shift-ctrl-opt-( |
surround with [ ] |
ctrl-< |
surround with < > |
ctrl-opt-< |
surround with << >> |
ctrl-) |
remove any encloser |
Explanations for the MPW menu items:
If there is no selection, the word around the current cursor's position is enclosed. Otherwise, the entire selection is enclosed.
Equivalent key binding: ctrl-(. There are also several other key bindings to automatically insert some of the delimiters, shortcutting the status bar prompt. See key bindings above.
CFM-68K |
Launch |
Scripting |
Characters |
Miscellaneous |
Selections |
Commands |
Patterns |
Shortcuts |
Editing |
PowerMacintosh |
System |
Expressions |
Projector |
Variables |
FileSystem |
Resources |
Window |
Languages |
|
|
When pressing the option key down, each item becomes: 'get item' to get the value of the corresponding variable.
When pressing the option key down, each item becomes: 'get item' to get the value of the corresponding variable.
When pressing the control key down, each item becomes: 'set item' to set the value of the corresponding variable. See description above.
When pressing the option key down, each item becomes: 'get item' to get the value of the corresponding variable.
When pressing the control key down, each item becomes: 'set item' to set the value of the corresponding variable. A navigation window lets you designate the folder. See description above.
There is no specific file marking for MPW mode.
The list of all the commands previously executed is called the commands history: you can access this list by option-clicking on the title bar of your current window (if it is in MPW mode of course). This will show you a list of the last used command lines: you can choose any of them and have it inserted in the current window. The Reset History List item allows you to empty this command history. There is a maximum number of command lines which can be stored in the history. By default, this number is equal to 20 but you can modify this value in the mode specific preferences. Long commands (more than 50 chars) are not included in the history.
Alternatively you can navigate through the history of commands using the two key combinations ctrl-UpArrow or ctrl-DownArrow: this will insert at the cursor's position, one after the other, the various commands that have been stored in the history.
The Functions pop-up menu (symbolized by '{}' at the top right of the current window) contains a list of all the variable names used (with a 'set' command) in your script.
Remember that the abbreviation for MPW Mode is 'MPWS'. The Preferences... item in the Mode prefs submenu of the Config menu allows you to edit specific preferences for the MPW Mode (if you are in already in MPW Mode; if not, switch to MPW Mode). Most of them should be self-explanatory:
Please e-mail any problem or bug you encounter: bdesgraupes@easyconnect.fr
Copyright Bernard Desgraupes, 2001 All rights reserved. This software is free software 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.