                        TomShell Reference Manual
                             October 4, 1990
                       last revised August 10, 1991
                                Tom Clegg

 Table of Contents
 -----------------
  0. 0.200! new features
  1. TomShell Commands
        alias           dir             ls              system
        author          echo            mkdir           unalias
        cat             exit            mv              unset
        cd              help            ren             verbatim
        cls             history         rm              word
        condense        input           rmdir
        cp              interact        set
  2. Batch file only commands
        gosub           resume
        goto            return
        if              :label
        ifv
  3. Special variables
        0..99           dcdwatch        keystat         quick
        anygem          f               margin          resolution
        cwd             f1..f20         mem             status
        date            font            nolabel         time
        disk            force           owrite          verbosity
        dcd             key             PATH            volume
        **********  NEW: pause, prompt, shortdir, width  ***********
  4. Special characters
        >       >>      <       $       \       #       ;       !       "
  5. Explanations
        .1 Batch files
        .2 Errorlevels
        .3 Filename completion
        .4 Modes of Operation
        .5 Output devices
        .6 Running Programs
        .7 Variables
   
 =======================================================================
  
 0. 0.200! New features
 ----------------------
  .1    Finally, "ls" does good columns!  The list goes down the first (left)
        column, down the second column, down the third column, and so on.
        This is much better for actually trying to find files.  Maybe
        eventually this will be used in the "help" command as well. :-)

  .2    Two new variables have been implemented: pause and prompt.  Check
        out the appropriate sections in the manual (search for "(NEW)").
        I'm especially proud of "prompt".  :-)  Why are there so many
        happy faces here?  :-)

  .3    Two more variables have been implemented: shortdir and width.  Again,
        check for function later on.

  .4    With all these new variables, the "set" output got far too long to
        be useful (on a 25-line screen, all user variables were scrolled off
        the top by the system variables), so the system variables are hidden
        unless a "set s" command is given.  Much nicer looking.

  .5    Small and probably unnoticed feature removed: "alias f" would do
        the "set f" output but preceded by "f=    ".  Rather insignificant,
        but worth fixing anyway.  :-)
  
 1. TomShell Commands
 --------------------
 alias         author        cat           cd            cls           condense
 cp            dir           echo          exit          help          history
 input         interact      ls            mkdir         mv            ren
 rm            rmdir         set           system        unalias       unset
 verbatim      word

 alias          assign a complex meaning to a simple word.

                alias jim cat d:\stadel\money   # `jim' now means `cat d:\...'
                alias jim                       # what is "jim" aliased as?
                alias                           # list all aliases

 author         display initial message about me and my address.

                author

 cat            display a [text] file to the current output device.  Can
                be redirected via >whatever

                cat file1
                cat file1 file2

 cd             change current default (working) directory.  Equivalent to
                "set cwd ..."

                cd e:\stadel\
                cd \files\texts
                cd d:\

 cls            clear the screen using the VT52 "esc E" command.  Can
                be redirected via >whatever

                cls

 condense       take the spaces out of a variable's value.

                condense blah   # blah="foo bar" => blah="foobar"

 cp             copy files.  If there is more than one argument, the last
                one is considered to be the destination directory or file.
 
                cp jimbob.doc joebob.asc          # copy jimbob to joebob
                cp fubar.txt \texts\              # copy fubar.txt to \texts\
                cp fubar1.txt fubar2.txt \texts\
                cp fu*.doc \texts\
                cp fu*.doc                        # copy to current dir.
                cp fubar.txt                      # copy to current dir.

 dir            list files in current or given directory.  A search mask
                or path may be given.  Each file is displayed on a separate
                line, with its size, date, time, and status bits displayed
                in neat columns along with it.  Subdirectories are denoted
                by a trailing "\".
 
                dir                     # list all files in cwd
                dir \texts\             # list all files in \texts\
                dir \texts\*.doc
                dir *.txt *.doc g:\*.c
 
 echo           display the arguments to the current output device.

                echo blah               # output: blah<cr/lf>
                echo                    # output: <cr/lf>
                echo -n blah            # output: blah
                echo this is a test
                echo -n this is a test
                echo -n $disk;echo k    # output: (eg) 763k
 
 exit           exit the current batch file or interactive session.
 
                exit
                exit 44                 # sets $status to 44 and, if exiting
                                          TomShell completely, returns 44
                                          to the calling program.
                (see also "system")
                
 
 help           display a list of available commands and reserved variables.
 
                help
 
 history        display the last twenty commands entered, with line numbers.
                These entries can be accessed with !# or !string (!# refers
                to the line with the given number attached to it, !string
                to the most recent command starting with "string").

                history
 
 input          take one line of text input from the current input device
                and place the received text in the given variable.

                input name
                input name <aux: >aux:

 interact       enter interactive mode until the command "exit" is issued.
                See "Modes of Operation" below for more details.
 
 ls             display a short listing of files.  Sytax is the same as
                "dir", but the files are listed in columns of filenames
                rather than with the size, date, time, etc.

 mkdir          create a directory (folder) with the given name.

                mkdir tree
                mkdir c:\blah
                mkdir \test\phroo       # note: \test will not be created
                                        # if it doesn't already exist

 mv             identical to "cp" but, if a file is successfully copied,
                the original file will be deleted.

 ren            rename a file

                ren fubar.doc foobar.doc
                ren jimbob \texts\      # jimbob -> \texts\jimbob
                
                * Note: files can be renamed to anywhere on a logical drive
                without being copied or moved (renaming is faster), but
                not between drives.
                * Note: under TOS 1.4 or greater, folders can also be
                renamed.

 rm             delete the specified file or files.

                rm fubar.txt
                rm *.*
                rm *.txt

 rmdir          delete the specified directory (folder)

                rmdir test
                rmdir c:\temp
                
                * Note: trying to delete a non-empty directory will result
                in an error message.

 set            change the value of a user or system variable, or, if the
                variable specified does not exist, create a new variable
                with the given information.

                set name Tom
                set verbosity 2
                set name                # display the contents of $name
                set                     # list all user-defined variables
                set s                   # list all system variables
                set f                   # list function key macros
                
 system         exit all levels of TomShell and return to the calling
                program.  Differs from "exit" in that if it is called
                from a nested batch file or an "interact" system, the
                system will exit completely rather than going back one
                level.
                
                system

 unalias        remove an alias entry from the list

                unalias v

 unset          remove a variable entry from the list
 
                unset name

 verbatim       display a file to the console.  NOTE: This will ONLY output
                to the console and cannot be redirected.  It provides the
                advantage of being able to view a file containing non-ASCII
                characters properly.  Any character except for <cr> and <lf>
                will be output as some form of character.  Great for looking
                at binary files (why?)

                verbatim tomshell.ttp

 word           truncate the given variable to only one word (everything
                before the first space)
                
                word name       # "Tom Clegg" -> "Tom"
 

 2. Batch files only
 -------------------
 gosub         goto          if            ifv           resume        return
 :label
 
 gosub          branch to a given label until a "return" statement is
                encountered, whereupon execution will continue from this
                point
                
                gosub test.label

 goto           branch to a given label

                goto test.label.2
                
                * Note: gosub, goto, and return work just like in BASIC.

 if             conditional statement, can use "and"/"or". Just like BASIC,
                but the [in]equality operators are like C (==, !=, <, >,
                <=, >=)

                if <exp> and <exp> or <exp> then <cmd>
                if $status >= 0 and $key == off then phroo.bat
                if $status <0 or $key == on then fubar
                if $status != 3 then gosub test.label.3

 ifv            simplified form of "if".

                ifv status 0 goto foo
                 [equivalent to:]
                if $status == 0 then goto foo

 resume         reset the "stopped" flag.  The "s" key sets the flag,
                and "resume" or the command prompt display resets it.
                If it is set, no text is displayed unless "force" ==
                "on" (see "force")

                cat 1stfile
                resume          # in case 1stfile was aborted
                cat 2ndfile     # this one's important!

 return         return from a subroutine.  An error results if there is
                no "address" on the stack to return to (we aren't in
                a subroutine).
                
                return

 :label         define a label that can be jumped (goto label) or
                branched (gosub label) to.
                
                :test.label
                :test.label.2

 Special variables
 -----------------
 0..99 ^       anygem        cwd           date ^        disk ^        dcd ^
 dcdwatch      f             f1..f20       font          force         key ^
 keystat ^     margin        mem ^         nolabel       owrite        PATH
 quick         resolution ^  status        time ^        verbosity     volume
        **********  NEW: pause, prompt, shortdir, width  ***********
 ^ == read only
 
 0..99          the arguments passed to the current batch file, or the last
                one executed.  $0 is the name of the batch file, $1 is
                the first argument, $2 the second, and so on

 anygem         if tomshell is run from the \auto\ folder or as a .TOS
                program, set this variable to "off" before running any
                programs within Tomshell.  This disables the mouse on/off
                routines and automatic GEM program recognition (.prg/.app).

 cwd            current working directory. "set cwd gleep" is equivalent
                to "cd gleep".  Good for putting in the prompt string.

 date           the current date: Mmm dd, yyyy

 disk           free space on the current drive, in kilobytes.

 dcd            DCD pin on serial port (carrier detect).

 dcdwatch       if this is set to "on", TomShell will exit to its calling
                program as soon as it detects loss of carrier. Default is
                off.

 f              list of all the function key settings

 f1..f20        individual function key macro settings.  f11..f20 mean
                shift+f1 to shift+f10. Always use "definition" when
                setting these (always use quotes).  To include a <return>,
                use "\r".
                Similarly:      \b      backspace
                                \t      tab
                                \e      escape
                                \r      return
                                \<      left arrow
                                \>      right arrow
                                \[      shift-left arrow
                                \]      shift-right arrow
                                \^      up arrow
                                \v      down arrow

 font           big/small (monochrome only).  Refers to the system font size,
                small == 8x8, big == 8x16.  The 8x8 (small) font gives you
                50 lines per screen, the 8x16 (big) font gives you 25.
                Default is big.  Trying to use the small font in colour or
                (especially) on a TT is perilous.

 force          if this is set to "on", the [P] and [S] keys are disabled
                (display is uninterruptable).  Default is off.

 key            "on" if there is a key waiting in the key input buffer
                (use it as an abort key in, say, a time-consuming script).

 keystat        bit mapped number, each bit represents a different status
                key:
                bit     value   meaning
                0        1      right shift
                1        2      left shift
                2        4      control
                3        8      alternate
                4       16      caps lock on
                5       32      right mouse button
                6       64      left mouse button

 margin         the number of spaces output before each line displayed
                (after each <cr><lf>).  Usually only good for printing.
                Default is 0.

 mem            the size of the largest block of free memory, in kilobytes.

 nolabel        "exit" or "cont".  Controls behaviour of tomshell when
                a label is not found (goto/gosub).  "exit" will force
                a "system" command when a variable is not found, and when
                $nolabel == "cont", tomshell will continue as if the gosub
                or goto command had not been made.  Default is exit.

 owrite         controls behaviour when the destination file for a cp or
                mv operation already exists. "off", "on", and "ask".
                Should be obvious.

 PATH           list of folders, separated by commas, where tomshell will
                search for programs and batch files that are called but
                not found in the current directory. "." does not need to
                been included.

 pause (NEW)    set to any value under 32767 to pause after the given number
                of lines have been displayed (since the last keypress).
                The "More..." prompt will be shown, and you can type:
                        S       stop output: like normal [s]
                        C       continuous: don't do any more pausing
                Note that the C option is temporary; it will stay in effect
                until you press a key.  This includes pressing a key during
                the listing of (for instance) the file being displayed,
                which is a bit silly but sometimes useful.
                To turn this feature off permanently, set pause to 0.
                The default for this variable is 0 (no pause).

 prompt (NEW)   like many shells' prompt string, but slightly more powerful
                and interesting.  Not only can you display whatever you want
                in place of the standard "1 c:\tomshell > " prompt, you can
                run programs and execute other commands when the prompt is
                displayed.  Please note that this is a bad place to put an
                "interact" command.  Probably the worst place.  Don't. :)
                A trailing space character is always output after this
                command is executed, since it's very difficult to coerce
                tomshell into outputting a space character on its own.
                The default setting is "echo -n $ncmd $cwd >", which outputs
                the index of the current command (useful for !13 etc) and
                the current directory.  You could run batch files and neat
                stuff like that from here, but it's good to keep the
                execution time of this command down, since it's done a lot.
                Usually you'll just use the "echo" command.
                
                When setting this, put the command you want to be in the
                prompt string in quotation marks.  Otherwise, $variables
                are likely to be evaluated at the time of the "set prompt"
                command rather than during execution of the prompt string.
                
                set prompt "goo;echo -n $ncmd FOOBAR $cwd SILLY >"

 quick          "on" or "off".  Makes output to the screen quicker, but
                must be turned off for remote use.  Default is off.

 resolution     the current resolution of the ST's screen. High, medium, or
                low.  TT resolutions are called "unknown".

 shortdir       if on, the time and date are left off the "dir" listing.
                Good for getting two columns on an 80-column screen and
                still seeing the file sizes and attributes.  Default is
                off.

 status         the exit code returned by the last command or program
                executed.  Most tomshell commands leave $status intact.

 time           the current time.  hh:mm:ss in 24-hour format.

 verbosity      0, 1, and 2 supported now.  Controls amount of information
                displayed by tomshell.  Currently only restricts "cmd exit
                code #" (displayed only when $verbosity >= 1) and "File
                not found" (GEMDOS verbal error messages) (displayed only
                when $verbosity >= 2).  Default is 2.

 volume         if set to "on", the volume name and serial number of the
                disk in question will be displayed on the first line of a
                "dir" output.  Default is off.

 width          screen width.  Used for figuring out how many columns to
                use in "ls" and "dir".

 ------------------
 Special characters
 ------------------
 >     >>    <     $     \     #     ;     !     "
 
 >              |
 >>             | redirection
 <              |

 $              precedes variable names (echo $name)

 \              separates directory names from each other and from filenames

 #              (.tom files) from here to end of line is a comment

 ;              separates two or more commands (echo $name;cat phroo;exit)

 !              used to access command history entries (see "history")

 "              text enclosed in "quotes" will not be inspected for > <
                >> $ -n etc.  Use if you want to print "test   test" (>1
                space between words) or "$56.45" or "shmoo -n pak" or
                something like that.
 
 =======================================================================
 5. Explanations
 ===============
 
 .1 Batch files
 --------------
 To create a batch file, use any editor or word processor that can save
 a file "as ASCII", that is, with no special format or styling commands.
 An editor such as STeno or MicroEmacs will do fine.  Each line of a batch
 file is processed separately, just as if it were entered on the keyboard
 in interactive mode.  There are a few important differences, however. The
 first is that there are some commands available only in batch files.  See
 "Batch files only" above for a list of these commands.  Comments can also
 be imbedded in batch files.  To include a comment in a batch file, use a
 # character.  When Tomshell sees a # it will disregard everything until
 it gets to the next line of the file.
   Batch files' filenames should end with .bat, .tom, or .btp (for
 NeoDesk users).  To execute a batch file, simply type its name.  You don't
 need to type the .bat (or whatever) at the end of it, but it won't do
 any harm.  When Tomshell is looking for programs matching a certain name
 (such as when you type "phroo"), priority will be given to batch files over
 program files (.prg, .tos, .ttp, .app).  This means that if you tell
 Tomshell to run "foo", and there is a "foo.bat" and a "foo.tos" in the
 current directory, Tomshell will run "foo.bat".
   When it is first run, Tomshell will look for a batch file called
 "tomshell.tom" or "tomshell.bat" and automatically execute it before
 entering interactive mode.  This is a good place to put some commonly used
 aliases and variable assignments, and possibly turn off the keyclick or
 something like that.  It's just like autoexec.bat in the Messydos world.
 
 .2 Errorlevels
 --------------
 An errorlevel (also called return code or status) is a number that
 has some particular meaning, specific to the program or batch file that
 returns it.  The negative errorlevels are usually reserved for errors
 relating to the operating system, such as -33, which means "file not
 found" and is well known to anyone using a command line interpreter for
 more than about five seconds.  Tomshell will look for negative errorlevels
 and output an appropriate message, if it has one.  Whether or not Tomshell
 finds a verbal message, it will output a "cmd exit code #" if the
 status after the last command is not zero.  Zero is returned when nothing
 of note has happened and everything is fine and dandy, so there is no
 need for any "warning" to this effect.
   Aside from the reserved gemdos/bios/xbios errorlevels, a number returned
 by a program can mean just about anything.  Some programs even return weird
 numbers like 2851, for no apparent reason.  Usually, however, programs will
 return a 0, unless an error occurs.  You can set up batch files and
 programs that return meaningful error codes not necessarily relating to
 errors.  For example, a BBS program may exit and return 8, which means that
 it's midnight and the "today's callers" file should be deleted, and maybe
 some other stuff.
   The errorlevel returned by the last command is kept in the status variable
 ($status).  If you don't want the verbal messages ("File not found"), set
 $verbosity to 1.  If you don't want the verbal messages _or_ the numeric
 messages, set $verbosity to 0.  The default for $verbosity is 2 (show
 both lines).
 
 .3 Filename completion
 ----------------------
 A very useful feature of TomShell, and one for which I got the inspiration
 and keys and so on from Gulam, is filename completion.  With this nifty
 doo-dad, you can get a list of all the files that start with what you've
 just typed.  This only works if the cursor is in the last position of
 the entered command line (at the very end).
 
 If the command line looks like this:
 d:\devpac > cp c:\bin\foobar\jam
         The cursor must be here ^ for filename completion to do anything.
 
   If you press Tab, Insert, or ^I (ASCII tab), TomShell will attempt to
 expand the partial filename you have typed as much as it can, which is
 until either there is more than one match or the complete filename has
 been completed.  For example, if you have the following files in the
 current directory:
 
  foobar
  fubar
  fooobar
  tomfile
 
 Pressing any of the abovementioned keys will accomplish the following:
 
  You type...                   TomShell turns into...
  f                             f
  fu                            fubar
  fo                            foo
  foo                           foo
  fooo                          fooobar
  foob                          foobar
  t                             tomfile
 
 If tomshell manages to fill in the complete filename, it will also add
 a space after it, which not only lets you know that the filename is complete,
 but readies the command line for another, separate, argument.
 
 If you use the Home key (or ^O), TomShell will first do everything mentioned
 above, but if it can't fill in the whole filename it will give you a
 list (in "ls" format) of all files that match the most specific pattern
 that it can derive.  The command line will then reappear with the text
 you entered before the ^O still intact.
 
 Try it, it's neat.  It's particularly handy for accessing files such as
 temporary files created by Arc: "a6238124.tmp" can be entered, in most
 cases, by typing "a6<tab>", which is considerably faster than typing
 in the whole filename yourself.
 
 .4 Modes of Operation
 ---------------------
 Tomshell has two modes of operation.  At any given time, it is either
 processing commands from a batch file or waiting for you to type commands
 directly into the shell and processing them as they are entered.  The
 second ("interactive") mode can be entered from the first ("batch") mode
 with the "interact" function.  To return to batch mode from interactive
 mode, give the "exit" command.  If you are in the "top" level (not within
 a batch file or interact command, which incidentally can also be used from
 the command line) and you issue the "exit" command, Tomshell will terminate
 and you will be returned to the desktop, or whatever you ran tomshell from.
 
 Batch files can be started up from within other batch files with no problem.
 Actually, there is a limit to how "deep" this can go, but it shouldn't get
 in your way.
 
 .5 Output devices
 -----------------
 There are a few special output devices that can be used with the
 redirection operators (> >> <) for various purposes.  The devices supported
 by Tomshell are:
 
 con:                   the console (screen)
 prn:                   the parallel port (printer)
 aux:                   the serial port (modem)
 
 Use these devices in place of filenames and output from commands (and
 properly written programs) will be output to them rather than the current
 output/input device (usually con:).
 
 .6 Running Programs
 -------------------
 If you type only the main filename of the program you want to run, the
 rest will be added automatically if a matching file is found.  If more
 than one executable (.bat, .btp, .tom, .prg, .tos, .ttp, .app) matches
 the given filename, priority is given to the first batch file in the
 directory listing as it is on the disk.  This is not always the first
 one displayed in a "dir" listing, but usually this shouldn't be a
 consideration.
 
 If the extension of the file is not given, and there is no executable
 match found in the current directory, the directories listed in the "PATH"
 variable (separated by commas) are searched in the order in which they
 appear in the list.  If the extension of the file _is_ given, and the
 file is not found in the current directory, the PATH directories will
 not be searched.
 
 .7 Variables
 ------------
 These are very important things for everything but the most basic of
 applications.  They are exactly what they sound like.  You can keep anything
 you want in a variable: numbers, text, symbols, whatever.  If you want to
 include reserved characters (such as > or ;) that would otherwise mess up
 Tomshell's operation, simply include them in "quotation marks".  At the
 moment, Tomshell has no math operators (even + and -) so you can't do much
 in the way of counting or things like that.  You can compare variables,
 input them from the user, display them, and so on.  The most notable
 variables are the reserved variables used by various parts of Tomshell
 (see _Special_variables_).
   To change the value of a variable, use the "set" command. For example,
 
 set foo bar
 
   will create the variable "foo" (or change it if it already exists) and
 set its value to "bar".  The reserved variables work the same way:
 
 set verbosity 1
 
   Some reserved variables are read-only (for obvious reasons), such as
 $disk (free space on the current drive) and $mem (largest block of free
 memory).
 
   You've probably noticed the $ in front of the variable names by now, and
 may not know why it's there.  All it does is tell Tomshell that the word
 immediately following it is the name of a variable and should be replaced
 with the contents of that variable.  For example, to echo (show) the free
 space on the current drive, type
 
 echo $disk
 
   This tells Tomshell to look for a variable called "disk" and echo the
 the contents of that variable rather than the word "disk".
 
   The $ is not required for the "set" command.  In fact, you can become
 quite confused if you start typing something like
 
 set $verbosity 2
 
   This might, for example, create a variable called "1" and set its value
 to "2".  This presumably isn't what you want.  If you want to copy the
 contents of variable a to variable b, type
 
 set b $a
 
   Note that the $ is used for the "a" variable.  This is because we want
 to set the variable "b" to _the_contents_of_ $a.  Typing the $a tells
 Tomshell to use the contents of the "a" variable.
 
 Enjoy.
 
 Tom Clegg
 e-mail contact at the NCAUG BBS, 613 737 1133, ...2400 bps
