home *** CD-ROM | disk | FTP | other *** search
/ Power-Programmierung / CD2.mdf / c / library / dos / cmdline / cmdparse / cmdparse.doc < prev    next >
Encoding:
Text File  |  1989-12-02  |  6.5 KB  |  159 lines
  1.  
  2. CMDPARSE                   David K. Rich                            Page 1
  3.  
  4. When writing programs which take parameters from the DOS call line, I found
  5. myself constantly re-inventing a way to determine what was on the command
  6. line.  Finally, I decided that it was time to build that wheel
  7. once-and-for-all.  This set of functions for Turbo (ANSI?) C is the result.
  8.  
  9. In the ZIP file for CMDPARSE you should find:
  10.  
  11.           CMDPARSE.C           The source code for the functions.  It could
  12.                                probably be tightened, but has the benefit
  13.                                that it works.  Please don't fiddle with it
  14.                                and then distribute the modified version as
  15.                                CMDPARSE, give any modified version another
  16.                                name and claim it yourself (with
  17.                                acknowledgement)
  18.  
  19.           CMDPARSE.OBJ         The TurboC 2.0 OBJ file which can be linked
  20.                                with your program or placed in your LIB file.
  21.  
  22.           CMDPARSE.H           A header file which should be included in
  23.                                any code that references CMDPARSE.
  24.  
  25.           CMDPARSE.DOC         This file.
  26.  
  27.           CPDEMO.EXE           A program which demonstrates these functions.
  28.                                Try it with various command parameters &
  29.                                options.
  30.  
  31.  
  32.  
  33. CMDPARSE                   David K. Rich                            Page 2
  34.  
  35.  
  36. What follows was excerpted from the comments in the code.  It should
  37. adequately document things.
  38.  
  39. First, several assumptions are made by these functions:
  40.  
  41.                   All parameters are separated by one or more spaces. The
  42.                    number of spaces is not significant and the spaces are
  43.                    not a part of the parameter.
  44.  
  45.                   No more than 20 parameters and options will be passed.
  46.  
  47.                   Options are indicated by a leading switch character,
  48.                    either a slash (/) or a dash (-).
  49.  
  50.                   Slash-delimited options may be appended to a field without
  51.                    a separating space, vis.
  52.  
  53.                             param/n        command/c
  54.  
  55.                   Dash-delimited options will always be preceded by a space.
  56.  
  57.                   Options always are terminated by a space.
  58.  
  59.                   Options can take one of three forms:
  60.  
  61.                            Switch+character    example:   /n
  62.                            Switch+string       example:   /noi
  63.                            Switch+expression   example:   /VIDEO=MONO
  64.  
  65.                   The switch+expression options may NOT have spaces before &/or
  66.                     after the = sign.
  67.  
  68.                   No case conversions are done.
  69.  
  70. Two global arrays are defined, which can be referred to in your code because
  71. of extern declarations in CMDPARSE.H
  72.  
  73.       char *cmd_arg[22]           Pointers to the READ-ONLY strings for each
  74.                                   parameter.  These are read-only because
  75.                                   the pointers are all to substrings of
  76.                                   combined_cmd.
  77.  
  78.       int arg_type[22]            A parallel array to cmd_arg, one entry for
  79.                                   each item in cmd_arg.  arg_type[] will be
  80.  
  81.                                                0 = a parameter
  82.                                                1 = an option
  83.  
  84. You may never have to directly refer to these arrays because of the
  85. functions included.
  86.  
  87.  
  88.  
  89. CMDPARSE                   David K. Rich                            Page 3
  90.  
  91. The functions are as follows:
  92.  
  93.     int cmd_init(void)           This function MUST be called before any
  94.                                  of the other functions.  It retrieves the
  95.                                  call line and parses it into the arrays.
  96.  
  97.     char *get_param(int param_number)
  98.  
  99.                                  This function will return a pointer to the
  100.                                  READ-ONLY string for the parameter whose
  101.                                  number is passed.  Note that parameter #0
  102.                                  is the program name, parameter #1 is the
  103.                                  first parameter after the program name,
  104.                                  etc.
  105.  
  106.                                  Returns NULL if parameter doesn't exist.
  107.  
  108.                                  If options are interspersed with parameters
  109.                                  they are not counted as parameter numbers.
  110.  
  111.                                  Execute CPDEMO with parameters, etc. to
  112.                                  see the effect of various command lines.
  113.  
  114.     int if_option(char *search_string)
  115.  
  116.                                  Scans all option fields and tests the first
  117.                                  character(s) following the switch to see if
  118.                                  they match.  The number of characters checked is determined
  119.                                  by the number of characers in the test
  120.                                  string passed.
  121.  
  122.                                  The comparison is case sensitive.
  123.  
  124.                                  Returns:
  125.  
  126.                                     0 if not found
  127.                                     array subscript in cmd_arg[] if found
  128.  
  129.     int if_optioni(char *search_string)
  130.  
  131.                                  Same as if_option(), except the comparison
  132.                                  is case-insensitive.
  133.  
  134.  
  135.  
  136. CMDPARSE                   David K. Rich                            Page 4
  137.  
  138.  
  139.     char *opt_value(char *search_string)
  140.  
  141.                                  Returns a pointer to the READ-ONLY string
  142.                                  containing the rvalue of a /optname=value
  143.                                  option type. Scans all option fields and
  144.                                  tests the first character(s) following the
  145.                                  switch to see if they match.  The number of
  146.                                  characters checked is determined by the
  147.                                  number of characers in the test string
  148.                                  passed.
  149.  
  150.                                  The comparison is case sensitive.
  151.  
  152.     char *opt_valuei(char *search_string)
  153.  
  154.                                  Same as opt_value(), except the comparison
  155.                                  is case-insensitive.
  156.  
  157.  
  158.  
  159.