C O M N D

                    A TOPS-20 style command parsing library
                            for personal computers




             Documentation  and  source  code Copyright (C) 1985 by Mark
        E. Mallett;  permission is granted to distribute  this  document
        and the  code  indiscriminately.  Please leave credits in place,
        and add your own as appropriate.


                                 A Disclaimer



             The code which implements this library takes up about  12Kb
        of  space  on my CP/M system using Manx's AZTEC CII Z80 compiler
        (10Kb with the date/time support stubbed out).   I  don't  claim
        that  the  coding  is  very  efficient  nor  do I make any other
        claims about the code  in  general.    I  do  believe  that  the
        definition  of  the  call  interface  is reasonable, and for me,
        this has made it quite usable.




                                 This Document



             This document contains the following sections:


         o Document overview (this here section)

         o Introduction and history

         o Functional overview

         o How to write programs using the subroutine library

         o How to make the library work on your system




                           Introduction and History



             This document describes the COMND subroutine package for  C
        programmers.    COMND   is   a   subroutine  library  to  effect
        consistent parsing of user input, and in general is well  suited
        for verb-argument   style   command  interfaces.    The  library
        provides a consistent  user  interface  as  well  as  a  program
        interface  which,  I believe, could well remain unchanged if the
        parsing library were re-written to support  different  interface
        requirements (such as menu interaction).

             The   COMND  interface  is  based  on  the  TOPS-20  model.
        TOPS-20 is an operating system  which  is/was  used  by  Digital
        Equipment Corporation  on  their  PDP-20  computer.  TOPS-20 was
        based on TENEX, written by BBN (I  think,  I  think).    TOPS-20
        COMND  is much more robust and consistent than the library which
        this document describes;  this library being intended for  small
        computer  applications,  it  provides  the  most  commonly  used
        functions.

             This library was written on a Z-80 system  running  Digital
        Research   Corporation's   CP/M  operating  system  version  3.0
        (CPM+).  I have also compiled and  tried  it  on  a  VAX  11/780
        running VMS.    It  is completely written in the C language, and
        contains only a few operating system specific elements.

             The COMND JSYS section of the TOPS-20 Monitor Calls  manual
        is probably a good thing to read.

             Please note:   while there are a few unimplemented sections
        of this library, I felt that it was nevertheless  worthwhile  to
        submit  it  to  public  domain since it is usable for almost all
        general command parsing and since the  call  interface  is  well
        defined.   I  have  used this library extensively since sometime
        in 1984.




                              Functional Overview




             The COMND subroutine library  provides  a  command-oriented
        user  interface  which is consistent at the programmer level and
        at the  user  level.    At  the  program  level,  it  gives   an
        algorithmically  controlled  parsing  flow,  where a call to the
        library exists  for  each  field  or  choice  of  fields  to  be
        parsed.

             At the user level, the interface provides:


         o Command prompting.

         o Consistent  command  line  editing.  The user may use editing
           keys to erase the last character or word,  and  to  echo  the
           current input line and prompt.

         o Input  abbreviation  and  defaulting.    The  user  may  type
           abbreviations of  keywords,  or  may  type  nothing  to  have
           defaults applied.

         o Incremental  help.    By  pressing  a  known  key  (usually a
           question mark), the user  can  find  out  what  choices  s/he
           has.

         o Guide  strings.    Parenthesized guide words are shown at the
           users option.

         o Command completion.  Where the subroutine library  can  judge
           what  the  succesful  completion  of  a portion of user input
           will be, the user can elect to have this input completed  and
           shown automatically.




                            Using the COMND Library



             While  you  read  this part of the document, you might want
        to look at the  sample  program  named  TEST.C  which  has  been
        included with  this  package.   It is an over-commented guide to
        the use of the COMND library.

             Any module which makes use of this  library  shall  include
        the definition   file  named  "comnd.h".    This  file  contains
        definitions  which   are   necessary   to   the   caller-library
        interface.   Mnemonics  (structures  and constants) mentioned in
        relation to this interface are defined in this file.

             The philosophy of parsing with the COMND library is that  a
        command  line  is  typed,  the  program  inspects  it,  then the
        program acts on  the  directions  given  in  that  line.    This
        process is  repeated  until  the  program  finishes.   The COMND
        library assists the user in typing  the  command  line  and  the
        program in  inspecting  it.    Acting  on  it  is left up to the
        calling program.

             The typing and parsing of fields in  the  command  line  go
        essentially hand-in-hand   with   this   library.    The  single
        subroutine COMND() is used to effect all parsing.  This  routine
        is  called  for  each  field  of  the  input  line to be parsed.
        Parsing is done according to a current  parse  state,  which  is
        maintained  in  a  parameter  block  passed  between  caller and
        library.   The  state  block  contains  the  following  sort  of
        information (described in detail later):


         o What to use for a prompt string.

         o  Addresses  of  scratch  buffers  for  user  input  and  atom
           storage.

         o How much the user has entered.

         o How much of the line the program has parsed.




             An important thing to note is that the  indexes  (how  much
        entered and  parsed)  are  both  variable.    The program begins
        parsing of the input line upon a break signal by the user  (such
        as the  typing  of  a carriage return, question mark, etc).  The
        user may then resume typing  and  erase  characters  back  to  a
        point BEFORE  that  already  parsed.   It is very important that
        the program does not take any action on  what  has  been  parsed
        until  the  line  has  been completely processed, otherwise that
        action could be undesired.

             Since the user may back up the command  input  to  a  point
        before  that  already  processed  by  the application program, a
        mechanism must be provided to backup the program to the  correct
        point.   Rather  than going to the point backed up to, the COMND
        library  expects  the  application  program  to  return  to  the
        beginning of  the  line,  and start again.  The user's input has
        remained in the command line buffer, and the library  will  take
        care  of  buffering  the rest of the input when that parse point
        is again reached.  However, this means  that  there  must  be  a
        method  of  communicating  to  the  calling  program  that  this
        "reparse" is  necessary.    Actually  there  are   two   methods
        provided, as follows:


         o  Each  call  to  the command parsing routine COMND() yields a
           result code.  The result may indicate that a reparse  has  to
           take place.    The  program  shall  then back up to the point
           where the parse of the line began, and start again.

         o The application program may specify the address of  a  setjmp
           buffer which  identifies  the reparse point.  (Note setjmp is
           a facility provided as part of  most  standard  C  libraries.
           It  allows  you  to  mark a point in the procedure flow [call
           frame,  registers,  and  whatever  else  is  involved  in   a
           context],  and  return to that point from another part of the
           program as if control  had  never  proceeded.    If  you  are
           unfamiliar  with  this  facility,  you  might  want to find a
           description in your C manual.) It is  up  to  the  caller  to
           setup the setjmp environment at the reparse point.


             In  either  case, the reparse point (the point at which the
        parse will be restarted if necessary) is the point at which  the
        first element  of the command line is parsed.  This is after the
        initialization call which starts every parse.




             Every  call  to  the  COMND()   subroutine   involves   two
        arguments:   a  command  state  block, in which is kept track of
        the parse state, and a command function block,  which  describes
        what sort  of  thing  to parse next.  The command state block is
        given a structure called "CSBs", and  a  typedef  called  "CSB".
        Each  element  of  the structure is named with a form "CSB_xxx",
        where "xxx" is representative of the  element's  purpose.    The
        following  are  the  elements of the command state block, in the
        order that they appear in the structure.


         o CSB_PFL is a BYTE.  This contains flags which are set by  the
           caller  to  indicate  specifics  of  the  command processing.
           These flags are:


            o _CFNEC:  Do not echo user input.

            o _CFRAI:  Convert lowercase input to uppercase.


         o CSB_RFL, a BYTE value, contains flags which are kept  by  the
           library in  the  performance  of the parse.  Generally, these
           flags  are  of  no  interest  to  the  caller   since   their
           information  can  be  gleaned  from  the  result  code of the
           COMND() call.  However, they are:


            o _CFNOP:  No  parse.    Nothing  matched,  i.e.,  an  error
              occured.

            o _CFESC:  Field terminated by escape.

            o _CFEOC:  Field terminated by CR.

            o _CFRPT:  Reparse required.

            o _CRSWT:  Switch ended with colon.

            o _CFPFE:  Previous field terminated with escape.


         o  CSB_RSB  is  the  address  of a setjmp buffer describing the