home *** CD-ROM | disk | FTP | other *** search
/ Simtel MSDOS - Coast to Coast / simteldosarchivecoasttocoast2.iso / c / getargs.doc < prev    next >
Text File  |  1994-03-07  |  5KB  |  127 lines
  1. getargs - command line processor for C programs
  2.  
  3. A command line switch is an argument preceded by a '-' that modifies
  4. the way in which a program works.  This command line processor is a package of
  5. subroutines.  Access to the routines is through one call to the procedure
  6. getargs().  The routines are table driven.  Getargs() removes switches from the
  7. command line as it works and leaves other arguments (the ones not preceded by
  8. '-') alone.
  9.  
  10. When getargs() finds an error, it prints an error message to stderr listing all
  11. the legal switches, descriptions of each, and their default values.  It
  12. then terminates with exit(1), which should close any open files.
  13.  
  14. To use getargs() you must: (1) Set up a table to tell the routine what switches
  15. to expect, (2) Declare the associated variables and initialize them to their
  16. default values, and (3) call the routine itself somewhere early in the main()
  17. routine.  The file getargs.h contains the #defines and typedefs needed to
  18. create the command switch descriptor table.  This table is an array of
  19. structures:
  20.  
  21.     typedef struct
  22.     {    unsigned    arg            ; /* command line switch */
  23.         unsigned    type        ; /* variable type (of those #defined above) */
  24.         int            *variable    ; /* pointer to variable */
  25.         char        *errmsg        ; /* pointer to error message */
  26.     } ARG;
  27.  
  28. The arg field is a character that identifies the switch on the command line. 
  29. In the following descriptions this character is represented by <switch>.  The
  30. type field may take any one of five values, all #defined in getargs.h.
  31.  
  32. INTEGER switches take the form
  33.     -<switch><number>
  34. Numbers preceded by 0x are hex, by 0 without the x, octal.  All others are
  35. decimal.  The number is terminated by any character not legal in the indicated
  36. radix.  The int pointed to by the variable field of the ARG structure will be
  37. set to the value of the <number>.  If the <number> isn't typed on the command
  38. line, *variable is set to 0.
  39.  
  40. BOOLEAN switches will cause *variable to be set to 1 if present.  If the switch
  41. is absent, *variable is not modified.
  42.  
  43. CHARACTER switches take the form
  44.     -<switch><character>
  45. When the switch is found on the command line, *variable is set to the character
  46. immediately following the <switch> character.
  47.  
  48. STRING switches take the form
  49.     -<switch><string>
  50. When the switch is found on the command line, the character pointer pointed to
  51. by the variable field is set to point at a string consisting of all characters
  52. following (but not including) the <switch> character up to the end of the
  53. current argument (not to the end of the command line).
  54.  
  55. PROC switches take the form
  56.     -<switch><anything>
  57. Here, the variable field is a pointer to a subroutine that is called indirectly
  58. as soon as the switch is encountered on the command line.  A pointer to <anything>
  59. is passed to this subroutine as a single argument.  It is the responsibility
  60. of the called subroutine to parse <anything> as appropriate.
  61.  
  62. The errmsg field in the table is used to print an error message if an undefined
  63. switch is found.
  64.  
  65. Switches may be combined into a single argument, but string switches must be
  66. last one because all following characters will be considered part of the
  67. <string>.  When defining a STRING switch in the table, be sure to cast the
  68. variable into an integer pointer.  See argtest.c for an example.
  69.  
  70. EXAMPLES
  71.  
  72. Argtest is an example of how to use getargs().  Argtab is the table which
  73. defines the legal switches.  Main() prints the command line before
  74. and after calling getargs(), and prints the values of the associated
  75. variables after the call.  Similarly, proc() displays its argument when called.
  76.  
  77. The following execution illustrates all five of the legal switches:
  78.  
  79.     A>argtest -b -pFISH alpha -shello_world -p&CHIPS -n0xff beta
  80.     argc=8.  command line before processing: 
  81.         "argtest -b -pFISH alpha -shello_world -p&CHIPS -n0xff beta "
  82.  
  83.     procedure called as follows: proc("FISH") 
  84.     procedure called as follows: proc("&CHIPS") 
  85.  
  86.     variable values after processing:
  87.         boolarg = TRUE 
  88.         chararg = & 
  89.         intarg  = 255 
  90.         strarg  = hello_world 
  91.  
  92.     argc=3.  command line after processing: 
  93.         "argtest alpha beta "
  94.  
  95. Arguments may be combined as follows:
  96.  
  97.     A>argtest alpha -bcYn98sapple_pie
  98.     argc=3.  command line before processing: 
  99.         "argtest alpha -bcYn98sapple_pie "
  100.  
  101.  
  102.     variable values after processing:
  103.         boolarg = TRUE 
  104.         chararg = Y 
  105.         intarg  = 98 
  106.         strarg  = apple_pie 
  107.  
  108.     argc=2.  command line after processing: 
  109.         "argtest alpha "
  110.  
  111. This execution illustrates the error message:
  112.  
  113.     A>argtest -y
  114.     argc=2.  command line before processing: 
  115.         "argtest -y "
  116.  
  117.     Illegal argument 'y'.  Legal arguments are:
  118.  
  119.     -b      boolean argument                         (value is FALSE)
  120.     -c<c>   character argument                       (value is &    )
  121.     -n<num> integer argument                         (value is 0    )
  122.     -s<str> string argument                          (value is "do wha")
  123.     -p<str> procedure argument                      
  124.  
  125. This documentation is a condensation of the article by Allen Holub in Dr. 
  126. Dobb's Journal #103 (May 1985).
  127.