home *** CD-ROM | disk | FTP | other *** search
/ C!T ROM 2 / ctrom_ii_b.zip / ctrom_ii_b / PROGRAM / C / CL / CL.DOC < prev    next >
Text File  |  1991-12-12  |  7KB  |  244 lines
  1. YACLP (Yet Another Command Line Parser)
  2.  
  3. This code is freeware, uploaded by the author. It is provided as is. Please
  4. use freely. Any comments, suggestions etc. to
  5.  
  6.     Roger Hirst
  7.     CIS:100014,2067
  8.  
  9. Thanks to John W.Small, Power Software for the original idea.
  10.  
  11. The current version is 1.1 which contains a minor bug fix and adds getFirst,
  12. getLast, getNext and getPrev to the Name, Option and Error lists. These
  13. functions allow you more flexibility in the way in which you choose to
  14. process the command line.
  15.  
  16. CL is a total overkill for command line processing but it was interesting
  17. writing it. There are now more functions than can be easily used in one
  18. application. But there is the flexibility for you to pick the method of
  19. access which you prefer and discard the other functions.
  20.  
  21. The following files make up CL
  22.  
  23.     CL.H            -    The class definition header file
  24.     CL.CPP        -    The source file for CL
  25.     CLTEST.CPP    -    The test harness
  26.     CL.DOC        -     This file
  27.  
  28. This command line parser class was designed as an exercise in the use of
  29. Borland's container Array class. You will need access to the Borland
  30. container class libraries in order to build the test program and to
  31. use the code in your own programmes.
  32.  
  33. The public interface to the CmdLn class is designed for simplicity.
  34.  
  35. Any number of command line names and/or options are supported.
  36. Options are identified by a - or / character, which may be changed by
  37. modifying "switches" in CL.CPP.
  38.  
  39. static char *switches  = "/-";
  40.  
  41. A typical command line might be:
  42.  
  43.     CLTEST -v -c /pA5 \dos\test1*.doc -e.XYZ  -gh
  44.  
  45.         Names and options are delimited by whitespace.
  46.  
  47. Member Functions
  48.  
  49.     CmdLn (char *);
  50.  
  51.         The class constructor, taking a set of possible options as its
  52.         parameter. Any option taking an additional argument is followed
  53.         by a colon.
  54.  
  55.             CmdLn CL ("cCe:E:gGhHl:L:o:O:P:p:vVxX");
  56.  
  57.             c, g, h, v and x (upper and lower case) are simple options.
  58.             e, l, o, and p take an additional argument.
  59.  
  60.         Any options not found in the parameter to the constructor are saved
  61.         as Error Options. Thus invalid command line options are not seen by
  62.         the programme but it is possible to determine the number of errors
  63.         and the option characters which caused them.
  64.  
  65.         There are only option errors, names can never be in error (?).
  66.  
  67.         Names containing the wildcard characters ? and * are expanded.
  68.  
  69.     ~CmdLn ();
  70.  
  71.         The class destructor.
  72.  
  73.     char *version ();
  74.  
  75.         Returns a pointer to a string representing the current version number.
  76.  
  77.     int  numNames ();
  78.  
  79.         Returns the number of valid names parsed.
  80.  
  81.     char *getName (int i);
  82.  
  83.         Returns a pointer to the i th name. An invalid value for i returns
  84.         NULL.
  85.  
  86.     char *getFirstName ();
  87.  
  88.         Returns a pointer to the first name in the list or NULL
  89.         if nothing is found.
  90.  
  91.     char *getLastName  ();
  92.  
  93.         Returns a pointer to the last name in the list or NULL
  94.         if nothing is found.
  95.  
  96.     char *getNextName  ();
  97.  
  98.         Returns a pointer to the next name in the list or NULL
  99.         if nothing is found.
  100.  
  101.     char *getPrevName  ();
  102.  
  103.         Returns a pointer to the previous name in the list or NULL
  104.         if nothing is found.
  105.  
  106.     int  numOptions ();
  107.  
  108.         Returns the number of valid options parsed.
  109.  
  110.     char getOption (int i,char *&optarg);
  111.  
  112.         Returns the i th option and any additional argument. An invalid value
  113.         for i returns CL_ENDOFLIST for the option character.
  114.  
  115.     char getFirstOption (char *&optarg);
  116.  
  117.         Returns the first option in the list or CL_ENDOFLIST if nothing is
  118.         found.
  119.  
  120.     char getLastOption  (char *&optarg);
  121.  
  122.         Returns the last option in the list or CL_ENDOFLIST if nothing is
  123.         found.
  124.  
  125.     char getNextOption  (char *&optarg);
  126.  
  127.         Returns the next option in the list or CL_ENDOFLIST if nothing is
  128.         found.
  129.  
  130.     char getPrevOption  (char *&optarg);
  131.  
  132.         Returns the previous option in the list or CL_ENDOFLIST if nothing is
  133.         found.
  134.  
  135.     int  numErrors ();
  136.  
  137.         Returns the number of invalid options parsed.
  138.  
  139.     char getError (int i);
  140.  
  141.         Returns the i th error option detected. An invalid value
  142.         for i returns CL_ENDOFLIST for the option character.
  143.  
  144.     char getFirstError ();
  145.  
  146.         Returns the first error in the list or CL_ENDOFLIST if nothing is
  147.         found.
  148.  
  149.     char getLastError  ();
  150.  
  151.         Returns the last error in the list or CL_ENDOFLIST if nothing is
  152.         found.
  153.  
  154.     char getNextError  ();
  155.  
  156.         Returns the next error in the list or CL_ENDOFLIST if nothing is
  157.         found.
  158.  
  159.     char getPrevError  ();
  160.  
  161.         Returns the next error in the list or CL_ENDOFLIST if nothing is
  162.         found.
  163.  
  164.     void add (char *);
  165.  
  166.         Adds additional items to those parsed from the command line.
  167.         Permits the    same parsing of command line and user entered input.
  168.  
  169.     void printContentsOn (Rostream os);
  170.  
  171.         Prints the contents of the Name, Option and Error arrays.
  172.         Intended for diagnostic purposes.
  173.  
  174.     void clearNames ();
  175.  
  176.         Clears all name entries.
  177.  
  178.     void clearOptions ();
  179.  
  180.         Clears all option entries.
  181.  
  182.     void clearErrors ();
  183.  
  184.         Clears all error option entries.
  185.  
  186.     void clearAll ();
  187.  
  188.         Clears name, option and error entries.
  189.  
  190.     void reset ();
  191.  
  192.         Clears all entries and reparses the command line.
  193.  
  194. CLTEST.CPP
  195.  
  196.     Initialises the command line to respond to the options c,e,g,h,l,o,p,v
  197.     and x. The constructor parses the command line for valid options and
  198.     file names. Any wild card file names are expanded.
  199.  
  200.         CmdLn CL ("cCe:E:gGhHl:L:o:O:P:p:vVxX");
  201.  
  202.     To cope with the situation where the user does not input options and file
  203.     names on the command line the add member function is provided. Options and
  204.     wild card file names are translated by the add function
  205.  
  206.         cout << "Enter additional test fields (Names or Options) - ";
  207.         cin.getline (s,80);
  208.         CL.add (s);
  209.  
  210.     Various tests of the options follow.
  211.  
  212. Additional Notes
  213.  
  214. CL.CPP contains a correction to the Borland Array class. After detaching
  215. an Object from the Array the add member function simply carries on adding to
  216. the end of the array thus generating a sparse Array. This causes great
  217. confusion when printContentsOn or some other function is called which
  218. assumes a dense Array.
  219.  
  220. Note that calls to any of the getNext... getPrev... functions beyond
  221. the begining or end of a list does no harm, CL_ENDOFLIST will be
  222. returned but the index to the array will still be incremented/decremented.
  223. This can cause confusion if you call getNext... beyond the end of
  224. the list and then expect getPrev... to return something sensible
  225. on the first call. It is best to start all sequences of getNext...
  226. or getPrev... with a call to getFirst... or getLast...
  227.  
  228. CL_ENDOFLIST (-1) has been added as the "nothing found" return code
  229. replacing '?' this allows '?' to be used as a command line option.
  230.  
  231.     Normally the question mark would be used to support a help function:
  232.  
  233.         program -?
  234.  
  235. Care should be taken with the signed/unsigned character compiler
  236. option. This can cause the CL_ENDOFLIST test to fail. The test code
  237. was compiled with signed characters. If you need unsigned chars simply
  238. redefine CL_ENDOFLIST.
  239.  
  240.  
  241.  
  242. Roger Hirst
  243. 7th December 1991
  244.