SHELL V2.11  (C)Copyright 1986-88, Matthew Dillon, All Rights Reserved.
Freely distributable for non-profit only.

	    old users: Please read the version history at the bottom of
	    this document for changes and additions.


      (A)   Compiling
      (B)   Overview
      (C)   Quicky tech notes on implimentation.

      (D)   Command pre-processor
      (E)   Command-list
      (F)   special SET variables
      (G)   Version history

       See also EXAMPLES.TXT

			NEW FEATURES THIS VER

    (Taken from the history below):  an IPC implementation, ENV: variable
    support, many commands enhanced, some bugs fixed.

			    COMPILATION


    The SHELL will compile only under AZTEC C and requires my
    support library (SUP32.LIB) to link as well as a precompiled
    symbol table of all AMIGA .H files.  A Makefile is included.
    Note that the shell must be compiled using 32 bit integers (+L)
    option and linked with SUP32.LIB and C32.LIB.  Additionaly, my
    dres.library must be present in order to use the IPC facility.

    NOTE that converting the shell to use 16 bit integers does not
    make it significantly smaller or faster.  Do not waste your time.



			     OVERVIEW


    Matthew Dillon
    891 Regal Rd.
    Berkeley, California 94708
    USA

    ..!ucbvax!dillon
    dillon@ucbvax.Berkeley.EDU
    dillon@cory.Berkeley.EDU

    This is not a shareware program.  My basic philosophy is to write
    software for myself and distribute it if I think it will benefit
    others (that is, unless I start going broke).  Contribute if you want
    to.

    IT IS SUGGESTED THAT YOU USE CONMAN OR THE NEW 1.3 ENHANCED CONSOLE
    DEVICE.  CONMAN does to my shell what Steve did in his Manxfied (old
    term) 16 bit version of my shell, and more.  It isn't required, but
    CONMAN (shareware) complements the functionality of the shell quite
    well.


   PROBLEMS

   -Make sure you give the SHELL a big enough stack, especially if you
    intend on running shell scripts which source other scripts.  8192
    is suggested.  Remember, STACK must be run BEFORE you run the shell.
    Running it from the shell does not effect the shell's stack.

   -You should not redirect the RUN command. to redirect the command the
    RUN command is running, embed a standard CLI redirection in the command
    string:

    RUN ">file" command

   -Append '>>' does NOT work with BCPL programs.  It does work with all
    internal and non-bcpl (read C) programs.

   OVERVIEW of the major features:

   -History mechanism (complements conman quite nicely, in fact)
   -Redirection
   -Piping (sort of)
   -Command search path by name and by CLI path list
   -Aliases
   -Variables & variable handling (embedded variables), and enviroment variables
   -Automatic file name expansion via '?' and '*'
   -Conditionals
   -Shell Scripts
   -many built in commands to speed things up


			    COMMAND PREPROCESSOR


   preprocessing is done on the command line before it is passed on to
   an internal or external routine:

   ^c	    where c is a character is converted to that control character.
	    Thus, say '^l' for control-l.

   $name    where name is a variable name.  Variable names can consist of
	    0-9, a-z, A-Z, and underscore (_).  The contents of the
	    specified variable is used.  If the variable doesn't exist,
	    the specifier is used.  That is, if the variable 'i' contains
	    'charlie', then '$i' -> 'charlie'.  If the variable 'i' doesn't
	    exist, then '$i'->'$i' .

   ;	    delimits commands.	 echo charlie ; echo ben.

   ' '      (a space). Spaces delimit arguments.

   "string" a quoted string.  For instance, if you want to echo five spaces
	    and an 'a':

	    echo      a       -> a
	    echo "    a"      ->      a

   \c	    overide the meaning of special characters.	'\^a' is a
	    circumflex and an a rather than control-a.	To get a backslash,
	    you must say '\\'.

	    also used to overide alias searching for commands.

   >file    specify output redirection.  All output from the command is
	    placed in the specified file.

   >>file   specify append redirection (Does not work with BCPL programs).

   <file    specify input redirection.	The command takes input from the
	    file rather than the keyboard (note: not all commands require
	    input).  It makes no sense to say  'echo <charlie' since
	    the 'echo' command only outputs its arguments.

   |	    PIPE specifier.  The output from the command on the left becomes
	    the input to the command on the right.  The current SHELL
	    implimentation uses temporary files to store the data.

   !!	    execute the previously executed command.
   !nn	    (nn is a number).  Insert the history command numbered n (see
	    the HISTORY command)
   !partial search backwards through the history list for a command which
	    looks the same as 'partial', and execute it.

   #	    Enter comment.  The rest of the line is discarded (note: \#
	    will, of course, overide the comment character's special
	    meaning)

   ^search^replace
	    a '^' at the beginning of the line indicates history
	    replacement.  The first occurance of 'search' in the previous
	    command is changed to 'replace', and the command executed.



			     SHELL COMMANDS


   The first argument is the command-name... if it doesn't exist in the
   list below and isn't an alias, it is assumed to be an external (disk)
   command.

   AUTOMATIC SOURCING may be accomplished by naming shell scripts with a
   .sh suffix.	Thus, if you say 'stuff' and the file 'stuff.sh' exists in
   your current or C: directory, it will be SOURCED with any arguments you
   have placed in the $_passed variable.

			  EXCEPTION_PROCESSING

      if no _except variable exists, any command which fails causes the
      rest of the line to abort as if an ABORTLINE had been executed.  If
      the _except variable exists, it is of the form:

      "nnn;commands..."

      where nnn is some value representing the minimum return code required
      to cause an error.  Whenever a command returns a code which is
      larger or equal to nnn, the commands in _except are executed before
      anything.  WHEN _except EXISTS, THE COMMAND LINE DOES NOT ABORT
      AUTOMATICALLY.  Thus, if you want the current line being executed
      to be aborted, the last command in _except should be an "abortline".

      exception handling is disabled while in the exception handling routine
      (thus you can't get into any infinite loops this way).

      Thus if _except = ";", return codes are completely ignored.

      example:

      set _except "20;abortline"


   ABORTLINE

      or just 'abort'.  Causes the rest of the line to be aborted. Used in
      conjunction with exception handling.

      % echo a;abort;echo b
      a


   HELP

      simply displays all the available commands.  The commands are
      displayed in search-order.  That is, if you give a partial name
      the first command that matches that name in this list is the one
      executed.  Generally, you should specify enough of a command so that
      it is completely unique.

   QUIT
   EXIT
   RETURN [n]

      quit my SHELL (awww!).  End, El-Zappo, Kapow. Done, Finis.  If you
      use RETURN and are on the top source level, the shell exits with the
      optional return code.  (see RETURN below)


   SET
   SET name
   SET name string

      The first method lists all current variable settings.
      The second method lists the setting for that particular variable,
      or creates the variable if it doesn't exist (to "")
      The last method sets a variable to a string.

      see the section on special _ variables down below


   UNSET name name name....

      unset one or more variables.  Deletes them entirely.


   SETENV name string

      Create/Modify an enviroment variable.  The enviroment is maintained
      in ENV:, with a separate file for each enviroment variable.  This
      should be assigned to a directory somewhere.

   UNSETENV name name name....

      remove the specified variables from the enviroment list.	This
      call DeleteFile()'s the enviroment variable from ENV:

   PRINTENV

      Print the contents of the enviroment directory ENV:

   ALIAS
   ALIAS name
   ALIAS name string

      same as SET, but applies to the alias list.  You can alias a single
      name to a set of commands.  For instance:

      alias hi "echo a; echo b"

      then you can simply say 'hi'.  Aliases come in two forms the second
      form allows you to place the arguments after an alias in a variable
      for retrieval:

      alias xxx "%i echo this $i is a test"

      % xxx charlie
      this charlie is a test

      The rest of the command line is placed in the specified variable
      for the duration of the alias.  This is especially useful when used
      in conjunction with the 'FOREACH' command.


   UNALIAS name name name...

      delete aliases..


   ECHO string
   ECHO -n string

      echo the string to the screen.  If '-n' is specified, no newline is
      output.


   STRHEAD  varname breakchar string

      remove everything after and including the breakchar in 'string' and
      place in variable 'varname':

	 % strhead j . aaa.bbb
	 % echo $j
	 aaa
	 %


   STRTAIL  varname breakchar string

      remove everything before and including the breakchar in 'string' and
      place in variable 'varname':

	 % strtail j . aaa.bbb
	 % echo $j
	 bbb
	 %


   SOURCE file [arguments]

      execute commands from a file.  You can create SHELL programs in
      a file and then execute them with this command.  Source'd files
      have the added advantage that you can have loops in your command
      files (see GOTO and LABEL).  You can pass SOURCE files arguments
      by specifying arguments after the file name.  Arguments are passed
      via the _passed variable (as a single string).

      Automatic 'sourcing' is accomplished by placing a .sh extension on
      the file and executing it as you would a C program:

      --------- file hello.sh ---------
      foreach i ( $_passed ) "echo yo $i"
      ---------------------------------
      % hello a b c
      yo a
      yo b
      yo c

      NOTE: The hash '#' as the FIRST character on the line is a comment
	    within script files.

   MV from to
   MV from from from ... from todir

      Allows you to rename a file or move it around within a disk.  Allows
      you to move 1 or more files into a single directory.  (if todir == '/',
      the items are moved to the parent directory).

   CD
   CD ..
   CD path

      Change your current working directory.  You may specify '..' to go
      back one directory (this is a CD specific feature, and does not
      work with normal path specifications).  Note that CD / also goes
      back one directory.

      CD without any arguments displays the path of the directory you
      are currently in.


   PWD
      rebuild _cwd by backtracing from your current directory.	The $_cwd
      variable can get confused by Assign'd labels.

   RM [-r] file file file...

      DeleteFile().  Remove the specified files.  Remove always returns
      errorcode 0.  You can remove empty directories.  The '-r' option
      will remove non-empty directories by recursively removing all sub
      directories.

   CP file	(to current directory)
   CP [-r] dir	(to current directory)
   CP file file
   CP file1 file2...fileN dir
   CP [-r] dir1 dir2...dirN dir

      copy files or directories.  when copying directories, the "-r" option
      must be specified to copy subdirectories as well.  Otherwise, only
      top level files in the source directory are copied.


   MKDIR name name name...

      create the following directories.


   HISTORY [partial_string]

      Displays the enumerated history list.  The size of the list is
      controlled by the _history variable.  If you specify a partial-
      string, only those entries matching that string are displayed.


   MEM

      Display current memory statistics for CHIP and FAST memory.


   CAT [file file....]

      Type the specified files onto the screen.  If no file is specified,
      STDIN in used.  CAT is meant to output text files only.  You cannot
      use CAT to join binaries together.

   DIR [-s] [path path ... ]

      Get a directory listing of the current directory or specified
      directories.  The -s option causes DIR to display a short-form
      listing.

   DEVINFO [device: device:... ]

      Display Device statistics for the current device (CD base), or
      specified devices.


   FOREACH varname ( strings ) command

      'strings' ied.

[label] IF	    exp

	    Is TRUE if the expression result is defined AND non-zero.
	    Is FALSE if the expression result is defined AND zero.
	    Neither IF or ELSE will be executed if the expression result
	    is undefined.  If the expression is undefined, another assembly
	    pass is automatically taken.

[label] ELSE

	    ELSE the current IF.

[label] ENDIF
[label] EIF

	    Terminate an IF. ENDIF and EIF are equivalent.

[label] REPEAT	    exp
[label] REPEND

	    Repeat code between REPEAT/REPEND 'exp' times.  if exp == 0,
	    the code repeats forever.  exp is evaluated once.

		Y   SET     0
		    REPEAT  10
		X   SET     0
		    REPEAT  10
		    DC	    X,Y
		X   SET     X + 1
		    REPEND
		Y   SET     Y + 1
		    REPEND

	    generates an output table:	0,0 1,0 2,0 ... 9,0  0,1 1,1 2,1
	    ... 9,1, etc...

	    Labels within a REPEAT/REPEND should be temporary labels with a
	    SUBROUTINE pseudoop to keep them unique.

	    The Label to the left of REPEND is assigned AFTER the loop
	    FINISHES.


[label] XXX[.force] operand

	    XXX is some mnemonic, not necessarily three characters long.
	    The .FORCE optional extension is used to force specific
	    addressing modes (see below).

GENERAL:

    The label will be set to the current ORG/RORG either before or after
    a pseudo-op is executed.  Most of the time, the label to the left of a
    pseudo-op is the current ORG/RORG. The following pseudo-op's labels are
    created AFTER execution of the pseudo-op:

	SEG, ORG, RORG, REND, ALIGN

EXTENSIONS:

    FORCE extensions are used to force an addressing mode.  In some cases,
    you can optimize the assembly to take fewer passes by telling it the
    addressing mode.  Force extensions are also used with DS,DC, and DV
    to determine the element size.  NOT ALL EXTENSIONS APPLY TO ALL
    PROCESSORS!

	example:    lda.z   charlie

	i   -implied
	ind -indirect word
	0   -implied
	0x  -implied indexing (0,x)
	0y  -implied indexing (0,y)
	b   -byte address
	bx  -byte address indexed x
	by  -byte address indexed y
	w   -word address
	wx  -word address indexed x
	wy  -word address indexed y
	l   -longword (4 bytes) (DS/DC/DV)
	r   -relative
	u   -uninitialized (SEG)

	First character equivalent substitutions:

	b z d	    (byte, zeropage, direct)
	w e a	    (word, extended, absolute)


ASSEMBLER PASSES:
    The assembler may have to make several passes through the source
    code to resolve all generation.  The number of passes is not
    limited to two.  Since this may result in an unexpected, verbose
    option 2, 3, and 4 have been provided to allow determination of the
    cause. The assembler will give up if it thinks it can't do the
    assembly in *any* number of passes.

    Error reporting could be better....


EXPRESSIONS:
	[] may be used to group expressions.  The precedense of operators
	is the same as for the C language in almost all respects.  Use
	brackets [] when you are unsure.  The reason () cannot be used to
	group expressions is due to a conflict with the 6502 and other
	assembly languages.

	Some operators, such as ||, can return a resolved value even if
	one of the expressions is not resolved.   Operators are as follows:

	NOTE WELL!  Some operations will result in non-byte values when a
	byte value was wanted.	For example:	~1  is NOT $FF, but
	$FFFFFFFF.  Preceding it with a < (take LSB of) will solve the
	problem.  ALL ARITHMETIC IS CARRIED OUT IN 32 BITS.  The final
	Result will be automatically truncated to the maximum handleable
	by the particular machine language (usually a word) when applied
	to standard mnemonics.

	prec	    UNARY

	20  ~exp    one's complement.
	20  -exp    negation
	20  !exp    not expression (returns 0 if exp non-zero, 1 if exp zero)
	20  <exp    take LSB byte of a 16 bit expression
	20  >exp    take MSB byte of an expression

		    BINARY

	19  *	    multiplication
	19  /	    division
	19  %	    mod
	18  +	    addition
	18  -	    subtraction
	17  >>,<<   shift right, shift left
	16  >,>=    greater, greater equal
	16  <,<=    smaller, smaller equal
	15  ==	    equal to.  Try to use this instead of =
	15  =	    exactly the same as == (exists compatibility)
	15  !=	    not equal to
	14  &	    logical and
	13  ^	    logical xor
	12  |	    logical or
	11  &&	    left expression is true AND right expression is true
	10  ||	    left expression is true OR right expression is true
	 9  ?	    if left expression is true, result is right expression,
		    else result is 0.	[10 ? 20] returns 20
	 8  []	    group expressions
	 7  ,	    separate expressions in list (also used in
		    addressing mode resolution, BE CAREFUL!

    Constants:

	nnn	decimal
	0nnn	octal
	%nnn	binary
	$nnn	hex
	'c      character
	"cc.."  string (NOT zero terminated if in DC/DS/DV)
	[exp]d	the constant expressions is evaluated and it's decimal
		result turned into an ascii string.

    Symbols:

	...	-holds CHECKSUM so far (of actual-generated stuff)
	..	-holds evaluated value in DV pseudo op
	.name	-represents a temporary symbol name.  Temporary symbols
		 may be reused inside MACROS and between SUBROUTINES, but
		 may not be referenced across macros or across SUBROUTINEs.
	.	-current program counter (as of the beginning of the
		 instruction).
	name	-beginning with an alpha character and containing letters,
		 numbers, or '_'.  Represents some global symbol name.


WHY codes:
    Each bit in the WHY word (verbose option 1) is a reason (why
    the assembler needs to do another pass), as follows:

    bit 0   expression in mnemonic not resolved
	1   -
	2   expression in a DC not resolved
	3   expression in a DV not resolved (probably in DV's EQM symbol)
	4   expression in a DV not resolved (could be in DV's EQM symbol)
	5   expression in a DS not resolved
	6   expression in an ALIGN not resolved
	7   ALIGN: Relocatable origin not known (if in RORG at the time)
	8   ALIGN: Normal origin not known	(if in ORG at the time)
	9   EQU:   expression not resolved
	10  EQU:   value mismatch from previous pass (phase error)
	11  IF:     expression not resolved
	12  REPEAT: expression not resolved

	13  a program label has been defined after it has been
	    referenced (forward reference) and thus we need another
	    pass
	14  a program label's value is different from that of the
	    previous pass (phase error)

    Certain errors will cause the assembly to abort immediately, others
    will wait until the current pass is other.	The remaining allow another
    pass to occur in the hopes the error will fix itself.


VERSIONS:

    V2.11
	-Fixed <exp >exp bug, <exp now means LSB, >exp MSB (it used to
	 be reversed).
	-Fixed many bugs in macros and other things
	-Added automatic checksumming ... no more doing checksums manually!
	-Added several new processors, including 6502.
	-Source is now 16/32 bit int compatible, and will compile on an
	 IBM-PC (the ultimate portability test)

    V2.01

	-can now have REPEAT/REPEND's within macros
	-fill field for DS.W is a word (used to be a byte fill)
	-fill field for DS.L is a long (used to be a byte fill)


ff ¤e file saves by crunching spaces to tabs.
		     The default is OFF.
    SET var str     -create/modify an internal variable
    SETENV var str  -create/modify an enviroment variable (1.3 ENV:)
    SWAPMARK	    -PUSHMARK, swap top two marks on stack, POPMARK
    SCANF ctlstr    -scan the string at the current text position (C scanf)
		     example:	(scanf %s)          SEE BELOW
    SCREENBOTTOM    -Move cursor to the bottom of the screen.
    SCREENTOP	    -Move cursor to the top of the screen
    SCROLLUP	    -Scroll up without moving cursor
    SCROLLDOWN	    -Scroll down without moving cursor
    SETFONT font sz -Set the window's font.  ex:   (setfont topaz.font 11)
    SETTOGGLE N     -set toggle array entry N  (0..255)
    SOURCE file     -source a script file. '#' in first column for comment
    SPLIT	    -Split line at cursor
    TAB 	    -forward tab
    TABSTOP N	    -Set tab stops every N.  does not effect text load
    TLATE [+/-]N    -translate character by +N or -N, or set character
		     to exactly N if no + or -. (e.g. TLATE +65 TLATE 3)
    TMPHEIGHT N     -set window height for next window only, pixels
    TMPWIDTH  N     -set window width for next window only,  pixels
    TOGGLE N	    -flip toggle array entry N (0..255)  (See IF)
    TOMOUSE	    -moves cursor to mouse position
    TOP 	    -Move to Top of File
    TOPEDGE N	    -set topedge in the screen in PIXELS for any new window
    UNBLOCK	    -clear the block markers for the current window
    UNDO	    -undo current line (must be mapped to a key to work)
    UNMAP key	    -unmap a key
    UP		    -cursor up
    UNSET var	    -delete an internal variable