Club Amiga de Montreal - CAM/CAM_CD_1.iso/files/074.lha/CShell/shell.doc

Text File | 1986-11-20 | 26KB | 917 lines

          INSTRUCTIONS FOR SHELL Version: 2.07M 10-Sep-87
        ================================================

  Contents
  --------

    I.    Description
    II.   Overview of Major features
    III.  Restrictions
    IV.   PIPES
    V.      Command Pre-processor
    VI.   Command Line Editing
    VII.  Function Keys
    VIII. Shell Commands
    IX.   Special Set Variables
    X.      Advanced Topics
    XI.   Example login file
    XII.  Example script file


I.  Description
    -----------

    Shell V2.07M is the follow on to 2.04,5,6M which originated from:
    Shell V2.04 by Matt Dillon:
    Shell V2.04 (C)Copyright 1986, Matthew Dillon, All Rights Reserved
    Enhanced by permission by Steve Drew.

    You may distribute this program for non-profit only.



II. OVERVIEW
    --------

    Shell provides a convient AmigaDos alternative command interface.
    All it's commands are internal and thus does not rely on the c:
    commands for any functionality (except the run command).


    Major features include:

    -command line editing
    -shell & Amigados search path support
    -simple history
    -redirection of any command
    -piping
    -aliases
    -variables & variable handling (embedded variables)
    -file name expansion via conventional wild carding ('?' and '*')
    -conditionals (if/else ect..)
    -source files  (w/ gotos and labels)
    -many built in commands to speed things up


III. RESTRICTIONS
     ------------

    o AmigaDos execute command will not work. Alternative is to use shell
      own script language (which is more powerful) or to do a 'run execute'.
    o This version runs UNDER WORKBENCH 1.2 ONLY.
    o VDK handler has a bug with setting file dates so when using the copy
      command and VDK you should use the -d switch otherwise you file date
      in vdk: will be bad. (This is not a bug with shell)
    o If using with conman it may be best to start shell with the -a switch
      (shell -a .login) to turn off shell's command line editing and use
      conmans instead.

IV. NOTES ON PIPES
    --------------

    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

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


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

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

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

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

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


VI. COMMAND LINE EDITING
    --------------------

    o Command line can be upto 255 chars.
    o Inserts and deletes are handled correctly over multiple screen lines.
    o Shell will keep track of the line width should the window get resized.

     KEY DEFINITIONS:
              Up Arrow    Recal previous commands
           Down Arrow  Recal commands
         Left Arrow  Move cursor about command line.
         Right Arrow  "     "      "      "      "
         ^A        Toggle insert/overtype mode.
         ^D        EOF
         ^E        Put cursor at end of text.
         ^K        Delete to end of line.
        ^R        Retype current line.
        ^U        Erase entire line.
        ^X        Erase entire line.
        ^Z        Put cursor at start of text.
        f1 - f10    Execute command if variable exists.
        F1 - F10    More commands (Shifted f keys).
        Help         invokes help command


VII. FUNCTION KEYS
     -------------

    Function keys now insert text to the current position on the command
    line. They maybe terminated with a ^M (return). f1 would be non shifted
    where as F1 is shifted.

      $ set f1 dir df0:^M

    will add the text 'dir df0:<return>' to the current line.

      $ set f1 dir

    would only add 'dir' you could then enter ' df0:<return>'



VIII. SHELL COMMANDS
      ---------------

   First to start shell from a CLI

   shell [-a] [-c command;command]

   where:
     -a disables all command line editing features. This is usefull for
        when running shell over AUX:.

     -c allows execution of one command line and then exits out of shell.
     This is usefull for running a internal shell commands in the
     background or from an external application. eg:
        Run shell -c dir df0:; copy -r df0: df1: >nil:; echo "Done"

     If you 'Run' shell in the background without the -c switch shell
     will detect this and imediatley exit.


   Command execution:

   Internal shell commands maybe abreviated.

   The first argument is the command-name... if it doesn't exist in the
   list below and isn't an alias, it is assumed to be an external (disk)
   command. At this point the shell pathing, and AmigaDos pathing is checked
   in order to locate the command.

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


   Wild card expansions:
    Most shell commands will accept multiple arguments that can
    be as a result of wild card expansion. Also when the calling
    an external command shell will first expand any wild cards
    to seperate arguments. If you wish to have the external command
    handle it's own wild carding you will need to insert quotes
    arround the special wild card characters ? and *.

    eg.
        arc a new.arc *.txt    - shell will expand and pass to arc
        arc a new.arc "*.txt"   - let arc expand the wild cards.

    Wild card expansions:
        ?      match any single character
        *      match any string
        df0:.../* all files in all directories on df0:
        .../*      recursive search down ALL sub directories from
              current level

    LIST OF COMMANDS:
    -----------------

    *** NOTE:
    THERE EXISTS TWO VERSIONS OF SHELL 2.07M, THE ONLY DIFFERENCE
    IS IN ONE VERSION COMMANDS CAT, RM, MV, HAVE BEEN RENAMED TO BE
    TYPE, DELETE, RENAME. (I had'nt intended this version to be public
    for consistancy sake, but it slip out.)
    USE THE HELP COMMAND TO DETERMINE WHICH VERSION YOU HAVE.


    ABORTLINE

    usage  : abortline
    example: echo a;abort;echo b
    results: a

    Causes the rest of the line to be aborted. Intended for use in
    conjunction with exception handling.


    ALIAS

    Usage   : alias [name] [command string]
    example : alias vt "echo Starting VT100;run sys:tools/vt100"

        Sets a name to be a string. You can alias a single name to a set
    of commands if you enclose them in quotes as above. By simply
    typing vt, the command line above would be executed.


    Argument Passing to an Alias:

    Usage    : alias name "%var [command string]"
    example : alias xx "%q echo hi $q, how are ya."
          xx Steve
    results : hi Steve, how are ya.

    The second form of the alias command allows passing of arguments
    to any position within the command string via use of a variable
    name. To pass arguments to the end of a command string this method
    is actually not necessary.


    CAT
    (TYPE)

       Usage   : cat [file file....]
     example : cat foo.txt

    Type the specified files onto the screen.  If no file is specified,
    STDIN in used.  CAT is meant to output text files only.


    CD

    Usage   : cd [path]
    example : cd df0:devs/printers

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

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


    COPY

    Usage   : copy [-u][-d] file file
    or    : copy [-u][-d] file1 file2...fileN dir
    or    : copy [-r][-u][-d] dir1 dir2...dirN dir
    options :
          -r    recursive, copy all subdirectories as well.
          -u    update, if newer version exist on dest, don't copy
          -d    don't set destination file date to that of source.

    example : copy -r df0: df1:


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

    All files will be displayed as they are copied and directory's
    displayed as they are created. This output can be suppessed by
    redirecting to nil: eg. copy -r >nil: df0: df1:

    Copy will abort after current file on Control-C.

         Copy by default sets the date of the destination file to that of
         the source file. To overide this feature use the -d switch.

         Another useful option is the -u (update) mode were copy will not
         copy any files which exists already in the destination directory
    if the destination file is newer or equal to the source file.
    This is usefull when developing code say in ram: eg. 'copy *.c ram:'
    when done you can copy -u ram: df1: and only those modules you have
    modified will be copied back.

    Copy command will now create the destination directory if it does
    not exist when specified as 'copy [-r] dir dir'. If you specify
    copy file file file dir, then 'dir' must already exist.


    DEC

    Usage   : dec varname
    example : dec abc

    Decrement the numerical equivalent of the variable and place
    the ascii-string result back into that variable.


    DEVINFO

    Usage   : devinfo [device: device:... ]
    example : devinfo df0: df1: ram:

    Display Device statistics for the current device (CD base), or
    specified devices. Gives block used/free, % used, errs and
    volume name.


    DIR

    Usage   : dir [-sdf] [path path ... ]
    example : dir df0:
    options :
          -s  short multi(4) collum display, directories in red pen.
          -d  list directories only
          -f  list files only


    Displays a directory of specified files. Default output show's
    date, protection, block size, byte size. And total space used.
    Files are alphabetically sorted, first by upper case then by
    lower. (allows README files ect.. to stand out.)

    Wild card expansions:
        ?    match any single character
        *    match any string
        .../    recursive search down ALL sub directories
        dir df0:.../    does a full (All) sorted directory
        dir .../*.c    start at current dir and go down looking
                for all .c files.

    Exclude pattern matching specifier: !

    dir !*.info will       exclude all *.info files in current dir.
    dir df0:.../!*.info       full directory tree of df0: but exclude
                  any ugly .info files.
    dir !*.o !*.c (will result in ALL files matching since what
                doesnt match the !*.o will match the !*.c)


    ECHO

    Usage   : echo [-n] string
     example : echo hi there
    results : hi there

        Echo the string given. If -n switch given no newline is
    appended.


    ELSE ;

    Usage   : else ; command
    Usage   : if -f foo.c ; else ; echo "Not there" ; endif

    Else clause, must follow an IF statement.


    ENDIF

    Usage   : endif

    The end of an if statement.

    *Note: if you return from a script file with unterminated IF's
     and the last IF was false. No commands will be executed until
     'endif' is typed.


    FOREACH

    Usage   : foreach varname ( strings ) command
     example : foreach i ( a b c d ) "echo -n $i;echo \" ha\""
    result  : a ha
          b ha
          c ha
          d ha

    'strings' is broken up into arguments.  Each argument is placed in
    the variable 'varname' in turn and 'command' executed.  To execute
    multiple commands, place them in quotes:

    Foreach is especially useful when interpreting passed arguments in
    an alias.

    eg.
        foreach i ( *.pic ) viewilbm $i
    assuming a.pic and b.pic in current directory the following commands
    will occur:
        viewilbm a.pic
        viewilbm b.pic


    FOREVER

    Usage   : forever command
    or      : forever "command;command;command..."

    The specified commands are executed over and over again forever.

    -Execution stops if you hit ^C
    -If the commands return with an error code.


   GOTO

    Usage   : goto label
     example :
          label start
            echo "At start"
            dir ram:
            goto start

    Goto the specified label name.  You can only use this command from a
    source file. Labels may now be forward or reverse from current
    position.


    HELP

    Usage   : help
    example : help

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


    HISTORY

    Usage   : history [partial_string]
     example : history

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


    IF

    Usage   : if argument conditional argument ;
    or      : if argument
     or      : if -f file

    If a single argument is something to another argument.  Conditional
    clauses allowed:

    <, >, =, 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.

    The third form of IF used by -f switch checks for existance of
    the specified file.

    When using 'IF' command interactively if you are entering commands
    following an 'IF' that was false, the prompt will be set to a
    underscore '_ ' to indicate all commands will be ignored until
    an 'ELSE' or 'ENDIF' command is seen.

    INC

    Usage   : inc varname
    example : inc abc

    Increment the numerical equivalent of the variable and place
    the ascii-string result back into that variable.


    INPUT

    Usage   : input var var ... var
    example : input abc

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


    LABEL

    Usage   : label name

    Create a program label right here. Used in source files, can then
    GOTO a label.


    MEM

    Usage   : mem

    Display current memory statistics for CHIP memory and
    fast memory (if any installed).


    MKDIR

    Usage   : mkdir name name name...
     example : mkdir df0:stuff

    Create the specified directories.


    MV
    (RENAME)

        Usage   : mv from to
    or      : mv from from from ... from todir

    Allows you to rename a file or move it around within a disk.
    Allows you to move 1 or more files into a single directory.


    PS

     Usage   : ps

    Gives status of DOS processes.  eg:

    Proc Command Name         CLI Type    Pri.  Address  Directory
     1   SHELL                Initial CLI   0      97b0  Stuff:shell
     2   sys:c/clockmem       Background  -10    2101a8  Workdisk:
     3   c:emacs              Background    0    212f58  Stuff:shell
     4   sys:c/VT100          Background    0    227328  Workdisk:

     Address is the addres of the task, directory is the process
     currently CD'd directory.


    PWD

    Usage   : pwd

    Rebuild _cwd by backtracing from your current directory.


    QUIT

    Usage   : quit

    Quit out of Shell back to CLI.


    RETURN

    Usage   : return [n]
    example : return 10

    Exit from a script file, or quit from shell with optional
    exit code.


    RM
    (DELETE)

     Usage   : rm [-r] file file file...
    example : rm foo.txt test.c

    Remove (delete) the specified files.  Remove always returns
        errorcode 0.  You can remove empty directories.  The '-r' option
        will remove non-empty directories by recursively removing all sub
        directories.
    If  you specify any wildcard deletes the files will be listed as
    they are deleted. This can be suppressed by redirecting to nil:
    eg.  rm df0:.../*.o   delete all .o files from every directory.


    RUN

    Usage   : run prgm
    example : run emacs

    Finds the specified file via $_path variable, or 2nd via AmigaDos
    PATH setting, then calls AmigaDos Run command with the explicit
    path/command. This command is really only implemented to allow
    consistancy in first checking the shell pathing before amigados
    pathing. Since shell allows for device names in _path it does'nt
    care when you swap disks; if you had "df0:c/" in _path then whatever
    disk you have in df0: will be checked. AmigaDos PATH always resolves
    to a Lock that points only to a particular disk label:directory.


    SET

    Usage   : set [name] [string]
    example : set abc hello

    Set with no args lists all current variable settings.
    Set with one arg lists the setting for that particular variable.
    Specifying name and string, stores the string into variable name.

        Also See the section on special _variables.


    SLEEP

    Usage   : sleep timeout
    example : sleep 10

    Sleep for 'timeout' seconds, or until ^C typed.


    STRHEAD

    Usage   : strhead varname breakchar string
     example : strhead j . foobar.bas
              echo $j
    result    : foobar

    Remove everything after and including the breakchar in 'string' and
        place in variable 'varname'.


    STRTAIL

    Usage   : strtail varname breakchar string
     example : strtail j . foobar.bas
          echo $j
    result  : bas

    Remove everything before and including the breakchar in 'string' and
    place in variable 'varname'.


    SOURCE

    Usage   : source file [arguments]
    example : source do_assigns all
    result  : source file 'do_assigns' called with var _passed = 'all'

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

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


    --------- file hello.sh ---------
    foreach i ( $_passed ) "echo yo $i"
    ---------------------------------

    $ hello a b c
    yo a
    yo b
    yo c


    UNALIAS

    Usage   : unalias name .. name
    example : unalias vt

    Delete aliases..


    UNSET

    Usage   : unset name .. name
     example : unset abc

          Unset one or more variables.  Deletes them entirely.


    VER

    Usage   : ver

    Show current version name, & authors.



IX. SPECIAL SET VARIABLES
    ---------------------

    _prompt
    This variable is set to the command you wish executed that will
    create your prompt. This can contain escape sequences if you wish.
    The if command will set the prompt to a '_ ' if commands are
    disabled while waiting for a 'endif' or 'else' command. Interactive
     mode only.

    _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
        <command>, then for <command>.sh (automatic shell script sourcing).

        The default _path is set to  "c:,df1:c/,df0:c/,ram:,ram:c/"
        When using 'run' command Shell will now use it's own search
    path first to find the command to run. If it fails to find
    the command (but the Run command was found) it executes the
    command line anyway to let amigaDos search path take over.

    _insert
        Set's the default for insert/overtype mode for command line
    editing. ^A toggles between, but after <RET> the default is
        set back as indicated by this variable. By default _insert is 1
        indicating insert mode on setting to zero will make overtype
    the default.

    _width
    Indicates the console window width, 77 if unset.
     Will change automatically if the user resizes the window.



X.  ADVANCED TOPICS
    ---------------

    EXCEPTION_PROCESSING:

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

    "nnn;commands..."

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

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

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

    example:

    set _except "20;abortline"



XI. 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:


    # -Steve's .login file- #

    echo -n    "Enter Date [DD-MMM-YY HH:MM] ";input new; DATE $new

    # ------My search path ------- #

    set   _path  ram:c/,ram:,c:,df0:c/,df1:c/,sys:system/,sys:utilities

    # -------Function keys-------- #

    set   f1     dir df0:^M
    set   f2     dir df1:^M
    set   F1     dir -s df0:^M
    set   F2     dir -s df1:^M
    set   f3     info^M
    set   f4     ps^M

    # ---------Quickies---------- #

    # -query delete- #
    #another favorite eg    qd *.c
    alias qd "%q foreach i ( $q ) \"echo -n Delete [n] ;input a;if $a = y;del $i;endif\""

    alias delete rm
    alias rename mv
    alias makedir mkdir
    alias type  cat
    alias print "%q copy $q prt:"
    alias info  "devinfo df0: df1: ram:"
    alias tosys "assign c: SYS:c"
    alias toram "assign c: RAM:c;"
    alias tomanx "assign c: MANX:c; manxinit"
    alias d     "dir -s"
    alias clr   "echo -n ^l"
    alias wb    "loadwb"
    alias pref  "sys:preferences"
    alias cal   "run sys:utilities/calculator"

    # ------Applications---------- #

    alias em    "run emacs"
    alias vt    "run sys:c/VT100"

    # --------Finish Up----------- #

    ver ;echo -n "Shell loaded on ";date



XII. Example Source file
     -------------------

     # ---- MANXINIT.SH  ------ #

    SET INCLUDE=AC:include CCTEMP=ram:
    makedir ram:lib;Set CLIB=RAM:lib/;copy AC:lib/$libfile ram:lib"
    alias    cleanup    "del >NIL: ram:lib/* ram:lib"

    #run make in background at lower priority:
    alias    make    "%q run ChangeTaskPri -5 +^J^J MAKE $q"