This file documents the Tcl shell and the Toolserver shell

===============================================================================

	TCL SHELL

The basic idea of the Tcl Shell is to provide an interactive way to access 
TCL, it is *NOT* intended to serve as a pseudo-unix-shell. However, I don't 
use MPW or AU/X, and therefore I implemented a few very useful unix shell 
functions. 

All pathnames must be mac pathnames; relative pathnames start 
with colons, absolute pathnames don't. For instance, ':file1' specifies a 
file named 'file1' in the current directory. '::file2' specfies a file in 
the parent directory, and ':::file3' is a file in the parent's parent's 
directory. Additionally, hitting command-tab with a partial pathname invokes 
a filename-completion function that tries to fill in the rest of the 
characters of the name. 

The supported functions are all valid Tcl commands and the following:

cat <file>...  Dump contents of files into shell window.

cd <relative or absolute pathname>
	Change directory. If called with no arguments, go to home directory.
cp <file1> <file2>
	or
cp <file1> .... <destDir>
	Basic unix functionality, recursive.

dirs - show current directory stack. See 'pushd' and 'popd'.

grep <pat> <file>...
	Grep, reasonably slow.

mkdir <dirname> - make a directory (folder)

ls [-F|l] [<file>]...
	Two, mutually exclusive flags. '-F' just gives the normal display, with 
	a '*' behind applications and a '/' behind directories (folders). '-l' 
	presents a long listing, including sizes of both forks, creator, file 
	type, and last modification time. 'procs.tcl' includes functions 'l' and 
	'll' which serve as my Unix aliases to 'ls -F' and 'ls -l'.
	
mv <file1> <file2>
	or
mv <file1> .... <destDir>
	Moves a file, potentially across volume boundaries. Recursive.

popd - Pop top dir off dir stack and 'cd' to it.

pushd [<dir>] - If 'dir' specified, push current folder into directory 
    stack and 'cd' to dir. Otherwise, swap current dir w/ top of dir stack.

ps
	Prints a list of active applications.
	
rm [-r] <file>...
	Removes files and empty directories. "-r" allows recursive removal, but 
	DON'T BLAME ME IF YOU DELETE YOUR ENTIRE DRIVE!
	
rmdir <dirname> - remove a directory (folder)

setCreator <creator> <files> - Changes the creator of given files, which can
	be glob expressions.

setType <type> <files> - Changes the type of given files, which can
	be glob expressions.

wc <file>...
	'wc' primitive from unix, counts lines, words, characters.


The file ":Tcl:Modes:shellMode.tcl" contains Tcl code implementing the 
shell interface.  You can change this to suit your tastes.  One recent 
goody is that you can re-execute previous commands merely by moving the 
cursor to the line and hitting the return key.  If there is no '>' 
character on the line when you hit a carriage return, the return is an 
ordinary new line.

A primitive history mechanism can be used to move up and down the last 20 
commands by using control-uparrow and control-downarrow at a prompt.

===============================================================================


        Using ToolServer With Alpha

Draft, March 16, 1999: Eric Petersen <epeterse@aem.umn.edu>

        Introduction

ToolServer is a complete tool and script execution environment extracted
from the MPW Shell that you can use to execute time-consuming,
noninteractive 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 MPW 3.3 or later using the built-in MPW RShell command and
from third-party applications that include support for ToolServer. You can
also use ToolServer as a foreground application; you specify the scripts to
be executed and obtain the status of executing scripts by choosing the
appropriate File menu items.

[From ÒToolServer ReferenceÓ]

        Getting Started

Type control-command-Y to open the Toolserver Shell, an Alpha window titled
Ò*Toolserver shell*Ó.  (This will also launch the ToolServer
application.)  You will see the following message and prompt:

    Welcome to Alpha's MPW shell (using ToolServer via AppleEvents).
    ÇmpwÈ |

The cursor will be positioned as shown by the Ò|Ó.  You may now type a
command and hit _return_ (MPW users will have to unlearn hitting _enter_ to
execute a command).  The following commands are supported by ToolServer:

    Alert          Directory      Exit           Newer          Shift
    Alias          Duplicate      Export         NewFolder      ShutDown
    Beep           Echo           Files          Parameters     Unalias
    Begin...End    Eject          Flush          Quit           Unexport
    Break          Else           For...         Quote          Unmount
    Catenate       Equal          Help           Rename         Unset
    Confirm        Erase          If...          Request        Version
    Continue       Evaluate       Loop...End     RShell         Volumes
    Date           Execute        Move           Set            Which
    Delete         Exist          Mount          SetFile

Additional tools and scripts may be placed in the ÒScriptsÓ, ÒToolsÓ,
and ÒUser CommandsÓ folders.  These names are for your benefit only;
tools may be placed in the ÒScriptsÓ folder, user-defined commands may be
placed in the ÒToolsÓ folder, etc.  You should be aware that newer
distributions of MPW have merged the ÒToolsÓ and ÒScriptsÓ folders 
into a single ÒCommandsÓ folder.  ToolServer also has access to
environment variables, called MPW variables.  The _value_ of these
variables is obtained by enclosing the variable name in curly braces.  For
example, the command [1]

    ÇmpwÈ echo {commands}

will return a comma-delimited list of the pathnames that ToolServer
searches to find commands:

    :,HD:MPW:User Commands:,HD:MPW:Tools:,HD:MPW:Scripts:

Thus the current directory Ò:Ó is searched first, then ÒUser CommandsÓ,
ÒToolsÓ, and ÒScriptsÓ in that order.

* [1] You should be aware that MPW and ToolServer are not, by default, case
sensitive.

If you wish to save typing keystrokes---and time spent learning---by using
Unix-style command names, you may execute commands such as

    ÇmpwÈ alias cd     directory
    ÇmpwÈ alias pwd    directory
    ÇmpwÈ alias grep   search
    ÇmpwÈ alias mkdir  newfolder
    ÇmpwÈ alias mv     move
    ÇmpwÈ alias cp     duplicate
    ÇmpwÈ alias rm     delete
    ÇmpwÈ alias ls     files
    ÇmpwÈ alias source execute

These aliases will be forgotten when ToolServer quits however.  It would be
better to save these commands in a file in the ÒTS Startup ItemsÓ folder;
all files in ÒTS Startup ItemsÓ are executed when ToolServer launches. 
The items in the ÒTS Startup ItemsÓ folder do not have any special naming
conventions, and will be executed in alphabetical order.  They can also be
any type of executable entity, such as scripts, tools, and/or 
applications.  As we'll see later on, you might want to put an alias of 
the Key Caps utility in as well.

To get started, make an alias of the Alpha application and place it in 
the ÒUser CommandsÓ folder.  Now the command (assuming that the alias is 
named ÒalphaÓ)

    ÇmpwÈ alpha foo

will open the file ÒfooÓ in the current directory with Alpha.  This is of 
little use until the current directory is set; the current directory is 
set to the location of the ToolServer application initially.  Obviously 
the ÒdirectoryÓ command is needed here, but how does it work? Type

    ÇmpwÈ help directory

to get the help text

    Directory       # set or write the default directory
    Directory [-q | directory]  > directory
        -q          # don't quote directories with special characters

ÒDirectoryÓ by itself writes the full pathname of the current directory
(hence the alias to ÒpwdÓ above), while Òdirectory dir_pathnameÓ sets
the current directory to Òdir_pathnameÓ (as would be expected from the
alias to ÒcdÓ).  To see an example, try

    ÇmpwÈ directory
    ÇmpwÈ directory :: ; directory

which return ÒHD:MPW:Ó and ÒHD:Ó, respectively, in this example.  (The
parent directory of Ò:Ó is Ò::Ó, Ò:::Ó is the grandparent directory, etc. 
We also note the use of Ò;Ó to separate commands on a line.)  Now ÒfilesÓ
will list the files _and_ folders in the current directory:

    ÇmpwÈ files
    :Applications:
    ':Desktop Folder:'
    :MPW:
    :Papers:
    :Pictures:
    :Trash:
    Bookmarks.html
    cholesky.tex
    thesispage.sty

Note that names with spaces or special characters must be quoted if they
are to be used in commands.  You can now navigate to your desired folder
all at once, or step-by-step:

    ÇmpwÈ directory 'HD:Applications:Alpha Ä:Tcl:Modes:'

In this example, the ÒÄÓ (option-f) character was entered via the Utils
-> Ascii Etc -> Insert Ascii menu item, since _typing_ option-f will
trigger the Edit -> Emacs -> Forward Word command in Alpha.  (Its ASCII
code is decimal 196.  You could also paste it from, say, the Key Caps
utility.)  Now, to find all occurrances of the string ÒToolServerÓ in the
code, type

    ÇmpwÈ search -i toolserver Å.tcl  # -i is a case-insensitive search

The MPW wildcard character ÒÅÓ (option-x) is ASCII code 197, and 
the Ò#Ó symbol starts a comment.

As a final exercise, let's create a small, but useless, script to play a 
tune.  We'll need the ÒbeepÓ command, so let's find out how to use it.

    ÇmpwÈ help beep
    Beep            # generate tones
    Beep [note [,duration [,level]]]É
        #   duration is given in sixtieths of a second (default is 15)
        #   sound level is given as a number from 0 to 255 (default is 128)

So save the following pair of lines in a new file ÒChimesÓ in the ÒUser 
CommandsÓ folder:

    beep 2e,20,40  2c,20,60  2d,20,80  1g,40,100
    beep 1g,20,120 2d,20,140 2e,20,160 2c,40,180

When the file is saved, type

    ÇmpwÈ chimes

to hear the tune.

**Miscellany**

* You should also note that ToolServer will not automatically come to the
front when an interactive command, such as Alert, is executed.

		Where to Download

* ToolServer

<ftp://ftp.apple.com/devworld/Tool_Chest/Core_Mac_OS_Tools/MPW_etc./
    MPW-GM/MPW/ToolServer.sit.hqx>

* ToolServer Reference (PDF format)

<ftp://ftp.apple.com/devworld/Tool_Chest/Core_Mac_OS_Tools/MPW_etc./
    Documentation/MPW_Reference/ToolServer_Reference.sit.hqx>

* Introduction to MPW (PDF format)

<ftp://ftp.apple.com/devworld/Tool_Chest/Core_Mac_OS_Tools/MPW_etc./
    Documentation/MPW_Reference/Introduction_to_MPW.sit.hqx>

* MPW Tools for use with ToolServer

<ftp://ftp.apple.com/devworld/Tool_Chest/Core_Mac_OS_Tools/MPW_etc./
    MPW-GM/MPW/Tools/>

* MPW Command Reference (documentation for MPW Tools, PDF format)

<ftp://ftp.apple.com/devworld/Tool_Chest/Core_Mac_OS_Tools/MPW_etc./
    Documentation/MPW_Reference/MPW_Command_Reference.sit.hqx>

		FAQ

* Q: My file in ÒTS Startup ItemsÓ doesn't get executed. Why not?

* A: You probably have a syntax error or are trying to use a command not
supported by ToolServer.  Look in the file ÒStartupTS.errÓ in the
directory with ToolServer.  It will probably contain something like

    ### ToolServer - Execution of HD:MPW:TS Startup Items:your_file terminated.
    ### ToolServer - Execution of StartupTS terminated.

Unfortunately, you have to figure out the offending command or syntax on 
your own.
