Relay-Version: version B 2.10 5/3/83; site utzoo.UUCP
Path: utzoo!mnetor!seismo!lll-lcc!ames!ucbcad!ucbvax!CORY.BERKELEY.EDU!dillon
From: dillon@CORY.BERKELEY.EDU (Matt Dillon)
Newsgroups: comp.sys.amiga
Subject: SHELL 2.04 	PART 2 of 4 (instructions, examples)
Message-ID: <8701030935.AA22551@cory.Berkeley.EDU>
Date: Sat, 3-Jan-87 04:35:25 EST
Article-I.D.: cory.8701030935.AA22551
Posted: Sat Jan  3 04:35:25 1987
Date-Received: Sat, 3-Jan-87 07:36:47 EST
Sender: daemon@ucbvax.BERKELEY.EDU
Organization: University of California at Berkeley
Lines: 721


#! /bin/sh
# This is a shell archive, meaning:
# 1. Remove everything above the #! /bin/sh line.
# 2. Save the resulting text in a file.
# 3. Execute the file with /bin/sh (not csh) to create:
#	doc.txt
#	examples.txt
# This archive created: Sat Jan  3 00:58:57 1987
export PATH; PATH=/bin:/usr/bin:$PATH
echo shar: "extracting 'doc.txt'" '(19307 characters)'
if test -f 'doc.txt'
then
	echo shar: "will not over-write existing file 'doc.txt'"
else
cat << \!Funky!Stuff! > 'doc.txt'

SHELL V2.04. (C)Copyright 1986, Matthew Dillon, All Rights Reserved.
You may distribute this program for non-profit only.


INSTRUCTIONS FOR SHELL V2.04

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

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

      (G)   example .login file.


(A) COMPILING:

   NOTE: An executable is provided as compilation instructions are
   difficult AND because there is a good change this version will not
   compile correctly using Manx.  For you Manx hackers: Beware the
   C/Assembly interface when you convert.  There is also a good chance
   you will not have the latest version of MY.LIB.  Also for you Manx
   hackers, you must use the +l option for 32 bit ints.

   This version of my shell MUST be compiled with Lattice. You must use
   the Provided Startup Module rather than Lstartup.obj or Astartup.obj.
   The startup module is equivalent to Astartup.obj except that I have added
   a little code at the beginning to save the BCPL startup state.

   Link using the provided startup module and the following libraries in
   this order:

      MY.LIB AMIGA.LIB LC.LIB

   MY.LIB is my own library which has been posted (but feel free to ask
   me to send it to you if you haven't got it).

   lc1 -i$incdir/ -i$incdir/lattice/ $y
   lc2 -s -v $y

      where $incdir is the include directory for C, and '$y' stands for
      each .C file.  At this point you have nothing but object modules and
      must now link them together:

      NOTE: you MUST use the LC2 options.


   a/blink c.o+main.o+...+run.o library $libdir/my.lib+$libdir/amiga.lib+$libs+$libdir/lc.lib to ram:shell

      NOTE: c.o is provided, do not use standard startups (I said this
      above)


   Executable Size should be around 34K.


(B) OVERVIEW:

   PROBLEMS

   -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 programs.

   OVERVIEW of the major features:

   -simple history
   -redirection
   -piping
   -command search path 
   -aliases
   -variables & variable handling (embedded variables)
   -file name expansion via '?' and '*'
   -conditionals
   -source files  (w/ gotos and labels)
   -many built in commands to speed things up

   NEW FEATURES IN 2.04:
      - CP command now internal... see instructions.
      - RM command now has '-r' option.
      - \command forces the command parser NOT to look at aliases.  Thus,
       you can alias something like 'cd' and have the alias contain a 'cd'
       which references the internal cd:

       alias cd "stuff...;\\cd $x"

      - "-c" command line option to execute commands and return.
       shell -c "echo a;echo b;echo c".
      -_path default now places RAM: and RAM:C first rather than last.
      -_histnum variable .. current history #
      -expanded filenames are sorted.
      -^search^replace (modify previous command).

   NEW FEATURES IN 2.03.  Thanks to Steve Drew who suggested a '_path'
   variable.  The other difference with this version is that BCPL
   output redirection works properly.  Additionaly, alias loops are
   detected (this is what is known as a hack).

   NEW FEATURES IN 2.02.  I would like to thank Dave Wecker and Steve Drew
   for their numerous comments on the previous version of my shell.

   -Return code and error handling
      (A) retrieve return code
      (B) Manual or Automatic error handling.
   -Control C-F now passed to external commands.
   -can execute shell scripts as if they were normal commands (w/ arguments)
    (see down below)
   -C:RUN no longer required.  ext Command loading is faster
   -BCPL programs which change the CLI state (CD/PATH...) now work with
    the shell.  However, the CLI PATH is not used currently.
   -MV command embellished... can now specify multiple files with a
    directory as the destination.
   -'-l' option for DIR
   -CD re-written, new variable $_cwd. startup directory figured out.
   -wildcard expansion no longer cares about case.
   -Comment character '#'
   -EXIT as an alternate to QUIT

   Additional Commands:
      abortline
      forever

   Additional SET variables (see documentation below)
      _cwd           current directory (see CD below)
      _maxerr        worst return value to date
      _lasterr       return value from last command (internal or external)
      _except        contains error level AND exception code. "nnn;command"
                     (see ABORTLINE, and start of section E)

      _passed        contains passed command line to source files
      _path          contains search path (example:  "c:,df1:c/,df0:c/"


(C) QUICK TECH NOTES:

   PIPES have been implimented using temporary RAM: files.  Thus, you
   should be careful when specifying a 'ram:*' expansion as it might
   include the temp. files.  These files are deleted on completion of
   the pipe segment.

   The file names used are completely unique, even with multiple shell
   running simultaniously.

   My favorite new feature is the fact that you can now redirect to and
   from, and pipe internal commands.  'echo charlie >ram:x', for
   instance.  Another favorite:

      echo "echo mem | shell" | shell

   To accomplish these new features, I completely re-wrote the command
   parser in execom.c

   The BCPL 'RUN' command should not be redirected.. .strange things
   happen.

   NO BCPL program should be output-append redirected (>>).


(D)   Command pre-processor

   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).

   , =, and combinations (wire or).  Thus <> is not-equal, >=
      larger or equal, etc...

      If the left argument is numeric, both arguments are treated as
      numeric.

      usually the argument is either a constant or a variable ($varname).

      The second form if IF is conditional on the existance of the argument.
      If the argument is a "" string, then false , else TRUE.


   ELSE ;

      else clause.


   ENDIF ;

      the end of an if statement.


   LABEL name

      create a program label right here.


   GOTO label

      goto the specified label name.  You can only use this command from a
      source file.


   DEC var
   INC var

      decrement or increment the numerical equivalent of the variable and
      place the ascii-string result back into that variable.


   INPUT varname

      input from STDIN (or a redirection, or a pipe) to a variable.  The
      next input line is placed in the variable.


   VER

      display my name and the version number.


   SLEEP timeout

      Sleep for 'timeout' seconds.



(F) SPECIAL SET VARIABLES

   _prompt
         This variable is set to the command you wish executed that will
         create your prompt.

   _history
         This variable is set to a numerical value, and specifies how far
         back your history should extend.

   _debug
         Debug mode... use it if you dare.  must be set to some value

   _verbose
         Verbose mode (for source files).  display commands as they are
         executed.

   _maxerr
         The worst (highest) return value to date.  To use this, you usually
         set it to '0', then do some set of commands, then check it.  

   _lasterr
         Return code of last command executed.  This includes internal
         commands as well as external comands, so to use this variables
         you must check it IMMEDIATELY after the command in question.

   _cwd
         Holds a string representing the current directory we are in from
         root.  The SHELL can get confused as to its current directory if
         some external program changes the directory.  Use PWD to rebuild
         the _cwd variable in these cases.

   _passed
         This variable contains the passed arguments when you SOURCE a file
         or execute a .sh file.  For instance:

         test a b c d

         -------- file test.sh ----------
         echo $_passed
         foreach i ( $_passed ) "echo YO $i"
         --------------------------------


   _path
         This variable contains the search path when the shell is looking
         for external commands.  The format is:  DIR,DIR,DIR  Each DIR must
         have a trailing ':' or '/'.  The current directory is always
         searched first.  The entire path will be searched first for the
         , then for .sh (automatic shell script sourcing).

         The default _path is set to  "c:,df1:c/,df0:c/,ram:,ram:c/"



(G) EXAMPLE .login file.

   from a CLI or the startup-script say 'SHELL filename'.  That file
   is sourced first.  thus, 'SHELL .login' will set up your favorite
   aliases:

   ------------------------------ example .login source file ----------

echo "shells, Matt"
alias l     "%var if $var;echo $var;else;echo *;endif"
alias c     "echo ^l"
alias cc    "cd ram:;assign c: cb:c"
alias wb    "cd ram:;assign c: sys:c"
alias ed    "run ED"
set dest ram:a
set temp ram:
set ld cb:clib
set incdir cb:include
set libs +$ld/lc.lib
set ops  ""

   --------------------------------------------------------------------


!Funky!Stuff!
fi  # end of overwriting check
echo shar: "extracting 'examples.txt'" '(1870 characters)'
if test -f 'examples.txt'
then
	echo shar: "will not over-write existing file 'examples.txt'"
else
cat << \!Funky!Stuff! > 'examples.txt'
EXAMPLE FILES

------------------------------------------------------------------------
EXAMPLE INTERNAL COMMAND OVERIDING
------------------------------------------------------------------------

#Make CD not only do it's normal function, but also a PWD.

alias cd "%var \\cd $var;pwd"

------------------------------------------------------------------------
.LOGIN
------------------------------------------------------------------------

echo "shells, Matt"
alias l     "%var if $var;echo $var;else;echo *;endif"
alias c     "echo ^l"
alias cc    "cd ram:;assign c: cb:c"
alias wb    "cd ram:;assign c: sys:c"
alias ed    "run ED"
set dest ram:a
set temp ram:
set ld cb:clib
set incdir cb:include
set libs +$ld/lc.lib
set ops  ""


------------------------------------------------------------------------
RAM.SH
------------------------------------------------------------------------
cp c:run ram:; cp c:assign ram:; cp c:cp ram:; assign c: ram:


------------------------------------------------------------------------
C1.SH
------------------------------------------------------------------------
foreach y ( $_passed ) "echo $y;lc1 -o$temp -i$incdir/ -i$incdir/lattice/ $y";echo DONE


------------------------------------------------------------------------
C2.SH
------------------------------------------------------------------------
foreach y ( $_passed ) "echo $y;lc2 -s -v $temp$y";echo DONE


------------------------------------------------------------------------
LD.SH
------------------------------------------------------------------------
blink $ld/lstartup.obj+$_passed library $ld/lc.lib+$ld/amiga.lib $ops to $dest


------------------------------------------------------------------------
LDALL.SH
------------------------------------------------------------------------
set O "";foreach y ( *.o ) "set O $O+$y";strtail O + $O
ld $O;unset O


!Funky!Stuff!
fi  # end of overwriting check
exit 0
#	End of shell archive