Frozen Fish 1: Amiga/FrozenFish-Apr94.iso/bbs/alib/d8xx/d811/bsh.lha/bsh/bsh.doc

Text File | 1993-02-14 | 87KB | 2,301 lines

                        CONTENTS


        (0)     Features
        (1)     Command pre-processor (parser)
        (2)     Command-line editing
        (3)     Command-list
        (4)     Variables
        (5)     Expressions
        (6)     Redirection and pipes
        (7)     Programming
        (8)     Directory aliases
        (9)     Problems


    Bsh is an enhanced shell and interpretive programming language.  It
    contains many advanced features not previously seen in shells on
    the Amiga(TM) computer.  Bsh has been tested on an Amiga 3000
    running AmigaDOS1.3, AmigaDOS2.04 and AmigaDOS2.1, on an Amiga
    1000 running AmigaDOS1.2 and AmigaDOS1.3, and on an Amiga 500
    running AmigaDOS2.04.


                        MAJOR FEATURES

   o Command history.  Bsh remembers commands that you typed in a
     history buffer; you can subsequently recall (and modify) these
     commands using the command-line editing features described in
     chapter 2.
   o Command line editing (see chap. 2)
   o Command substitution.  This allows you to place the output of one
     command in the command-line of another.  See the IFS variable in
     chapter 4.
   o Redirection and piping (see chap. 6)
   o Concurrent piping for external commands
   o Here documents
   o Command aliases
   o File name completion using wildcards ('*', '?')
   o Pattern permutations ({str1,str2}{str3,str4}...).  Each possible
     permutation becomes a separate argument for the command.  For
     example, to rename MyFunkyOldSourceFile.bak to
     MyFunkyOldSourceFile.c:
        % mv MyFunkyOldSourceFile.{bak,c}
     This is not a wild-card operation, but it can be combined with
     regular wildcards.  For example, to remove all files ending in
     .bak or .o:
        % rm *.{bak,o}
   o Variables, array variables and environment variables (see chap. 4)
   o Expression evaluation using constants, bsh variables, arithmetic
     operators and functions (see chap. 5)
   o bsh scripts
   o Conditionals (IF, ELSEIF, ELSE, ENDIF)
   o Looping (WHILE, ENDWHILE, CONTINUE, BREAK, GOTO)
   o More than 50 builtin commands (see chap. 3)
   o More than 40 builtin functions (see chap. 5)
   o Command search by CLI path and by bsh path variable
   o Directory aliases (see chap. 8).  Short abbreviations for the
     current dirctory the parent of the current dirctory and the home
     directory which can save lots of typing


                        New features in bsh 0.95

   o Bsh is separated into a shared library containing most of the
     code, and a very small command which just opens the library and
     calls the main() entry point in it.  This allows multiple shells
     to be running without multiple copies of the code segment in
     memory at a time.


                        New features in bsh 0.96

   o Command hashing.  When bsh finds a command in your search-path,
     it remembers the location so that the next time you use the
     command, it loads the command from the remembered location instead
     of searching the path again.  This can significantly reduce the
     number of disk accesses depending on the number of directories in
     your search path.  The hash list can be manipulated using the HASH,
     UNHASH, REHASH commands.
   o Separate command newbsh creates a new shell in its own console
     window.


                        New features in bsh 0.97

   o Resident command loading.  Allows pure, and pseudo-pure (linked
     with LATTICE cres.o) commands to be made resident.
   o Redirection of standard error file.  Stderr redirection of external
     (disk-based) commands requires AmigaDOS 2.0 to work.
   o Bsh has been recompiled with Manx 5.0d using prototyping.
   o WorkBench startup via newbsh (a tool icon is provided).  Newbsh
     can also be started by clicking on a script icon.


                        New features in bsh 0.98

   o Variable exporting, bsh variables can be EXPORTed to sub-shells.
   o Window manipulations with the window command.
   o Bsh and newbsh have been made RESIDENTable.
   o Bsh has been recompiled with Manx 5.2a.


                        New features to be included in bsh 1.0

   o Command grouping.  Commands may be grouped by placing a list of
     commands within parentheses which may also contain a pipeline.
     Also it is now possible to run a single command or command group
     in the background or pipe the output of a group of commands into
     another command.
        % cmd &              run command cmd in the background
        % cmd1 & cmd2        run cmd1 in the background while running
                             cmd2
        % (cmd1;cmd2) | cmd3 pipe output from group to input of cmd3
     Command groups, and background commands are run in a separate
     shell (bsh must be in your search path).  This feature also allows
     concurrent piping of script programs - they are run in a separate
     shell.
     The command-grouping feature is not included in version 0.98.
     This will be included with bsh 1.0.
   o User definable functions (really resident scripts).
   o A match() function which will compare a string with a pattern and
     return true if the string matches the pattern.
   o Some simple form of job control (at least the ability to stop
     runaway or catatonic programs and recover the use of the shell).


                        In the future...

     Also in the planning stage, an AppWindow feature which would
     allow scripts to be run by just dropping their icons into a
     bsh AppWindow, and an ARexx port.
   1-0                     THE COMMAND LINE

    Before passing a command line on to a program, bsh performs an initial
    editing (parsing) pass. First any history substitution is performed.
    Next, if the command line contains multiple commands or command groups,
    each is extracted and treated as a separate command line.  Then alias
    and variable substitution is performed. Next, wildcard expansion is
    performed with each matching file found occupying one argument position
    on the command line.  Finally, redirection files are opened, and the
    redirection operators ( <, > ) and redirection file names are removed
    from the command line: the program being run never sees them.  Any of
    the special characters recognized by the command parser can of course
    be protected from their normal interpretation by quoting them.



    1-1                     HISTORY REPLACEMENT

    See also the HISTORY command in chapter 3.

    !!      At the beginning of a line, causes the previous
            command to be re-executed.

    !string Causes the most recently entered command starting with
            string to be re-executed.  See the HISTORY command.

    !n      Causes the nth command to be re-executed.

    !-n     Causes the n+1th previous command to be re-executed.
            Using this, you can toggle repeatedly between two
            commands:
                % cmd1
                % cmd2
                % !-1           re-executes cmd1
                % !-1           re-executes cmd2
            To make things even easier, you could assign the string
            "!-1\r" to the variable f2, and then just keep poking
            the f2 function key until done.


    1-2                         SEPARATORS

    ' '     A space; used as an argument separator.  In order to
            include a space within an argument, you must quote it
            (see below).

    ;       Is used as a command separator.

                % cd foo ; ls

    #       Enter a comment.  The rest of the line is ignored if it
            is immediately followed by a tab or space.

                % foo bar # this command does something

    |       The pipe operator (see below under redirection).

    &       Is used as a command separator.  The command on the left
            is run in the background; the command to the right is then
            run without waiting for the first command to complete.
            This requires the command grouping feature, not included in
            version 0.98 of bsh.  You can also run a single command in
            the background by appending an & to the command.

                % foo & bar     Start foo in the background, then
                                run bar without waiting for foo.
                % foo &         Start foo in the background, bsh
                                returns to the prompt immediately.


    (cmd...) Run a group of commands in a separate shell.  This requires
            the command grouping feature, not included in version 0.98
            of bsh.


    1-3                         QUOTING

    'string'
    "string" a quoted string.  For example, to set a variable to a string
            containing spaces:

                % set a "b     c"
                % echo $a
                b     c
                % set a b     c
                % echo $a
                b c

            Within double quotes, variables are still substituted but not
            within single quotes.  Command substitution (`cmd`) also still
            occurs within double quotes but not within single quotes.

                % echo '$a'
                $a
                % echo "$a"
                b c

    \c      Protects a special character from normal interpretation;
            \* is an asterisk rather than all the files in the current
            directory.  To enter a backslash, just type "\\".  This is
            also used to prevent alias substitution for a command.
            Within double quotes, the backslash can also be used to enter
            escape characters as follows:
                \a      a bell - ^G (control-G)
                \b      a backspace (control-H)
                \e      an escape (control-[)
                \f      a form feed (control-L)
                \n      a newline character (control-J)
                \r      a carriage return (control-M)
                \t      a tab (control-I)
                \nnn    one to three octal digits representing an ascii
                        character of that value.

    `cmd`   Command substitution - execute command cmd and place its
            output on the command line.  Each word of output from cmd
            is a  separate argument for the command.  Words are delimited
            according to the characters in the IFS variable (see chap. 4).
            If IFS is undefined, words are delimited by space, tab, or
            a newline.  This is a way for one command's output to become
            anothers arguments.  For example, add all files in the current
            directory and all subdirectories to the zoo archive foo.zoo.

                % zoo a foo.zoo `find . -type f -print`

            You could even be a little more selective about it by piping
            the output of find through pick:

                % zoo a foo.zoo `find . -type f -print | pick`

            If the variable IFS has been defined, it contains a list of
            the characters used to delimit words.  If you use 'find' to
            generate a list of filenames, and the names might contain
            spaces or tabs, you set IFS:

                set IFS "\n"

            and each line of output from 'find' is treated as one word.

            Command substitution occurs within double quotes, but not
            within single quotes.


    1-4                 REDIRECTION OPERATORS

    See also chapter 6 for more information on redirection and pipes.

    >file   Redirect output from command.  Output from the command is
            directed to the named file.
    >>file  append output to end of the named file.

    2>file  Redirect standard error.  Redirection of standard error
            for external (disk based) commands requires AmigaDOS
            version 2.0, and cooperative utilities to work.
    2>>file append error file.

    <file   redirect standard input.  The command takes input from the
            named file rather than the console.

    <<string here-document: lines following this line in a script file
            until a line beginning with <string> are read as
            standard-input by the command.

    |       Is the pipe operator (also a command separator).  The
            output from the first command becomes the input to the
            second command.  See chapter 6 for more info on pipes.
            You can string out several commands this way, forming a
            "pipeline", each command after the first takes its input
            from the output of the previous command.  Each command
            except the last is considered a pipe-feeder.

                % cmd1 | cmd2   Standard-output of cmd1 is
                                connected (piped) to standard-
                                input of cmd2.

    Redirection operators are not recognized within quotes.


    1-5                 VARIABLE SUBSTITUTION

    See also chapter 4 for more information on variables, special
    variables, and special variable forms.

    $name   If name is the name of a bsh variable, its value is
            substituted for the $name occurrence.  If it is not a bsh
            variable, the null string is substituted.
                % set a Fred
                % echo Hi, $a
                Hi, Fred

    ${name}x Concatenates a string on to the end of a variable. This
            is so bsh can tell where the variable name ends and the
            string begins as in the following example.
                % set a Mon
                % echo ${a}day
                Monday

    $array[$i]  Substitutes the i-th element of array if it exists.
            If it does not exist, no changes are made.
                % set a Bob Bill Joe
                % set i 2
                % echo Hi, $a[1]
                Hi, Bill
                % echo Hi, $a[$i]
                Hi, Joe

    $#array Substitutes the number of elements in an array.  A zero
            is substituted  if the variable is not defined or is not
            an array.

    $?name  Substitutes 1 if name is defined, else 0.

    Variable substitution occurs within double quotes, but not within
    single quotes.


    1-6              FILENAME COMPLETION (WILDCARDS)

    *       Matches any string of characters of any length including
            the null string.

                % set a *       # creates an array a, containing the
                                # names of all files in the current dir

    ?       Matches any single character.

                % echo ???      # echos the names of all files in the
                                # current dir whose names are  three
                                # characters long.

    {s1,s2} Matches either s1 or s2.  These are not wildcards in them-
            selves, but expand as though they had matched.  If combined
            with wildcards, only file names matching are expanded.
            For example:

                % echo {a,b,c}  # even if these don't match any files.
                a b c
                % echo *.{c,o}  # only matches existing files ending in
                                # in .c or .o

            This can be used with the SET command to construct arrays:

                % set a {0,1}{0,1,2,3,4,5,6,7,8,9} # generates an array
                                # of 20 elements containing 00 thru 19

    Filename completion does not occur within quotes.


    1-7                 DIRECTORY ALIASES

    See also chapter 8 for more information on directory aliases

    .       the current directory.
    ..      the parent directory of the current dir.
    ./f     the file 'f' in the current directory.
    ../f    the file 'f' in the parent of the current dir.
    ~       the home dir (specified by the home variable).
    ~/f     the file 'f' in the home directory.

    Directory aliasing does not occur within quotes.
   2-0                 COMMAND LINE EDITING

    Command-line editing is in effect from the time bsh prints the
    prompt until you press <cr> unless bsh was invoked with the -a
    option.  The command line can be up to 255 chars in length,
    including the prompt; once the command-line has reached its
    maximum length, attempts to insert a character are ignored.  Bsh
    will normally keep track of the line width if the window is
    resized or the font size is changed.


    2-1                 CONTROL KEY DEFINITIONS

    Control keys cause the command-line editor to take certain actions
    immediately.  Control keys not in the following list are ignored.

        ^A      Toggles insert/overtype mode
        ^B      Moves the cursor backward one word (same as shift
                left-arrow)
        ^\      EOF - this causes bsh to quit (unless _ignoreeof
                has been set)
        ^E      Places the cursor at the end of the line
        ^F      Moves the cursor forward one word (same as shift
                right-arrow)
        ^H      Deletes the character to the left of the cursor
        ^K      Deletes from the cursor to the end of the line
        ^R      Retypes the current line
        ^U      Deletes the portion of the line to the left of
                the cursor
        ^W      Deletes from the cursor to the end of the word
        ^X      Deletes the entire line
        ^Z      Places the cursor at the beginning of the line
                following the prompt
        ^-      Recalls the save-buffer.
        del     Deletes the character under the cursor


    2-2                 FUNCTION KEYS

        f1-f10  Function keys and their associated bsh variable names
        s1-s10  Shifted Function keys and their associated variables
        Help    Help key

    When you press a function key, if the corresponding variable is
    defined, its contents are read just as though you had typed each
    character of the variable.  If the variable is a command, you can
    then execute it just by pressing <cr>, or continue to add to the
    command line.  If the variable ends with a return (^M), the
    command will be executed immediately without waiting for you to
    press <cr>. The help key invokes the HELP command and then
    reprints the command line as it was.


    2-3                 THE ARROW KEYS

        Up arrow                Recall previous commands
        Down arrow              Recall subsequent commands
        Left arrow              Move the cursor backward on the
                                command line
        Right arrow             Move the cursor forward on the
                                command line
        Shift up arrow          Partial history recall
        Shift down arrow        Partial history recall
        Shift left arrow        Move the cursor to the beginning of
                                the previous word
        Shift right arrow       Move the cursor to the beginning of
                                the next word

    If you type a partial command string, and then a shift up arrow,
    bsh will search backward for a command beginning with that string;
    if one is found, it replaces the current contents of the command
    line.  Subsequent shift up/down arrows recall previous/subsequent
    matching commands respectively.  If you alter the line, it becomes
    the new search string; the search string is discarded when you
    execute the command.

    Before searching the command history, bsh saves the current
    command line in a save buffer; thus if you type an arrow key by
    mistake, you can recover the line you were typing by entering a
    ^- (control-minus).
   3-0                         COMMANDS


    The usual form of the command line is:
        NAME [<input-file] [>output-file] [arguments]
    where NAME is the command-name; for some commands (@, CD)
    it is usually possible to omit the command name.  The redirection
    arguments can appear anywhere in the command (even before the
    command-name); this is in fact the only way to redirect the output
    of the EVAL command.  However the pipe operator, if used must be
    last, since it also serves as a command separator.  The order of
    search is first aliases, then builtin commands, then resident
    (RES/REZ/RESIDENT) commands, followed by directories specified in
    the path variable.  For all builtin commands, case is significant;
    they are all in lower case: Break is the DOS Break command, while
    break is the builtin break command.  During the command search,
    scripts are treated no differently than other commands; if a script
    is found in your path and it has its script bit set, it is SOURCE'd,
    and any specified arguments are placed in the argv array.



    3-1                     BUILTIN COMMANDS


                                ABORT
      ABORT [exit-code [error-number]]

      Causes the remainder of the command line to be discarded.  Used
      with exception processing (see chapter 7).  ABORT will also set
      the exit-code and error-number if these are passed; this can be
      used to restore the values which are normally cleared after each
      command.

      % echo a;abort;echo b
      a


                                ALIAS
      ALIAS
      ALIAS name
      ALIAS name command...

      Declares name to be an alias for the command(s) specified.  In
      order to specify more than one command, you must use quotes
      around the entire list of commands.

      % alias frog "echo hop hop; echo hop; echo hop hop hop"

      then you can just type 'frog'.  All arguments to the alias are
      placed in the variable '!' which you can reference anywhere in
      the alias string:

      % alias rdonly protect $! -wd
      % alias inc @ $!++

      % rdonly *.c
      % i=0
      % inc i
      % echo i = $i
      i = 1

      Additionally, you can use aliases to change the default options
      for commands:

      % alias rm rm -i
      % alias ls ls -l

      Henceforth every time you use the rm command, it will prompt for
      each file before deleting it; ls will now give the long listing
      by default.  Bsh detects the recurrence of the command and
      prevents the alias from becoming recursive.

      If an alias has the same name as a normal command, you can still
      use the normal command by preceding the command with a backslash.

      % \rm *.info      # remove .info files without prompting
      % \ls             # print the short file listing

      See also UNALIAS


                                ARRAY
      ARRAY varname[size] ...
      ARRAY varname ...

      Declares varname to be an array of size elements.  If varname
      already exists, its contents are lost.  When the array is created,
      is is filled with NULL strings; these values are not considered
      to be numeric.  You must assign values to the individual elements
      before using them in expressions.  The second form can be used to
      convert a simple variable into an array of one element; array
      variables remain unchanged.  Arrays are singly dimensioned and are
      limited to no more than 32767 elements.


                                BREAK
      BREAK

      Break out of a while loop; execution continues with the next
      command following the corresponding endwhile for the current
      level of loop.  The BREAK command is used to prematurely exit a
      loop.  BREAK is restricted to script files.


                                CAT
      CAT
      CAT [file....]

      Copies the specified files to stdout (the current window, unless
      output has been redirected).  If you don't specify a file, stdin
      is copied.  You can cat standard input along with other files by
      specifying - (minus sign) alone as a file name.  You can also use
      CAT to join binary files together by redirecting the output to a
      file.

        % cat a                 types a to the current window
        % cat - bar >foo        copies stdin + bar to foo
        % cat a b c >prt:       copies a b and c to the printer


                                CD
      CD
      CD path

      Changes the current working directory.  You may use any of the
      directory aliases here (see Directory Aliases in chap. 8).

      CD with no arguments changes the current directory to the
      directory specified in the home variable, or if the home variable
      is undefined, CD just displays the path of the current directory.

      If you enter a directory name by itself on a line, then bsh
      implicitly changes the working directory to that dir.  This is
      only done if the path search fails to find a command of the same
      name and the dir name does not conflict with an internal command.


                                CLOSE
      CLOSE fd...

      Close a file.  fd is the file descriptor returned by the open()
      function.  The FILES command will list the file-names and
      descriptor numbers of all open files.  You cannot use CLOSE to
      close files opened by some other program.  Care should be used
      with this command, as it is possible to close files which are
      still in use such as script files and redirection files.


                                CONTINUE
      CONTINUE

      Advance to the next iteration of a while loop; execution
      continues with the while command at the top of the loop.
      CONTINUE is restricted to script files.


                                CP
      CP file... dev
      CP [-AacdeNnu] file file
      CP [-AacdeNnu] file... dir
      CP [-AacdeNnru] dir... dir

        -A      Set archive bit on source files after successful copy.
        -a      Set archive bit on destination files.
        -c      Causes cp to copy the file-protection bits and comment
                from the original file to the destination file.
                Otherwise the protection mask is set to ----rwed.
        -d      date - set file timestamp to current time and date.
                Default is to retain the original timestamp.
        -e      Copy only files which already exist in destination
                directory.
        -N      Copy only files which have been modified (archive bit
                is not set).
        -n      Copy only files which do not exist in destination
                directory.
        -r      Recursively copy all subdirectories.
        -u      Update - copy file only if destination file is older
                or does not exist.

      Copies files and directories.  To recursively copy all
      subdirectories of the directories specified on the command line,
      the "-r" option must be used.  If "-r" is not specified, each
      file in dir is copied, but none of the sub-directories in dir is
      copied.  When copying recursively, directories will be created
      automatically, if they do not already exist.

      Using the first form, it is possible to copy several files to a
      DOS non-filing-system device (E.G. PRT:); in this case, there
      are no applicable options.

      examples:

        % cp this that PRT:     # copy files to the printer
        % cp -u ~ .             # copy files from the home directory to
                                # the current dir; only copy file if it
                                # is newer.
        % cp *.c prt:           # copy all .c files in the current dir
                                # to the printer.

      CP has no quiet option but can be made to copy quietly by
      redirecting stderr:

        % cp dir1 dir2 2>NIL:


                                ECHO
      ECHO [-n] string...

      Write the strings to standard output (the current window unless
      output has been redirected).  A newline character is appended to
      the end of string unless '-n' is specified.


                                ELSE
      ELSE

      ELSE clause of a block if; this toggles the value of the matching
      IF condition.  Only one ELSE is allowed for each IF command.


                                ELSEIF
      ELSEIF expression

      ELSEIF clause of a block if; if the matching IF condition was
      true, it is now false; if it was false, it is now true if
      expression evaluates to true (non-zero).  Any number of ELSEIFs
      may be associated with one IF.

      example:

        if a < 10
        ...
        elseif a < 20
        ...
        else
        ...
        endif


                                ENDIF, FI
      ENDIF
      FI

      The end of the scope of a block IF statement.


                                ENDWHILE
      ENDWHILE

      The of the scope of a while loop.

      See also WHILE


                                @, EVAL
      @ expression
      EVAL expression

      @ and EVAL both evaluate an expression (see expressions below)
      After evaluating the expression, EVAL prints the value to the
      standard output, whereas @ does not.  If the _debug variable is
      set to 8, expression values are always printed to standard error
      when evaluated.  If you enter an assignment expression on a line
      by itself, bsh will execute an implied @ command using that
      expression.  If you wish to redirect the output of EVAL, you
      must place the redirection operator before the command name:

        % >foo eval 1+1

      it is not currently possible to pipe the output of eval to another
      command.

      examples:

        % eval sqrt(4)
        2.0000000
        % @ j=5
        % x=sin(.543)
        % echo $x
        0.51670675

      See also expressions in chapter 5.


                                EXPORT
      EXPORT varname...

      Sets the export flag for varname; variables which have the
      export flag set are exported to sub-shells of the current shell
      (they inherit its value).  This includes all shells started by
      bsh or newbsh commands from the current shell.  Script local
      variables cannot be exported.


                                FILES
      FILES

      Lists all files currently opened by bsh.  This includes files
      opened by the open() function, files opened by redirection
      ( >file ), and script files currently being executed.
      Information includes the file name, the file descriptor number,
      and whether the file was opened for read or write access.


                                FOREACH
      FOREACH var ( list ) command...
      FOREACH var ( list )
         command
         ...
      END

      For each argument in list, the argument is assigned to the
      variable var, and then each of the commands is executed in turn.
      If more than one command is given with the first form, they must
      be enclosed in quotes.  Foreach does not require a space between
      the open parenthesis and the first argument; however if the first
      argument contains a wildcard, then you must include the space for
      wildcard expansion to work properly; the same is true between the
      last argument and the closing parenthesis.  Only the first form
      of FOREACH can be used in an alias definition.

        % foreach i (1 2 3) echo "$i is a digit"
        1 is a digit
        2 is a digit
        3 is a digit

        % foreach i ( *.o )     # remove .o files
        > j=basename(i)
        > if -f $j.asm          # for which the source is in assembly
        >     rm -q $i
        > endif
        > end

      FOREACH can be used to interpret arguments of a parameterized
      alias:

        % alias xx "foreach i ( $! ) echo \$i"
        % xx *                  echos the names of all files in the
                                current directory

      You may not use a GOTO or WHILE command inside a FOREACH; however
      you can have calls to source scripts which do include GOTO and
      WHILE commands.  Also it is not possible to nest FOREACH commands.


                                GOTO
      GOTO label

      GOTO the named label.  Command execution continues with the
      command immediately following the label.  GOTO is restricted
      to script files.


                                HASH
      HASH
      HASH command
      HASH command path

      Display the hash tree, display the hash-path for a command, add
      a command and path to the hash tree.  Bsh searches the hash tree
      when the hash-operator (#) is included in the path variable.
      The use of this reduces the search time and disk accesses
      required to locate an external (disk-based) command.  No action
      by you is required to take advantage of this feature, as bsh
      automatically adds names of commands to this tree when it finds
      them while searching your path.  The HASH command allows you to
      manipulate this tree.  The filename part of path need not match
      command.

      Examples:

        % hash ls work:bin/ls   # add ls to the hash tree
        % hash                  # display the hash tree
        ls      work:bin/ls
        vi      work:bin/z

      See also UNHASH, REHASH


                                HELP
      HELP

      Displays all the bsh builtin commands and predefined functions.
      The commands are displayed columnwise in alphabetical-order.


                                HIST
      HIST [string]

      Displays the history list with event numbers (The number of
      events remembered in the history list is determined by the
      bsh _history variable).  If a string is specified, only those
      entries starting with string are shown.


                                IF
      IF expression
      IF test expr

      Execute following commands (through ELSE/ELSEIF/ENDIF) if
      expression evaluates to true (non-zero).  The IF command is not
      restricted to source files, and may be used interactively.  You
      can see whether the expression is true by using it with the
      EVAL command.  The structure of an IF block is something like
      this:

        if expression
            commands
            ...
        elseif expression
            commands
            ...
        elseif expression
            commands
            ...
        else
            commands
            ...
        endif

      The ELSEIF/ELSE clauses are of course optional.  If blocks may be
      nested up to a maximum depth of 32.  The nesting depth is reset at
      zero for each script file, so you could be nested at say level 23
      in one script file called from another at a depth of 31.

      The second form of IF involving the test command is included
      mainly for compatiblity with Bourne shell scripts.  See the
      separate documentation for test for format of test expressions.
      Bsh's own expression evaluation is much more powerful and easier
      to use than that of the test command.

      examples:

        if a < 10               if variable a is less than 10
            somecommand
        endif
        if -z fred              if file fred exists and is empty
            mv fred ..
        endif
        if ?x                   if variable x has been defined
            if a[5] != 0        if element 5 of a is non-zero
                x /= a[5]
            else
                echo a[5] is zero
            endif
            eval x
        endif

      See also expressions in chapter 5.


                                LABEL
      LABEL name

      Define a label name; used as the object of a GOTO.  Labels can
      only be used within a script file.  When LABEL is used, it
      should be the first command on a line as GOTO can only branch
      to line boundries.


                                LOCAL
      LOCAL varname[=value]...
      LOCAL arrayname[#elements]...

      LOCAL must be used from within a bsh script file; it creates a
      variable local to that script.  If a global or environment
      variable of the same name exists, it is masked (becomes
      invisible) within the script.  In order for a variable to become
      local to a script, it must be declared local (with the LOCAL
      command) before any other reference to it.  When a script exits,
      all variables local to that script are automatically destroyed.
      You cannot initialize an array with the LOCAL command.

        % local i j=1 ar[20] k=2 l
        % set ar {0,0,0,0,0}{0,0,0,0}   # initializes ar with zeros


                                MEM
      MEM

      Display memory availability for CHIP and FAST memory.  The
      advantage of using MEM over Avail is that MEM is an internal
      command and thus does not disturb the memory availability in
      order to print it.


                                MKDIR
      MKDIR name name name...

      Create directories.  If name already exists, MKDIR returns
      exit-status 5 (WARN) if name was a directory, or exit-status
      10 (ERROR) if name was a plain file.


                                MV
      MV from to
      MV from... todir

      Rename a file or move one or more files or directories to a
      different directory.  If todir is "/" or "..", the files are
      moved to the parent directory; if todir is ".", the files are
      moved into the current directory.  Currently MV cannot move
      files across devices (MV df0:a df1:).  MV will complain if you
      try to move a directory inside itself or inside one of its
      subdirectories.  MV returns an exit-status of 10 (ERROR) if the
      destination file already exists or todir does not exist or your
      try to mv a dir inside itself.


                                ONERR, ONINTR
      ONERR command...
      ONINTR command...

      ONINTR specifies the command(s) to be executed when an interrupt
      (^C,^D) is encountered when executing a script.  If ONINTR has
      been specified, the interrupt signals are reset before executing
      the command(s).  ONERR specifies the commands to be executed when
      an error occurs while executing a script.  See also the onerr,
      and onintr variables.  You can also set a global ONERR, which
      specifies commands to be executed if an error occurs while
      executing commands entered interactively, from the command line.
      If multiple commands are given, they must be enclosed in quotes.


                                PICK
      PICK [item...]

      PICK prompts you for every item specified on the command line, and
      for each item you respond positively, writes its name to standard
      out.  If no items are specified, PICK reads its standard input for
      items, one item per line.  For each item in the list, PICK prompts
      with:

        item [ynaveq] ?

      available responses are:
        y       yes, choose this item
        n       no, do not choose this item
        a       select this item, and all remaining items in the list
        v       view this item; uses program specified in the environment
                variable PAGER to view the item.  If the variable PAGER
                does not exist, the program More is used.  This only makes
                sense if item is a file.
        e       edit this item; uses program specified in the environment
                variable EDITOR to edit the item.  If the variable EDITOR
                does not exist, the program Ed is used.  This only makes
                sense if item is a file.
        q       quit
        !cmd    run cmd.  A '%' character in the command is replaced by
                the current item.

      PICK is best used to restrict command line arguments generated by
      wildcard search or by some other program:

        % cp `pick *.c` df1:foo         select which *.c files to copy
        % mv `find . -print | pick` a   select which files to move from
                                        list generated by 'find' to dir a.
        % pick * | zoo aI foo.zoo       select which files to archive


                                PRINTENV
      PRINTENV

      Displays the values of the environment variables.  PRINTENV only
      displays those files in the ENV: directory (not in subdirectories).


                                PWD
      PWD
      PWD file...

      Print the current directory name if no files given.  If files are
      specified, the absolute DOS path to each is printed.


                                QUIT
      QUIT [value]

      Quit bsh.  If you specify a value, bsh exits with the optional
      exit-code.  (see RETURN below)


                                READ
      READ varname...

      Read variable(s) from stdin.  One line is read and split according
      to IFS (see special variables).  Data are matched with the
      specified variable names.  Any excess data is discarded; if there
      is less data than variables, the remaining variables are set to
      the null string ("").  You cannot read an entire array just by
      specifying the array name; you must list the individual elements
      to be read.

        % read a b c[2] c[3]


                                REHASH
      REHASH

      Delete the entire hash tree.  See the discussion under HASH above.


                                REPEAT
      REPEAT count command

      Repeatedly execute a command.  The count can be an expression but
      if it contains any of '|; ><' you will have to enclose it in
      quotes.  Command may be several commands separated by semi-colons.
      If it is, the entire list of commands should be enclosed in quotes.
      You may not use a GOTO, WHILE or FOREACH command inside a REPEAT.


                                EXIT, RETURN
      EXIT [expression]
      RETURN [expression]

      Return from a script file.  If given, the expression value becomes
      the return value for the SOURCE command.  In a function script,
      this value is RETURN'ed as the function value.  In a startup
      script, EXIT functions as a QUIT command, that is bsh is prevented
      from going into interactive mode; once bsh has gone into interactive
      mode, EXIT functions only as a return.  This allows you to set up
      scripts which will run normally if entered from the command line,
      but quit after running the script when entered:

        % bsh <scriptfilename>


                                REWIND
      REWIND fd...

      Rewind a file; the file is positioned at its beginning.  Fd is a
      file descriptor returned by the open() function.


                                RM
      RM [-iqr] file...

      Delete the specified files or empty directories.  Use the "-r"
      option to remove non-empty directories by recursively removing
      all sub directories and files they contain.  The -i option will
      cause bsh to prompt for each file with:

        filename [ynaveq] ?

      before it is deleted; see the PICK command for responses.  RM
      returns errorcode 5 (WARN) if the file did not exist or 10
      (ERROR) if RM could not delete the file because it was busy.
      The -q option causes RM to do its work quietly, otherwise each
      file is listed as it is deleted.


                                SET
      SET
      SET name
      SET name string...

      The first form displays all bsh variables and their values.  The
      second form displays the value for a single variable.  The last
      form sets a variable to a string or array of strings.  To include
      a space in the value for a variable, you must quote the value.

      See also UNSET
      see the section on special variables below


                                SETENV
      SETENV name string

      Set an environment variable.  The environment variables are really
      files in the ENV: directory.  This probably should be assigned to
      some directory on your ram: disk by your startup-sequence.
      Environment variables are referenced in the same way as other bsh
      variables with the exception that environment variable names are
      not case sensitive.  If an environment variable and a bsh variable
      have the same name, the bsh variable overrides.  Also environment
      variables cannot be arrays at this time.

        % setenv NAME Fred
        % echo $name
        Fred


                                SLEEP
      SLEEP [time]

      Sleep for <time> seconds.  If <time> is not specified, bsh takes
      a one second nap.  Time may be specified with or without a
      fractional part (n.nn).  The resolution of <time> is .02 seconds.


                                SOURCE
      SOURCE script-file [arguments]

      Execute a script file.  Normally, you just type file [arguments];
      the main advantage to specifying SOURCE explicitly is that it
      does not require that the script and execute permission bits be
      set for the file.  Note that when you specify SOURCE explicitly,
      the path is not searched for file; you must specify the path for
      the file unless it is in the current directory.  Arguments are
      passed via the argv[] variable.  The name of the source script
      is in argv[0], the ith argument to the script is in argv[i].
      See also argv under special variables in chap. 4.  Some commands
      such as GOTO and WHILE can only be used in script files.

      Scripts are useful to replace a frequently used or long sequence
      of commands with a single, easy to remember command.  They are
      also useful in dealing with some program's clumsy user interface.
      Also, scripts can often be used in place of a C program, and are
      much easier to write and debug.  For more info on script
      programming, see chapter 7.


                                THEN
      THEN

      THEN does absolutely nothing whatsoever.  It is included only for
      compatibility with Bourne-shell scripts.


                                UNALIAS
      UNALIAS name...

      Removes bsh aliases from the alias tree.

      See also ALIAS


                                UNHASH
      UNHASH command

      Removes a command name from the hash tree.

      See also HASH, REHASH


                                UNSET
      UNSET name....

      Removes bsh variables from the variable tree and frees all space
      used by each for strings, arrays.

      See also SET


                                UNSETENV
      UNSETENV name....

      Removes the named environment variables.  This deletes the
      ENV:name file.

      See also SETENV


                                VER
      VER

      Displays the version number of bsh, along with its date.


                                WHILE
      WHILE expression

      Repeat statements while expression is true (non-zero).  WHILE can
      only be used in script files.  While loops may be nested up to a
      maximum depth of 10.

      example:

        while a < 10
            a++
            ...
        endwhile

      See also expressions in chapter 5.
      See also ENDWHILE


                                WINDOW
      WINDOW [parent | child]
      WINDOW [back | front | activate | zip]
      WINDOW x y width height
      WINDOW

      Manipulate the bsh window.  Using this command, you can move
      the bsh window in back of all other windows, in front of all
      other windows, activate the window, change its dimensions,
      toggle between two sizes (zip, requires DOS 2.0), or activate
      the child or parent of the shell's window.  Be careful - you
      can set the window width and height to zero if it has no size
      gadget; the window will then be very hard to find.  Also, any
      changes to the window size made while the window is not the
      active window are apparently missed by the console (I think
      this is fixed in DOS2.0)  With no arguments, WINDOW prints the
      current window coordinates and bounds; you can use this to save
      the current window bounds and restore them later:

                % set wndw `window`     # save current window bounds
                % window 0 0 640 400    # change window size...
                        ...
                % window $wndw          # restore window to previous
                                        # bounds

      The zip function requires AmigaDOS2.04 to operate.
      Keyword arguments may be abbreviated to a single letter.




    3-2                     OTHER COMMANDS


                                BSH
      BSH [-a] [startup-script]...
      BSH -c command;command...

      Startup a bsh shell in the current CLI window.  The -a switch
      is useful when you want to suppress bsh's command-line editing
      features.  It is possible to use the command-line editing features
      in an AUX: CLI.  The second form can be used to gain bsh services
      in running a command (i.e. wildcards, pipe, etc.).  At startup,
      bsh first reads and executes the file .bshrc in the current
      directory if it exists, or s:.bshrc.  Next if the -c switch was
      selected, command is executed and bsh then quits, else any startup
      scripts specified on the command line are executed.  Then bsh
      executes the file .login in the current directory if it exists,
      or s:.login and then enters interactive mode.  If a QUIT or EXIT
      command was encountered during execution of a startup script, bsh
      will quit without entering interactive mode.


                                NEWBSH
      NEWBSH [window-spec] [-a] [[FROM] startup-script...]
      NEWBSH [window-spec] -c command...

      Startup a new bsh shell in a different window.  The FROM keyword
      is only required if the first argument would be a startup script,
      to distinguish it from a window specification.  NEWBSH can be
      started from WorkBench by double-clicking on the NEWBSH tool
      icon, or by double clicking on a script icon.  Some sample icons
      are provided.  You can also extended select several script icons,
      and NEWBSH will execute each of them in turn.  If any of the
      scripts contain a QUIT or EXIT command, NEWBSH will quit after
      executing all of the scripts; otherwise NEWBSH will enter
      interactive mode, accepting command input.
   4-0                         VARIABLES


    Bsh like other shells uses only string variables.  However, some
    commands that work with expressions, can perform arithmetic on
    these variables as numbers.  These special commands are @, EVAL,
    IF, ELSEIF, RETURN, and WHILE.  In this context, a numeric variable
    is really a string variable that contains only digits with a leading
    sign or hexadecimal radix (0x), a decimal point and an exponent.
    Internally, variables are stored in a binary tree for fast access.

    A variable name consists of any number of characters chosen from
    letters, digits and the underscore.

    Variables may be set (assigned a value) by the SET command, or by
    use of an assignment operator in an expression.


    4-1                   VARIABLE SUBSTITUTION

    When a variable has been assigned a value, bsh replaces occurences
    of that variable on command lines with the assigned value.  Bsh
    recognizes a word as a variable if it begins with a dollar sign.
    You can protect a word from variable substitution by preceding the
    dollar sign with a backslash (\$).  Variable substitution occurs
    even if the variable name occurs within a string enclosed in double
    quotes, but not in a string enclosed in single quotes.  Environment
    variables are referenced in the same manner as regular bsh
    variables on the command line; however they cannot be assigned a
    value in an expression.  Within an expression, variables are
    referenced without the leading dollar sign.


    4-2                     ARRAY VARIABLES

    Before you can manipulate the elements of an array, the entire array
    must be declared.  Arrays can only be declared using the SET, or
    ARRAY commands:

        % set days Sunday Monday Tuesday Wednesday Thursday Friday Saturday

        % echo $days
        Sunday Monday Tuesday Wednesday Thursday Friday Saturday

    Individual array elements may be referenced by postfixing the array
    name with an element number enclosed in square brackets; the
    element number can also be a numeric variable.  A range of elements
    can be referenced by the first element number followed by a dash
    followed by the last element number.  An asterisk can be used to
    indicate all elements of the array, an asterisk can be used after
    the dash to indicate the last element of the array.

        % echo $days[3]
        Wednesday

        % echo $days[1-5]
        Monday Tuesday Wednesday Thursday Friday

        % set i 2
        % echo $days[$i]
        Tuesday

        % echo $days[$i-*]
        Tuesday Wednesday Thursday Friday Saturday

    All elements must be assigned a value when the array is declared
    (a NULL or 0 may be used if the desired value will not be known
    until later).  The SET command counts the number of items on the
    command line and allocates enough memory for that many elements.
    The ARRAY command allocates enough storage for the specified
    number of elements, and fills them all with NULLs.


    4-3                  SPECIAL VARIABLE FORMS

    The number of elements of an array can be referenced by using the
    form:

    $#array_name

    The existence of a variable can be queried by the form:

    $?var_name

    This form returns 1 if var_name has been defined, and 0 if it has
    not been defined.  You can also use this to determine whether an
    array has a specified number of elements:

    $?array[5]

    returns a 1 if array has at least 6 elements.

    You can catenate a plain string to the end of a variable on the
    command line if you enclose the variable name in braces:

    % set dow Sun
    % echo ${dow}day
    Sunday


    4-4                   SPECIAL VARIABLES

    Variable names starting with an underscore ('_') have a one to one
    connection with flags/counters deep in the heart of bsh.  For this
    reason, their intended effect cannot be accomplished using environ-
    ment, or local environment variables.


    argv
    *
        This array variable contains the arguments passed to a script
        program.  Each argument is an element of the array.  For
        example:

                    script-file printargs
            local i
            echo $argv
            echo $*
            set i 0
            while i < #argv
                echo argv[$i] = $argv[$i]
                i++
            endwhile

        % printargs 1 2 4
        printargs 1 2 4
        1 2 4
        argv[0] = printargs
        argv[1] = 1
        argv[2] = 2
        argv[3] = 4

        Individual arguments may be addressed as $argv[4], $argv[$i]...
        argv[0] contains the script file name; the remaining arguments
        may be referenced as a group by $*.  $* is equivalent to
        $argv[1-*].  Any of the first 10 elements may be referenced by
        short form; $1 is equivalent to $argv[1]...


    commands
        Contains the count of commands executed since bsh was started.
        This is maintained by bsh, however, it is not always updated
        after every command; if you exececute a script file, it will
        not be updated until the script completes.  This variable is
        read-only.


    cwd
        Contains the absolute path of the current working directory.
        This variable is maintained by bsh each time you change the
        working directory with a CD command or an external (disk-based)
        command changes the current directory.  This variable is read-only.


    _debug
        Debug modes.  The following debug modes are supported:
                 0      no debugging
                 1      print command arguments prior to executing
                        each command
                 2      print redirection file names (console is
                        indicated by an asterisk).
                 4      print depth of variable names in variable
                        tree (applies to set, hash, local and alias
                        commands only).
                 8      print expression values when they are evaluated
                        (by @, EVAL, IF, ELSEIF, RETURN, WHILE)
                16      print exit status, and DOS error number after
                        each command executed.
                32      print actual command line (after all variable
                        substitutions, and wild-card expansion).  As an
                        alternative to _verbose, this prints only those
                        commands that are actually executed.  If used
                        with mode 2, both outputs are combined on 1 line.

        Set _debug to the sum of the desired debugging modes.  Debugging
        output is written to the stderr file.  _debug must be a bsh
        variable (not an environment variable for this to have any effect).


    errno
        This variable contains the DOS error number from the last command.
        To obtain an English translation, feed it to Fault:

                % Fault $errno

        Remember that this variable is reset after each command, so you
        will have to assign it to some other variable first if you plan
        to manipulate it.  For the custom bsh error numbers, you can use
        the error script provided:

                % error 909
                error 909: reference to undefined variable


    height
        Maintained by bsh, this is the height of the console window in
        lines.  If you resize the window, bsh will update this variable
        to reflect the change.


    histnum
        This variable contains the event number of the next command to be
        executed.  This value is substituted for '!' in the prompt or
        title.  This variable is read-only.


    _history
        This variable specifies the number of history events bsh should
        retain.  Consecutive identical history items are entered in the
        history list only once.  _history must be a bsh variable (not an
        environment variable for this to have any effect).


    home
        This is the home directory variable; it contains the full path
        specification for the home directory.  It is substituted for a
        leading ~ in file name/path specifications.  This variable is
        automatically set by bsh at startup, but you can alter it at any
        time.

        examples:

        % cp ~/foo .    copies the file foo from the home directory
                        to the current directory.
        % ls ~          lists the files in the home directory.


    IFS
        Contains the characters that serve as argument separators when
        command output is being substituted on the command line or when
        variables are being read (READ command).  If IFS is not set,
        the value " \n\t" (space, new-line, tab) is used.


    _ignoreeof
        If defined, EOF is ignored on consoles.  Use this to prevent
        accidentally exiting bsh.  You can still exit bsh by entering
        the QUIT command.  _ignoreeof must be a bsh variable (not an
        environment variable for this to have any effect).


    insert
        This variable controls the default screen insert/overlay mode.
        If insert is set to 0 (zero), the default mode is overlay, else
        mode defaults to insert.  If insert is not set, insert is the
        default mode.  Of course you can always toggle between modes
        by typing a ^A during command entry.


    _noclobber
        If set to some value, output redirection will fail if the file
        already exists; append redirection will fail unless the file
        already exists.  Use of this variable can sometimes keep you
        from accidently clobbering an important file.  _noclobber must
        be a bsh variable (not an environment variable for this to have
        any effect).


    _noglob
        If set to some value, inhibits wildcard expansion.  Use this if
        you want an external program to do it's own wildcard expansion,
        or when symbols normally used as wildcards have a different
        meaning.  _noglob must be a bsh variable (not an environment
        variable for this to have any effect).


    _nonomatch
        If set to some value, will not complain when a wildcard string
        fails to find a match; instead, if the match fails, the string
        will be passed on to the command to be executed.  _nonomatch
        must be a bsh variable (not an environment variable for this to
        have any effect).


    _noreq
        If set to some value, will disable requesters ("Please insert
        volume fred in any drive") during the path search for external
        commands.  _noreq must be a bsh variable (not an environment
        variable for this to have any effect).


    path
        This contains the search paths used to find external commands.
        path is an array variable containing a list of directory-names
        to be searched, and optionally some special elements:
            '!'     Search the CLI path.  This does not include the
                    current directory, or C:.  See the example set path
                    below for how to include them.
            '#'     Look for the command in the hash list.
            '0'     Turn off requesters for following directories.  If
                    path contains, say, fred:c, and volume fred: is not
                    mounted, you can avoid a requester saying "Please
                    insert volume fred in any drive".
            '1'     Turn requesters back on.
        The path variable is not used if the command is in the system
        RESIDENT list, or the command name contains pathing information
        (contains a ':' or '/').  The suggested set value for path is

            % set path '.' '#' '!' sys:scripts c:

        This assumes that your bsh scripts are in the sys:scripts directory.
        There is no default value for path.


    pipe
        This variable contains the name of the pipe device which will be
        used when piping output from one command to input of another.  If
        pipe is undefined, temporary ram: files are used instead.  If set
        to "PIP:", it is assumed to be a conman PIP: pipe device; case is
        significant.


    prompt
        This string is displayed when bsh is expecting interactive input
        from the user.  Special characters recognized are:
                !       the value of the variable histnum (event number)
                `       the current time (HH:MM)
                ``      the current time (HH:MM:SS)
                \       used to protect the following character from
                        interpretation; to get a \, use \\.
                $name   the value of the variable name (any bsh variable)
                        If this should be evaluated each time the prompt
                        is printed, the name should be escaped as in
                        \$name; this will prevent the command parser from
                        evaluating the variable immediately.

        If commands are being skipped because you executed an IF command,
        bsh changes the prompt to "? ".  You must then enter an endif
        command before command execution resumes.


    PS2
        This is the secondary prompt used when bsh is expecting interactive
        input from the foreach command:

        % set PS2 "huh? "
        % foreach i ( a b )
        huh? echo $i
        huh? end
        a
        b

        If PS2 is not defined, the value "> " is used.


    status
        Exit-status of the last command.  This is set after each command
        executed, so it is necessary to query this immediately or its
        value will have changed.


    _title
        This string is printed in the window title line.  Special
        character processing is the same as for the prompt string.  _title
        must be a bsh variable (not an environment variable for this to
        have any effect).


    _umask
        This variable controls the permission bits set for files opened
        by bsh for output redirection.  The variable must be set to the
        sum of the desired permission bit values (use 15 for rwed, 13
        for rw-d, etc).  The permissions for the file are set after the
        file is closed.  _umask must be a bsh variable (not an environment
        variable for this to have any effect).


    _verbose
        Enter verbose mode (for scripts).  This mode displays commands as
        they are read from the script file.  Debugging output is written
        to the stderr file.  _verbose must be a bsh variable (not an
        environment variable for this to have any effect).


    width
        Maintained by bsh, this is the console width in chars.  If you
        resize the window, bsh will update this variable to reflect the
        change.
   5-0                         EXPRESSIONS

    The commands - @, ELSEIF, EVAL, IF, RETURN, and WHILE evaluate and
    utilize C-like expressions in the perfomance of their functions.
    Expressions consist of strings, numeric constants, bsh variables,
    function references and operators.  You can freely insert spaces
    anywhere in an expression except in compound operators variable
    names or numeric strings.  Within expressions variable names may
    be used without the leading dollar sign ($).  If you use a leading
    dollar sign, the variable is replaced by the command parser and
    looks like a constant to the expression evaluator.  Numerical
    operations are performed on 32-bit signed ints or 32-bit FFP
    floating point operands.  Variables have no intrinsic type, but
    assume the type of the data they contain.  The arithmetic and
    relational operators will all allow mixed mode operands.  That is
    an int can be added to a floating point operand or compared to
    a floating point operand; in this case, the int is first converted
    to floating point and then the operation is performed.  Environment
    variables may also be used within expressions, but may not be
    altered by an assignment operator within an expression; use the
    setenv command to alter environment variables.


    5-1                         OPERATORS

    The following is a list of bsh operators in order of precedence
    from highest to lowest.

        ()      override precedence of operators
        ?var    test the existence of a variable (this is similar to the
                $?var special form [see chap. 4-3]).
        #array  number of elements in an array (this is similar to the
                $#array special form [see chap. 4-3]).
        ~       unary one's complement
        !       logical not
        -       unary minus
        ++      increment a bsh variable (var++, ++var)
        --      decrement a bsh variable (var--, --var)
        %       modulus
        /       division
        *       multiplication
        -       subtraction
        +       addition
        <<      left shift
        >>      right shift
        >       greater
        <       less
        >=      greater or equal
        <=      less or equal
        !=      not equal
        ==      equal
        &       logical product
        |       logical sum
        ^       exclusive or
        &&      logical and
        ||      logical or
        =       assign a value to a bsh variable
        +=      increment the value of a bsh variable
        -=      decrement the value of a bsh variable
        *=      multiply the value of a bsh variable
        /=      divide the value of a bsh variable
        %=      assign the modulus value of a bsh variable
        ,       comma operator (comma is a binary operator which
                returns the value of the subexpression to the right
                of the comma).  That is, a = (b,c) assigns the value
                of c to a.  The comma is also used to separate
                function parameters, and to separate multiple
                assignments in an expression:

                    % a=1,b=2,c=3

    IMPORTANT: The decrement and increment operators are pre-increment
    (++var) and post-increment (var++).  In either case, the variable
    is incremented, but the value used in the expression is that of
    the variable before incrementing (post-increment) or after
    incrementing (pre-increment).  That is, if i has the value of 1,
    then j = i++ assigns the value of 1 to j while incrementing i to 2.
    These operators can only be used with integers.

    In addition, file operators operate on following filename.
    Boolean operators:

        -A      file has been archived
        -D      file has delete access
        -d      file is a directory file
        -e      file exists
        -f      file is a plain file
        -o      file exists
        -P      file is pure
        -r      file has read access
        -S      file is a script file
        -w      file is writeable
        -x      file is executable
        -z      file is empty

    Operators which return a value:

        -m      time of last modification (seconds since 1/1/1978)
        -p      file protection string (hsparwed)
        -s      size of file in bytes
        -T      date file was last modified
        -t      time file was last modified

    Examples:
        % eval str=-T fred
        26-Nov-89

        % eval str=-p fred
        ----rwed

        % if -f fred
        % echo fred is a plain file
        % endif

    A variable containing a file name must be prefixed by a dollar sign ($)
    when it is the object of a file operator.

        % if -s $file > 1000
        % echo $file is larger than 1000 bytes
        % endif


    5-2                 FUNCTIONS

    The following functions are predefined by bsh:

          abs(num)
        returns the absolute value of num.

          acos(num)
        returns the angle whose cosine is num.

          asin(num)
        returns the angle whose sine is num.

          atan(num)
        returns the angle whose tangent is num.

          basename(str)
        returns the base filename of str.  If str is "foo.c",
        basename(str) returns "foo".

          cat(str1,str2,...)
        concatenates strings.

          char(num)
        returns the character whose ascii value is num.  This provides a
        means to convert small integers to characters.

          cos(num)
        returns the cosine of num.

          cosh(num)
        returns the hyperbolic cosine of num.

          date()
        returns the current date in MM/DD/YY format.

          devname(str)
        returns the device name portion of string.  If str is
        "df1:foo", devname(str) returns "df1".

          eof(fd)
        returns true if EOF was read on file fd (fd is a file
        descriptor number as returned by open()).  Calling the eof()
        function has the side-effect of clearing the EOF condition for
        the file.

          exp(num)
        returns the exponential of num (e**num).

          filename(str)
        returns the file-name stripped of path.

          float(num)
        converts an integer to floating point.

          getchar()
        reads a character from stdin and returns it.

          hex(num)
        converts num to a hexadecimal string.

          index(str,"c")
        returns the position of first occurence of "c" in str.  Returns
        -1 if "c" not found in str.
                % eval index("abc","c")
                2
                % eval index("abc",99)      99 is the ascii value of 'c'
                2

          int(num)
        converts num to integer.

          left(str,num)
        returns the leftmost num characters in str.

          log(num)
        returns the natural logarithm of num.

          log10(num)
        returns the base 10 logarithm of num.

          lower(str)
        returns str transformed to lower case.

          max(num1,num2)
        returns the maximum of two numbers.

          min(num1,num2)
        returns the minimum of two numbers.

          mounted(device)
        returns true if device has been mounted and bsh is able to
        obtain a lock on it; this only works for filing-system devices.

          numeric(str)
        returns true if str is a numeric string.

          open(filename,mode)
        opens a file, and returns the file descriptor number.  Available
        modes are:
            "a" - append
            "r" - read
            "w" - write

          pathname(str)
        returns the path name portion of string.

          pow(base,exp)
        returns base raised to the exp power.  This is a floating point
        function, but will return an integer if both arguments are
        integer.

          ran(max)
        generates a random integer in the range (0 <= num < max).  Max
        must be < 4194304 (2**22).

          right(str,num)
        returns the rightmost num characters in str.

          rindex(str,"c")
        returns the position of last occurence of "c" in str.  Returns
        -1 if "c" not found in str.  See also index.

          rtime()
        returns the number of ticks since midnight.  There are 50 ticks
        per second.

          sin(num)
        returns the sine of num.

          sinh(num)
        returns the hyperbolic sine of num.

          size(var)
        returns the size of array (1 indicates scalar, 0 undefined)

          sqrt(num)
        returns the square root of num.

          strlen(str)
        returns the length of str.

          substr(str,first,len)
        extracts a substring from a string starting with character
        numbered first, of length len.
                % eval substr("abcdefg",3,3)
                cde

          tan(num)
        returns the tangent of num.

          tanh(num)
        returns the hyperbolic tangent of num.

          time()
        returns the current time in HH:MM:SS format.

          upper(str)
        returns str transformed to upper case.


    Additionally, any bsh script file may be used as a function; it
    returns a value via the RETURN command.  As with any other bsh script,
    arguments are passed to the function in the argv variable:

    funcname([arg]...)      user defined function

    File funcname must be somewhere in your path.
   6-0                 REDIRECTION AND PIPES


    You can now specify the type of PIPE you wish to use in the bsh
    variable pipe.  If this variable is undefined, PIPES are
    implimented as temporary ram: files.  These files are
    automatically deleted upon completion of the pipe segment.  To use
    the new 1.3 Pipe.device, you need only set the pipe variable:

        % set pipe PIPE:

    To use the Conman pip: device as a pipe:

        % set pipe PIP:

    Case is significant.  You should probably place one of the above
    commands in your s:.bshrc file.  Of course, whichever pipe you use,
    you will have to Mount it before using it; this should probably be
    done in your startup-sequence.

    If the pipe variable is set, bsh will run pipe segments in the
    background as separate processes, if they are external commands.
    This allows the pipe reader to start execution as soon as the pipe
    feeder produces some output instead of waiting for it to complete.
    As of version 1.0, a script which is executed as a pipe feeder,
    will be run in a sub-shell in the background; this is also true
    for a script run by the background operator '&'.

        % script1 | wc      Script1 runs in a subshell in the
                            background, while wc counts its
                            output.
        % script1 &         Script1 just runs in the background.


    It is now possible to redirect standard input and standard output
    to any file opened with the open() function.  For example:

        % j=open("foo","w")
        % cmd >&$j
        % close $j

    The output from cmd has been placed in file foo just as if you had
    typed:

        % cmd >foo

    Output can be appended to the end of a file by using the append
    redirection operator:

        % cmd >>foo


    The standard error file can can be redirected for internal bsh
    commands only (bsh will redirect standard error for external
    commands when running under AmigaDOS2.0 or higher.  Even then,
    this will only work for those commands which check for DOS2.0 and
    the pr_CES field in the process structure.)

        % cmd 2>foo         Redirect error messages from cmd to
                            file foo.

        % cmd1 2>>foo       Appends error messages to the end of
                            file foo.

        % cmd1 2>&1 | cmd2  Sends error messages down the pipe
                            along with regular output.


    A special form of input-file redirection is the here document;
    this allows you to include data for a program in a script
    immediately following the command invocation:

        % prog <<some-string-of-your-choice
        this is data line 1
        this is data line 2
        ...
        some-string-of-your-choice

    The lines of data are copied to a ram: temporary file, and input
    is redirected from that file.
   7-0                     SCRIPT PROGRAMMING

    Scripts are run as any other command, that is, if you type "foo",
    and the script file foo exists in your current directory or your
    search path, it is run automatically as though you had typed
    "source foo".  For this "automatic sourcing" to occur, the script
    file must have the SCRIPT and EXECUTE permission bits set:

        % protect foo +se

    You can also input or output redirect scripts the same as any
    other program.  Script output may also be piped to a different
    program, however currently, the script does not run in parallel
    and the pipe is a temporary ram: file.  In version 1.0 of bsh,
    these scripts will run in parallel in a separate shell.
    Parameters may be passed to scripts and are available to the
    script program in the local array argv.  Argv[0] contains the
    script name, and the remaining elements contain the actual
    parameters.


    7-1                         LOOPING

    Looping in scripts is accomplished using the WHILE or GOTO
    commands.
    Example:
        i = 1
        while i < 99
            cmd1
            if whatever
                break
            endif
            i++
        endwhile

    Bsh branches within scripts by Seeking to the new location.
    Because bsh cannot currently seek to the middle of a line, the
    WHILE and LABEL commands must be the first command on a line.
    Small loops (less than 1024 bytes) can be fit in a buffer and thus
    eliminate disk thrashing.


    7-2                     ARGUMENT PASSING

    Arguments are passed to scripts in the argv array variable.  This
    variable is local to the called script and is always an array,
    even if no arguments were specified.  Argv[0] contains the script
    name, as specified on the command line.  The remaining arguments
    are in argv[1] thru argv[n], where n is the number of arguments.
    The first ten arguments can be referenced in a short-hand way; $0
    refers to $argv[0], $9 refers to $argv[9].  The notation $* refers
    to all arguments after the script name, that is: $argv[1] ...
    $argv[n].  $argv[*] refers to all arguments including the script
    name, that is: $argv[0] ... $argv[n].

    The argv array is only a copy of the strings passed to the script,
    so you can safely alter elements of the array or even UNSET the
    array.

    The following program fragment shows how a script might examine its
    arguments looking for keywords.

        i = 1, list = 0, delete = 0, move = 0
        while i < #argv
            if lower(argv[i]) == 'list'
                list = 1
            elseif lower(argv[i]) == 'delete'
                delete = 1
            elseif lower(argv[i]) == 'move'
                move = 1
            endif
            i++
        endwhile


    7-3           EXCEPTION PROCESSING and INTERRUPTS

    If no onerr variable exists, any command which fails causes the
    script to abort as though a RETURN command had been executed.  A
    command fails if its exit status is >= the FailLevel set by the
    FailAt command.  The script will then return that value as its own
    exit status.  The onerr variable is set by the ONERR command:

        % onerr "stt=status,err=errno; cmd1; cmd2..."

    While bsh is executing a script, if a command fails with
    exit-status >= FailLevel, bsh then checks for the onerr variable.
    If the onerr variable exists, then the error status is cleared and
    the commands specified in the onerr variable are executed;
    execution then resumes with the next command unless the onerr
    contained a GOTO, RETURN or ABORT command.  The ABORT command can
    restore the exit-status:

        % onerr "stt=status,err=errno; cmd1; cmd2...; abort $stt $err"

    While bsh is executing a script, if a ^C (control-C) or ^D
    (control-D) signal is received, bsh then checks for the onintr
    variable (the onintr variable is set by the ONINTR command).  If
    the onintr variable exists, then the signals are cleared, and the
    commands specified in the onintr variable are executed; execution
    then resumes with the next command unless the onintr contained a
    GOTO, RETURN or ABORT command.

    Each script has its own onerr, and onintr variables; thus they can
    safely reference labels in the script file.

    The onerr/onintr commands should probably include one of RETURN or
    GOTO or ABORT.  This will ensure that an error in a pipe-line
    causes the pipe-line to be aborted.
   8-0                     DIRECTORY ALIASES


    Any argument of a command can make use of the directory alias
    feature.  To use this, the argument must start with one of the
    directory aliases:

        .       the current directory.
        ..      the parent directory of the current dir.
        ./foo   the file 'foo' in the current directory.
        ../foo  the file 'foo' in the parent of the current dir.
        ~       the home dir (specified by the home variable).
        ~/foo   the file 'foo' in the home dir.

    The ../ operator may be applied repetitively to higher and higher
    levels until you reach the root of a device:

        ../../f the file 'f' in the parent of the parent of the
                current dir.
        ~/../f  the file 'f' in the parent of the home dir.

    All of the directory alias substitutions are replaced with
    absolute path names; if you are currently in fred:a/b/c:

        % echo ../../foo
        fred:a/foo
        % echo //foo
        //foo
   9-0                     PROBLEMS



    Do not redirect the RUN command. to redirect the command the RUN
    command is running, include a standard CLI redirection in the
    command string:

        % RUN "command >file"

                            --------

    You need to give bsh sufficient stack space, especially if you
    will be running recursive shell scripts.  8192 is sufficient
    for the maximum recursion depth (16).  Stack should be run BEFORE
    invoking bsh.  Running it from within bsh does not affect bsh's
    stack size.  You don't need to worry about stack for newbsh, if
    called from a CLI; in this case newbsh allocates a stack of 8192
    bytes for itself.  Stacksize set in newbsh tool icons or script
    project icons should be set to at least 8192.

                            --------

    Programs which use Manx or Lattice stdio can sometimes cause the
    conman PIP: pipe-handler to crash.  This is NOT a bug in bsh.
    You can ignore the requester and the next time you use a pipe,
    the PIP: pipe-handler will be reloaded.

                            --------

    There is a bug in the new, DOS 2.04, Queue-Handler (V37 PIPE)
    which causes the pipe writer program to hang if the the pipe
    reader completes first.  To see this try:

        % mount PIPE:
        % set pipe PIPE:
        % type <some-file-bigger-than-12k> | More

    when More starts up, type q (for quit).  You will now have a
    hung process "type" which bsh is waiting to complete.  If you
    type a ^E (control-E), you should see a line that looks like:

        wait proc: type, procno 1, level 1

    If you type a ^F (control-F), bsh will move that process (and all
    others that it is waiting on) to the background, and once again
    accept command input.  If you execute the FILES command you should
    see a line that looks like:

        FILE: 3, 7EXXXXX/1FXXXXX, name = PIPE:A123456789, Write

    Now type:

        % cat PIPE:A123456789 >NIL:

    The background "type" process should complete and go away.  As an
    alternative to this process, you could continue to use the V36
    PIPE (Pipe-Handler); in your mountlist change L:Queue-Handler to
    L:Pipe-Handler, and change Stacksize = 3000 to Stacksize = 6000.
    If you updated from V36 to V37 using the 2.04 install disk, you
    should find Pipe-Handler in the System2.0:old directory.

                            --------

    Conman CNC: and CND: handlers apparently discard type-ahead when
    bsh toggles in and out of raw mode.  If type-ahead is important
    to you, use regular CON: or NEWCON: console windows.  Alternately,
    if you want to use Conman features, use the -a option when starting
    bsh or newbsh; this will disable the switch to raw mode.

                            --------

    "Say" does something funky to the console after which, it is
    impossible to place it in raw mode.  This has the effect of making
    bsh appear to hang.  You can escape by typing a ^\ (control-\) to
    get out of bsh.  If you started by bsh (not newbsh), you should
    EndCLI this CLI, as other programs which need to place the console
    in raw mode will hang.

                            --------

    It is not possible, currently, to redirect a parameterized alias
    which contains pipe segments.  That is

        % alias lx "ls $! | grep -v \.info"
        % lx >foo

    will now get error 904: redirection error.

                            --------

    Bsh does not run under AmigaDOS1.1 or older systems; bsh uses
    several Exec, DOS, and Intuition library calls new to the 1.2 OS
    release.  If there is a great deal of interest in this, I may
    provide a DOS1.1 compatible version.  But this would be very
    difficult as the Manx SDB debugger also does not run under
    DOS1.1.  Why are you running DOS1.1 anyway?  This version is
    obsolete.