home *** CD-ROM | disk | FTP | other *** search
/ Amiga Elysian Archive / AmigaElysianArchive.iso / prog / c / parse.lha / parse.doc_E < prev    next >
Text File  |  1992-08-11  |  9KB  |  193 lines
  1.  
  2.                                parse()
  3.                            version 1.00
  4.  
  5.                       by Jean-Pierre Rivière
  6.  
  7.           (Lecteur francophone, veuille bien lire parse.doc)
  8.  
  9.  
  10.     ABSTRACT : command line parser, easy to use and fully System V
  11.                compliant (for the options rules).
  12.                copyright (c) 1992 by Jean-Pierre Rivière.
  13.                Freely redistriubtable and free (that's freeware)
  14.                Any use of this program is free and costless as long
  15.                as the source of the program thereof, if it is
  16.                distributed, includes the present software package
  17.                or at least gives its reference and the mean to fetch it.
  18.                Any use of the package thereof is done at the sole risks
  19.                of the user, the author declining any responsability in
  20.                advance.
  21.                Enough talk, let's see the thing!
  22.  
  23.    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  24.  
  25.       Cares for the scrupulous respect of Unix System V v4 convnetions
  26.    for options parsing rules on command lines. To this end, uses a format
  27.    strings where all the options are included in no particular order,
  28.    but with a space after each option without arguments and with a
  29.    semicolon after each option with an argument.
  30.  
  31.       If everything has been all right, the return value is positive or
  32.    null, equal to the number of options recognized in the command line.
  33.  
  34.       Else it is negative to indicate a syntax error ir that the dynamic
  35.    memory allocation failed. In any case, there is nothing corresponding
  36.    to what might have been seen and hence you must not try to see that!
  37.  
  38.       If everything was OK, you shall disallocate manually by calling
  39.    parse_cleanup() to free what parse() had allocated.
  40.  
  41.       Let's remember that all the options shall be set before any arguments
  42.    if nay, that their order is clueless but that they shan't be repeated,
  43.    even if it would not be in contradiction.
  44.  
  45.       parse() and parse_cleanup() are two functions which I wrote as a
  46.    C module to ease the management of multiple options on command lines.
  47.    My goal was might and comfort and I think I reach that.
  48.  
  49.       Might because of the strict following of the norms edicted by the
  50.    Open Software Foundation. Might because easy to set into motion and
  51.    to get evoluate. The whole is then ergonomic both for the programmer
  52.    and the end user (unifomization of the shell interface is more easy
  53.    so more extended).
  54.  
  55.       The main tool for these two functions is a dumb strings which is
  56.    a sequence of options and option types : with or withour argument.
  57.  
  58.       For instance if your program is to be used so :
  59.  
  60.       fubar [-h] [-i] [-f <file>] [-o <dest>] [-v] [-R] <mode> [<type>]
  61.  
  62.    then the automatic treatment of the options is realized with the
  63.    following C string :
  64.  
  65.       "h i f;o;v R "
  66.  
  67.    or still, because the order is unimportant in that string :
  68.  
  69.       "R f;h i o;v "
  70.  
  71.       The characters in odd positions are the letters of the options. A
  72.    semicolon after a letter indicates that the option takes an argument,
  73.    a space that it doesn't. Beware : the charactcter after the letter of
  74.    option is fully mandatory.
  75.  
  76.       Attention also to the fact that the option are case-sensitive and that
  77.    you normally should use only letters (this last point is not checked but
  78.    it's up to the programmer to decide what he does there).
  79.  
  80.       By respect to the conventions thereof, the following command lines
  81.    are accepted (and correctly processed ;-) (if, of course, fubar finds
  82.    good the number of arguments he gets) :
  83.  
  84.  
  85.       fubar -i -hR -f thanks my lad
  86.  
  87.       fubar it_was_a pleasure
  88.  
  89.       fubar -o hara -hRi -f you said so
  90.  
  91.       fubar -h -  ---> here - means standard input and is not an option.
  92.  
  93.       fubar -h -o brien -- -i     --> -- indicates the end of the options
  94.                                       -i is the first argument.
  95.  
  96.       fubar -hi -o -i owa    --> the argument of an option with argument
  97.                                  is totally free. Here -i is the argument
  98.                                  of the option o.
  99.  
  100.    But the latter are not :
  101.  
  102.       fubar -hRo hara kiri  ---> the option wiharguments have to be lonesome
  103.  
  104.       fubar -hRi -hv virus  ---> never repeat an option
  105.  
  106.       fubar -ohara sant     ---> don't tie the argument to its option
  107.  
  108.       fubar -h - -i trema   ---> the - is considered as an option whose
  109.                                  letter lacks. Tthis might be out of the
  110.                                  norms (I have no more these at hand) but
  111.                                  I thought that if - is followed by a
  112.                                  group beginning by - then the first -
  113.                                  would very certainly be a typo (this is
  114.                                  true anyway when you encounter - --). This
  115.                                  was not a thing which simplified my code,
  116.                                  so I wait for your reactions...
  117.  
  118.       Well, here's a formal grammar for the description string :
  119.                   descriptor ::= descriptor | option
  120.                   option ::= (letter type)
  121.                   letter ::= { a...z A...Z }
  122.                   type ::= ( <space> ; )
  123.  
  124.       And to use all this ? See the the source code. If you define TEST
  125.    on the compilation line, you'll get an executable which will show you
  126.    I am not a liar. As the main() function suggests it, the idea is to do :
  127.  
  128.       if (parse(...) < 0) {
  129.          /* syntax errors treatment */
  130.          exit(1);
  131.       }
  132.       /* program own logic errors treatment */
  133.       ...
  134.       /* endd of the program */
  135.       parse_cleanup();
  136.       exit(0);
  137.  
  138.       For a greater ease, I defined a structure holding all the data, which
  139.    allows to easily point out what happens, and if it goes wrong.
  140.  
  141.       I let you have a look at the code (I won't duplicate it). Then pay
  142.    attention to the following things :
  143.       - a call to parse_cleanup() without a prior call to parse() is
  144.          illegal and return an error code. Yet harmless.
  145.       - a call to parse_clenup() after a call to parse() which failed is
  146.          illegal beacause parse() had cleansed everything already, and an
  147.          error code is returned. Yet harmless.
  148.       - two consecutive call to the same function parse() or parse_cleanup()
  149.          are forbidden and the second return an error code. Yet harmless.
  150.       - a call to parse_cleanup() is to free the memory allocated by a
  151.          successful call to parse(). Don't forget then to call it, even if
  152.          for instance the options set do not respect the logic of your
  153.          program. See the main() given as example.
  154.  
  155.       To use these two functions, compile them apart then link them
  156.    with your program. Thsi will warrant the processes involved.
  157.  
  158.       I defined several flags for the compilation of the module parse.o :
  159.  
  160.       NO_PARSE_ERR_MESS : if it is defined, the error messages won't exist.
  161.          You will then only have the error codes.
  162.       ENGLISH : it it is defined and if there are errors messages, those
  163.          will be in English (default id French :^)
  164.       ERR_MESS_WITHOUT_LETTER : if it is defined and if there are errors
  165.          messqages, those will be simple strings ready for printing. By
  166.          default, these string holds a %s in the right place to put the
  167.          option letter which went wrong, and hence need to be use with
  168.          a function like printf.
  169.  
  170.       When you edit your source; the only flag that might be defined
  171.    (and then before including parse?h) is NO_PARSE_ERR_MESS.
  172.  
  173.       parse() and parse_cleanup() are not public domain (because I don't
  174.    want a guy depossess me of them) but are freely redistributable and
  175.    freeware. Their use is wished anytime an Unix-like syntax is wanted
  176.    (I have never been able to cope with getopt() because it does not
  177.    very well when you modify your syntax (or I don't know how to use it
  178.    but then my solution is both more simple and more powerful)). You are
  179.    not entitled to distribute them without the documentation or for a fee
  180.    exceeding that of the support, the reference of that being the floppy
  181.    disks AmigaLibDisk distributed by Fred Fish.
  182.  
  183.       Well, good C programmation. If it's another language, feel free to
  184.    do it. Then please send me your adaptation, that would be smart of you!
  185.  
  186.    My address :
  187.  
  188.       Jean-Pierre Rivière
  189.       13, rue Maison Dieu
  190.       75014 PARIS
  191.       FRANCE
  192.  
  193.