home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / snip9707.zip / GETOPTS.MAN < prev    next >
Text File  |  1997-07-05  |  12KB  |  293 lines
  1. +++Date last modified: 05-Jul-1997
  2.  
  3. FUNCTION:   getopts()
  4.  
  5.  
  6. ABSTRACT:   Command line argument processor. Handles switches, options,
  7.             literal data, file names with or without wildcards. Switches and
  8.             options may have default values and range checking is supported.
  9.             Numeric arguments may be expressions.
  10.  
  11.  
  12. CALL WITH:  int getopts(int argc, char *argv[])
  13.  
  14.             argc and argv are passed from main()
  15.  
  16.             Option switches set up in an array of Option_Tag structures.
  17.  
  18.  
  19. PROTOTYPED: In GETOPTS.H. Also see GETOPTST.C for a working sample
  20.             application.
  21.  
  22.  
  23. ALSO USES:  FNSPLIT.C, FERRORF.C, ERR_EXIT.C, UNIX2DOS.C, DBLROUND.C, EVAL.C,
  24.             and RMALLWS.C.
  25.  
  26.  
  27. PORTABILITY:      Although written for DOS, getopts() should port with little
  28.                   effort to other environments. The only significant barrier
  29.                   to portability is directory and filename processing.
  30.  
  31.  
  32. PROCESSING LITERAL DATA AND FILE NAMES
  33. USING getopts() WITHOUT OPTION PROCESSING:
  34. ------------------------------------------
  35.  
  36. You can call getopts() without option processing by simply adding the
  37. following line to your program:
  38.  
  39. struct Option_Tag options[] = {{ NUL, False_, Error_Tag, NULL, NULL,
  40.                                  NULL, NULL}};
  41.  
  42. This is an empty options list which tells getopts() not to look for options.
  43. When called this way, only the global xargc and xargv[] data are saved.
  44.  
  45. If xarg processing is on, all arguments will be treated as file names and
  46. getopts will try to expand them. This is the default operation. To suppress
  47. argument expansion, add the following line to your program:
  48.  
  49. xargs_on = False_;
  50.  
  51. Using the xargs_on variable, it is even possible to add a command line option
  52. which will turn xargs processing on or off based on a specific command. Since
  53. options are processed left-to-right, all arguments preceding such a switch
  54. may be processed differently from arguments following the switch. See the
  55. section below on options processing for more information on specifying
  56. command line options.
  57.  
  58. When xargs processing is active, the global variable xargc will be the total
  59. number of arguments returned, including expanded filenames, plus 1. The full
  60. list of arguments, including expanded filenames, is returned in the global
  61. xargv array. Just as with argv, xargv[0] is the executing program's file name,
  62. copied from argv[0].
  63.  
  64. If xargs processing is turned off, or if the arguments cannot be expanded,
  65. the xargv array will hold the same contents as the original argv array. Note
  66. that command line options are stripped from the xargv array, so if your
  67. command line had 10 arguments, of which 5 were options, the xargv array would
  68. contain only 6 elements (remember xargv[0]), assuming no wildcard expansion
  69. occurred.
  70.  
  71.  
  72. PROCESSING OPTIONS USING getopts():
  73. -----------------------------------
  74.  
  75. Each program using getopts() must specify an options[] array of Option_Tag
  76. structures. Each of these structures must contain the following 7 fields:
  77.  
  78. Field 1 -   An integer specifying the letter used to control the option. For
  79.             example if you wanted to add a optional filename specification
  80.             using "-Ofilename", you would place 'O' in field 1.
  81.  
  82. Field 2 -   A Boolean_T type field (see SNIPTYPE.H) which controls whether
  83.             the option is case sensitive. In the above example, specifying
  84.             False_ in this field would also cause "-ofilename" to be
  85.             recognized.
  86.  
  87. Field 3 -   This field contains the enumerated type of data to be changed.
  88.             Valid values are:
  89.  
  90.             Boolean_Tag Used to specify True_/False_ switches.
  91.             Int_Tag     Used to specify int values.
  92.             Short_Tag   Used to specify signed short values.
  93.             Long_Tag    Used to specify signed long values.
  94.             Byte_Tag    Used to specify unsigned char values.
  95.             Word_Tag    Used to specify unsigned short values.
  96.             DWord_Tag   Used to specify unsigned long values.
  97.             Float_Tag   Used to specify float values
  98.             DFloat_Tag  Used to specify double values.
  99.             String_Tag  Used to specify strings (character arrays).
  100.             Error_Tag   Used only in terminating records (see above).
  101.  
  102. Field 4 -   The address where the option data is to be stored.
  103.  
  104. Field 5 -   If not NULL, this address points to a string specifying the
  105.             minimum allowable value for the option. In the case of boolean
  106.             variables and strings, this field is ignored. The format of this
  107.             string is the same as for a command line specification. See the
  108.             section on type formatting below for further details.
  109.  
  110. Field 6 -   If not NULL, this address points to a string specifying the
  111.             maximum allowable value for the option. In the case of boolean
  112.             variables and strings, this field is ignored. The format of this
  113.             string is the same as for a command line specification. See the
  114.             section on type formatting below for further details.
  115.  
  116. Field 7 -   If not NULL, this address points to a string specifying the
  117.             default value to be assigned to the datum. In the case of boolean
  118.             data, this field is ignored. In the case of numeric data, the
  119.             format of this string is the same as for a command line
  120.             specification. See the section on type formatting below for
  121.             further details.
  122.  
  123. Build your options[] array by specifying each option structure. When you're
  124. done, terminate the array with a terminating record as shown above. See the
  125. GETOPTST.C test file for an example.
  126.  
  127.  
  128. OPTION STRING FORMATTING BY TYPE:
  129. ---------------------------------
  130.  
  131. Boolean_Tag       N.A.
  132.  
  133. Int_Tag           Decimal numeric expression.
  134.  
  135. Short_Tag         Decimal numeric expression.
  136.  
  137. Long_Tag          Decimal numeric expression.
  138.  
  139. Byte_Tag          Hexidecimal numeric constant.
  140.  
  141. Word_Tag          Hexidecimal numeric constant.
  142.  
  143. DWord_Tag         Hexidecimal numeric constant.
  144.  
  145. Float_Tag         Decimal numeric expression.
  146.  
  147. DFloat_Tag        Decimal numeric expression.
  148.  
  149. String_Tag        String literal.
  150.  
  151.  
  152. Hexidecimal numeric constants consist of 2-8 hexidecimal (depending on the
  153. data type) digits, with or without an optional trailing 'h'.
  154.  
  155.  
  156. String literals are saved just as typed. The only problem is with strings
  157. containing spaces. Most operating systems split command line arguments at
  158. whitespace, so if you wanted to specify a string containing spaces, the
  159. entire argument, including the switch itself, must be enclosed in quotes, e.g.
  160.  
  161. "-oThis is a string".
  162.  
  163.  
  164. Decimal numeric expressions are processed by EVAL.C and may therefore consist
  165. of any numerical expression, either a constant or mathematical formula,
  166. conforming to the evaluate() function's syntax. Note that since the numeric
  167. expression starts out as a string, the same limitations regard embedded
  168. spaces apply.
  169.  
  170.  
  171.  
  172. SPECIAL OPTIONS CONSIDERATIONS:
  173. -------------------------------
  174.  
  175. All options are of the basic form, <switch_char><option>, and are processed
  176. left-to-right in sequence. The getopts() function allows the use of '-' (DOS-
  177. style) or '/' (Unix-style) option switch characters. The response file lead-
  178. in character, '@' is also treated as an option switch character. Should you
  179. need to enter a filename which uses any of these three switch characters,
  180. simply precede it with a '-'. Thus getopts() will perform the translation, e.g.
  181.  
  182. --file.ext  =>    -file.ext
  183. -@file.ext  =>    @file.ext
  184.  
  185. Per standard Unix practice, an option consisting only of back-to-back switch
  186. characters, typically "--", is interpreted as a command to turn off further
  187. option processing. Therefore a command tail consisting of...
  188.  
  189. -ofoo -ibar -xyz -- -oops
  190.  
  191. ...where "-o", "-i", and "-x" are valid option characters defined in the
  192. options[] array, would process the first three options, then return the fifth
  193. argument as the string literal "-oops" in the xargv array.
  194.  
  195. Boolean options take the extended form, <switch_char><option>[<action>],
  196. where the optional third action switch controls whether to turn the switch
  197. off (the default action is to turn it on). Thus if you have a boolean option
  198. defined which is controlled by the letter, 'a',
  199.  
  200. -a    turns on the option, while
  201. -a-   turns off the option.
  202.  
  203. The getopts() function does not allow for spaces between the switch character
  204. and the following argument. Therefore, if you have defined an option of type
  205. double, which is controlled by the letter, 'n',
  206.  
  207. -n98.6      is valid, while
  208. -n 123.45   is invalid.
  209.  
  210. All options except boolean switches allow a default value to be specified in
  211. the options[] array. You thus have 3 possible actions with two effective
  212. defaults. Consider the following options[] array and specified values:
  213.  
  214. double num       = 3.14159;
  215. char   numdflt[] = "2.71828";
  216. char   nummin[]  = "-100.0";
  217. char   nummax[]  = "1e6";
  218.  
  219. struct Option_Tag options[] = {                 /* Valid options        */
  220.       {
  221.             'N',                                /* Option letter        */
  222.             False_,                             /* Case sensitivity    */
  223.             DFloat_Tag,                         /* Data type            */
  224.             (void *)&num,                       /* Storage address      */
  225.             nummin,                             /* Range - min          */
  226.             nummax,                             /* Range - max          */
  227.             numdflt                             /* Default value        */
  228.       },
  229.       {
  230.             NUL,                                /* Terminating record   */
  231.             False_,
  232.             Error_Tag,
  233.             NULL,
  234.             NULL,
  235.             NULL,
  236.             NULL
  237.       }
  238. };
  239.  
  240. If you enter a non-boolean option with no value, the default value will be
  241. used. If no default value is specified, an error will be returned. Therefore
  242. the following arguments will result in the specified assignment to the num
  243. variable:
  244.  
  245. [no "-n" options specified]   num = 3.14159     (initialized default value)
  246. -n                            num = 2.71828     (option default value)
  247. -n((1+sqrt(5))/2              num = 1.618034    (note use of formula!)
  248.  
  249. Also note that in the code sample above, minimum and maximum values are
  250. specified for num. If range checking is enabled (i.e. if the min and/or max
  251. fields are non-NULL) an option which specifies an out-of-bounds value will be
  252. coerced to the nearest bounds value. To check if this has happened, examine
  253. the getopts_range_err global variable. If True_, a range error occurred and a
  254. value had to be coerced.
  255.  
  256.  
  257. USING RESPONSE FILES:
  258. ---------------------
  259.  
  260. Often times, you need to specify more options than can fit on the command
  261. line, therefore getopts() supports the use of response files. To use a
  262. response file, simply enter @<file_name> in the command line. As with all
  263. options, response files are processed left-to-right and multiple response
  264. files may be specified. The format of a response file is one option on each
  265. line of the file, with each line processed top-to-bottom. For example, here
  266. is a response file I used when testing getopts() with the GETOPTST test
  267. program:
  268.  
  269. ---[ begin ]---
  270. -a-
  271. -b
  272. -c987
  273. -d98765
  274. -e(1+sqrt(5))/2
  275. -f0cch
  276. -gThis is a response file
  277. *.h
  278. ----[end ]----
  279.  
  280. Also note that in response files, strings should *not* be quoted!
  281.  
  282.  
  283. HELPER FUNCTIONS:
  284. -----------------
  285.  
  286. GETOPTS.C also contains a helper function you may find handy to use in your
  287. own code. Normally, the evaluate() function takes a string and a storage
  288. address, and returns a status code. Within getopts(), we use getopts_eval()
  289. which takes the string to evaluate and simply returns a double. In the event
  290. of error, ErrExit() is called to terminate the program after telling you
  291. which expression it could not evaluate. Notice how getopts_eval() is used
  292. within the GETOPTST.C demo/test program.
  293.