			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
