comnd.doc

语法分析 编译原理 词法分析 语法分析 C++原代码

             This  function  parses  a  guide word string (noise words).
        Guide words appear between  significant  parts  of  the  command
        line, if  they  are  in  parentheses.    They  do not have to be
        typed, but if they are, they must match what is  expected.    If
        the  previous  field  ended  with  command  completion, then the
        guide words are shown automatically by the parser.

             An interesting use of guide  word  strings  is  to  provide
        alternate sets  with  the  command  chaining feature.  The parse
        (and program) flow can be altered depending on which string  was
        matched.



        CFB function _CMCFM:  confirmation

             A confirmation  is  a  carriage  return.  The caller should
        parse a confirmation as the last thing  before  processing  what
        was parsed.    Since  carriage  return  is  by default a wake-up
        character, requiring a confirmation will (if  you  don't  change
        this  wake-up  attribute)  require  that  the parse be completed
        with no extra characters typed.   A  parse  with  this  function
        code returns only a status.



        CFB function _CMGSK:  General storage keyword

             This  call provides for parsing of one of a set of keywords
        which are  not  arranged  in  a  table.    Often,  keywords  are
        actually stored  in  a  file  or  in  a linked list.  The caller
        fills in the CFB_DAT element of the command function block  with
        the  address  of  a  structure  named  CGKs (typedef CGK), which
        contains the following elements:


         o CGK_BAS:  A base address to give to the fetch routine.   Does
           not  matter  what  this  is,  as  long  as  the fetch routine
           understands it.

         o CFK_CFR:  The address  of  a  keyword  fetch  routine.    The
           routine  is called with the CGK_BAS value, and the address of
           the pointer to the previous  keyword.    It  is  expected  to
           return  the  address  of  the pointer to the next keyword, or
           with the first one if  the  passed  value  for  the  previous
           pointer is NULL.




                When  this  function  completes successfully, it returns
           the address of the pointer  to  the  string  in  the  CSB_RVL
           element in   the   command   state  block;    otherwise  (for
           unsuccessful completion), it must return NULL.    Please  see
           the   description   of   the   _CMKEY  function  code  for  a
           description of help and other processing.

                Note:  the General Keyword facility can be  used  to  do
           special  pre-processing  of candidate strings, such as hiding
           keywords which are not appropriate  for  the  program  state,
           user, access, etc.




        CFB function _CMSWI:  Parse a switch.

             This  is  intended  to  perform  switch  matching,  but  it
        currently is not implemented  and  will  return  a  result  code
        _CRIFC (invalid  function  code) if you try it.  Basically it is
        a placeholder for an unimplemented function.



        CFB function _CMTXT:  Rest of line

             This function parses the text  to  the  end  of  the  line.
        Note  that  this  does  not  parse  the trailing break character
        (i.e. the carriage return).  The text is returned  in  the  atom
        buffer  which  is  defined  (by  the  caller) by the CSB_ABF and
        CSB_ASZ elements of the command state block.



        CFB function _CMTOK:  token

             This function will parse an exact  match  of  a  particular
        token.   A  token  is  a  string of characters, whose address is
        supplied by the caller in the CFB_DAT  element  of  the  command
        function block.    This  function  is  mainly useful for parsing
        such things as commas and other separators, especially where  it
        is one  of  several  alternative parse functions.  It returns no
        value other than its status.




        CFB function _CMUQS:  unquoted string

             This function parses an unquoted string, consisting of  any
        characters other  than  spaces,  tabs, slashes, or commas.  This
        set may of course be changed by  supplying  a  CC  table.    The
        unquoted  string  is returned in the atom buffer associated with
        the command state block.



        CFB function _CMDAT:  parse date/time

             This function parses  a  date  and/or  time.    The  caller
        specifies,  via  flag  bits  in  the CFB_FLG byte of the command
        function block (as identified above) which  of  date,  time,  or
        both, are  to  be parsed.  The date and time are returned as the
        first two ints in the atom buffer which is associated  with  the
        command state   block.    Note  that  both  date  and  time  are
        returned, regardless of which were requested.

             Note  further  that  the  _CMDAT  function  is  not   fully
        implemented as of this writing.




                           Calling the COMND library


             All  that  you need to know to use the above information is
        how to call the  command  library.    Basically,  there  is  one
        support routine:  COMND().  It is used like this:

                 status = COMND (csbp, cfbp);

             Here,  "csbp"  is  the  address of the command state block,
        and "cfbp" is the address of the command function  block.    The
        COMND()  routine  returns  an  int status value, which is one of
        the following:


         o _CROK:   The  call  succeeded;    a  requested  function  was
           performed.   The  address  of  the matching function block is
           returned in the CSB_CFB element of the command  state  block,
           and other information is returned as described above.

         o _CRNOP:  The call did not succeed;  nothing matched.

         o _CRRPT:   The call did not succeed because the user took back
           some of what had already been parsed.    In  other  words,  a
           reparse  is  required,  and  your program must back up to the
           reparse point.  Note that if  you  specify  a  setjmp  buffer




           address  in  the  CSB_RSB element of the command state block,
           you will never see this value because the COMND library  will
           execute a longjmp() operation using that setjmp buffer.

         o _CRIFC:    The  call  failed  because you provided an invalid
           function code in the command function block (or in one  which
           is chained to it).  One of us has made a programming error.

         o _CRBOF:   Buffer  overflow.   The atom buffer is too small to
           contain the parsed field.

         o _CRBAS:  Invalid radix for number parse.

         o _CRAGN:  You should not see this code.  It is reserved for  a
           support-mode call to the subroutine library.




             When  you use the setjmp method of command reparsing, it is
        usually  enough  to  check  the  result  against   _CROK   only,
        everything else being treated the same (error in input).




                         Installing the COMND library



             This  part of the document describes the modules which come
        with the COMND library kit, and what you might have to  look  at
        if  the  code does not instantly work on your system (which will
        probably be the case if your system is not the same kind as  the
        one which you got it from).

             The files which come in the COMND kit are as follows:


         o  COMND.R  -  Source for this document, in a form suitable for
           the public domain formatting program called "roff4".

         o COMND.DOC - This document.

         o COMND.EDT - Edit history for the subroutine library.

         o MEM.H - A file of my (Mark  Mallett)  definitions  which  are
           used by the code in the command subroutine library.

         o COMND.H - Command library interface definitions.

         o COMNDI.H - Command library implementation definitions.

         o COMND.C  -  Primary  module  of  the COMND library.  Contains
           user input buffering and various library support routines.

         o  CMDPF1.C  -  First  module  of  parse  function   processing
           routines.

         o  CMDPF2.C  -  Second  module  of  parse  function  processing
           routines.

         o CMDPFD.C - Contains the date/time  parse  function  routines.
           This  is  included  in  a  separate  module so that it can be
           replaced with  a  stub,  since  few  programs  (that  I  have
           written,  anyway)  use  this  function, and it does take up a
           bit of code.

         o CMDPSD.C - A stub for the date/time parsing functions.   This
           can  be  linked  with  programs which do not actually use the
           date/time parse function.

         o CMDOSS.CPM - Operating system specific code which  works  for
           CP/M.   This  is  provided  as a model for the routines which
           you will have to write for your system.

         o DATE.CPM - Date/time support  routines  for  version  3.0  of
           CP/M.   This  is a module containing routines to get the date




           and time from the  operating  system,  and  to  encode/decode
           these values  to and from internal form.  This is provided as
           a model;  you will probably have to  rewrite  them  for  your
           system.   Note,  you  don't  need these routines if you don't
           use the date and time parsing function (if you use  the  stub
           instead).




                               Your Improvements



             If  you  improve  this  library  or  make  it work on a new
        operating system, I'd appreciate hearing about it so that I  can
        maintain a   proper   version.      Also   please  maintain  the
        edit/version history in the file COMND.EDT.


                                                Mark E. Mallett
                                                c/o M-TEK
                                                P.O. box 6357
                                                Nashua NH 03114

                                                voice: 603 424 8129
                                                data:  603 424 8124
                                                   (1200 baud, allow system
                                                    time to boot)
EEOOFF