home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / snpd9707.zip / GETOPTSL.MAN < prev    next >
Text File  |  1997-07-05  |  6KB  |  154 lines
  1. +++Date last modified: 05-Jul-1997
  2.  
  3. FUNCTION:   getopts_lite()
  4.  
  5.  
  6. ABSTRACT:   Command line argument processor. A subset of getopts() (also in
  7.             SNIPPETS), handles switches, options, literal data, file names
  8.             with or without wildcards. Only statically defined default values
  9.             are supported. Range checking and response files are not
  10.             supported.
  11.  
  12.  
  13. CALL WITH:  int getopts_lite(int argc, char *argv[])
  14.  
  15.             argc and argv are passed from main()
  16.  
  17.             Option switches set up in an array of Option_Tag structures.
  18.  
  19.  
  20. PROTOTYPED: In GETOPTSL.H.
  21.  
  22.  
  23. ALSO USES:  DIRPORT.H
  24.  
  25.  
  26. PORTABILITY:      Although written for DOS, getopts_lite() should port with
  27.                   little effort to other environments. The only significant
  28.                   barrier to portability is directory and filename
  29.                   processing.
  30.  
  31.  
  32. PROCESSING LITERAL DATA AND FILE NAMES
  33. USING getopts_lite() WITHOUT OPTION PROCESSING:
  34. -----------------------------------------------
  35.  
  36. You can call getopts_lite() without option processing by simply adding the
  37. following line to your program:
  38.  
  39. struct Option_Tag options[] = {{ NUL, Error_Tag, NULL, 0}};
  40.  
  41. This is an empty options list which tells getopts_lite() not to look for
  42. options.  When called this way, only the global xargc and xargv[] data are
  43. saved.
  44.  
  45. All arguments will be treated as file names and getopts will try to expand
  46. them. See the section below on options processing for more information on
  47. specifying command line options.
  48.  
  49. Using xargs processing, the global variable xargc will be the total number of
  50. arguments returned, including expanded filenames, plus 1. The full list of
  51. arguments, including expanded filenames, is returned in the global xargv
  52. array. Just as with argv, xargv[0] is the executing program's file name,
  53. copied from argv[0].
  54.  
  55. If the arguments cannot be expanded, the xargv array will hold the same
  56. contents as the original argv array. Note that command line options are
  57. stripped from the xargv array, so if your command line had 10 arguments, of
  58. which 5 were options, the xargv array would contain only 6 elements (remember
  59. xargv[0]), assuming no wildcard expansion occurred.
  60.  
  61.  
  62. PROCESSING OPTIONS USING getopts_lite():
  63. ----------------------------------------
  64.  
  65. Each program using getopts_lite() must specify an options[] array of
  66. Option_Tag structures. Each of these structures must contain the following 7
  67. fields:
  68.  
  69. Field 1 -   An integer specifying the letter used to control the option. For
  70.             example if you wanted to add a optional filename specification
  71.             using "-Ofilename", you would place 'O' in field 1. Note that
  72.             options are case-sensitive, to make a case-insensitive option,
  73.             you need to create two entries, in this example, one for 'O' and
  74.             one for 'o'.
  75.  
  76. Field 2 -   This field contains the enumerated type of data to be changed.
  77.             Valid values are:
  78.  
  79.             Boolean_Tag Used to specify True_/False_ switches.
  80.             Word_Tag    Used to specify unsigned short values.
  81.             DWord_Tag   Used to specify unsigned long values.
  82.             Double_Tag  Used to specify double values.
  83.             String_Tag  Used to specify strings (character arrays).
  84.             Error_Tag   Used only in terminating records (see above).
  85.  
  86. Field 3 -   The address where the option data is to be stored.
  87.  
  88. Field 4 -   Specifies the size of the buffer (used only for strings).
  89.  
  90. Build your options[] array by specifying each option structure. When you're
  91. done, terminate the array with a terminating record as shown above. See the
  92. GETOPTST.C test file for an example.
  93.  
  94.  
  95. OPTION STRING FORMATTING BY TYPE:
  96. ---------------------------------
  97.  
  98. Boolean_Tag       N.A.
  99.  
  100. Word_Tag          Decimal numeric constant.
  101.  
  102. DWord_Tag         Decimal numeric constant.
  103.  
  104. Double_Tag        Decimal numeric constant.
  105.  
  106. String_Tag        String literal.
  107.  
  108.  
  109. String literals are saved just as typed. The only problem is with strings
  110. containing spaces. Most operating systems split command line arguments at
  111. whitespace, so if you wanted to specify a string containing spaces, the
  112. entire argument, including the switch itself, must be enclosed in quotes, e.g.
  113.  
  114. -o"This is a string".
  115.  
  116.  
  117.  
  118. SPECIAL OPTIONS CONSIDERATIONS:
  119. -------------------------------
  120.  
  121. All options are of the basic form, <switch_char><option>, and are processed
  122. left-to-right in sequence. The getopts_lite() function allows the use of '-'
  123. (DOS- style) or '/' (Unix-style) option switch characters. Should you need to
  124. enter a filename which uses a switch character, simply precede it with a '-'.
  125. Thus getopts_lite() will perform the translation, e.g.
  126.  
  127. --file.ext  =>    -file.ext
  128.  
  129. Per standard Unix practice, an option consisting only of back-to-back switch
  130. characters, typically "--", is interpreted as a command to turn off further
  131. option processing. Therefore a command tail consisting of...
  132.  
  133. -ofoo -ibar -xyz -- -oops
  134.  
  135. ...where "-o", "-i", and "-x" are valid option characters defined in the
  136. options[] array, would process the first three options, then return the fifth
  137. argument as the string literal "-oops" in the xargv array.
  138.  
  139. Boolean options take the extended form, <switch_char><option>[<action>],
  140. where the optional third action switch controls whether to turn the switch
  141. off (the default action is to turn it on). Thus if you have a boolean option
  142. defined which is controlled by the letter, 'a',
  143.  
  144. -a    turns on the option, while
  145. -a-   turns off the option.
  146.  
  147. The getopts_lite() function does not allow for spaces between the switch
  148. character and the following argument. Therefore, if you have defined an
  149. option of type double, which is controlled by the letter, 'n',
  150.  
  151. -n98.6      is valid, while
  152. -n 123.45   is invalid.
  153.  
  154.