sys-utils/README.shhopt-1.1

   1 shhopt - library for parsing command line options.
   2 ==================================================
   3
   4 This is a set of functions for parsing command line options. Both
   5 traditional one-character options, and GNU-style --long-options are
   6 supported.
   7
   8
   9 What separates this from traditional getopt?
  10 --------------------------------------------
  11
  12 This library does more of the parsing for you. You set up a special
  13 structure describing the names and types of the options you want your
  14 program to support. In the structure you also give addresses of
  15 variables to update or functions to call for the various
  16 options. By calling optParseOptions, all options in argv are parsed
  17 and removed from argv. What is left, are the non-optional arguments to
  18 your program.
  19
  20 The down-side of this, is that you won't be able to make a program
  21 where the position of the options between the non-options are
  22 significant.
  23
  24
  25 Usage
  26 -----
  27
  28 To see how to use this library, take a look at the sample program
  29 example.c.
  30
  31 A brief explanation:
  32
  33 To parse your command line, you need to create and initialize an array
  34 of optStruct's. Each element in the array describes a long and short
  35 version of an option and specifies what type of option it is and how
  36 to handle it.
  37
  38 The structure fields (see also shhopt.h):
  39
  40   `shortName' is the short option name without the leading '-'.
  41
  42   `longName' is the long option name without the leading "--".
  43
  44   `type' specifies what type of option this is. (Does it expect an
  45       argument? Is it a flag? If it takes an argument,what type should
  46       it be?)
  47
  48   `arg' is either a function to be called with the argument from
  49       the commandline, or a pointer to a location in which to store
  50       the value.
  51
  52   `flags' indicates whether `arg' points to a function or a storage
  53       location.
  54
  55 The different argument types:
  56
  57   `OPT_END' flags this as the last element in the options array.
  58
  59   `OPT_FLAG' indicates an option that takes no arguments. If `arg' is
  60       not a function pointer, the value of `arg' will be set to 1 if
  61       this flag is found on the command line.
  62
  63   `OPT_STRING' expects a string argument.
  64
  65   `OPT_INT' expects an int argument.
  66
  67   `OPT_UINT' expects an unsigned int argument.
  68
  69   `OPT_LONG' expects a long argument.
  70
  71   `OPT_ULONG' expects an unsigned long argument.
  72
  73 The different flag types:
  74
  75   `OPT_CALLFUNC' indicates that `arg' is a function pointer. If this
  76       is not given, `arg' is taken as a pointer to a variable.
  77
  78
  79 Notes
  80 -----
  81
  82 * A dash (`-') by itself is not taken as any kind of an option, as
  83   several programs use this to indicate the special files stdin and
  84   stdout. It is thus left as a normal argument to the program.
  85
  86 * Two dashes (`--') as an argument, is taken to mean that the rest of
  87   the arguments should not be scanned for options. This simplifies
  88   giving names of files that start with a dash.
  89
  90 * Short (one-character) options accept parameters in two ways, either
  91   directly following the option in the same argv-entry, or in the next
  92   argv-entry:
  93
  94         -sPARAMETER
  95         -s PARAMETER
  96
  97 * Long options accept parameters in two ways:
  98
  99         --long-option=PARAMETER
 100         --long-option PARAMETER
 101
 102   To follow the GNU-tradition, your program documentation should use
 103   the first form.
 104
 105 * Several one-character options may be combined after a single
 106   dash. If any of the options requires a parameter, the rest of the
 107   string is taken as this parameter. If there is no "rest of the
 108   string", the next argument is taken as the parameter.
 109
 110 * There is no support for floating point (double) arguments to
 111   options. This is to avoid unnecessary linking with the math
 112   library. See example.c for how to get around this by writing a
 113   function converting a string argument to a double.
 114
 115
 116 Portability
 117 -----------
 118
 119 If your libc lacks strtoul, you will need to link with GNU's -liberty,
 120 that may be found by anonymous ftp to prep.ai.mit.edu:/pub/gnu
 121
 122 The library has (more or less recently) been compiled and `tested' on
 123 the following systems:
 124
 125         IRIX Release 5.3 IP22
 126         Linux 1.2.9
 127         SunOS Release 4.1.3_U1 (-liberty needed)
 128         ULTRIX V4.4 (Rev. 69)
 129
 130 All compilations were done using GNU's gcc, and GNU's make.
 131
 132
 133 Author
 134 ------
 135
 136 The program is written by
 137
 138         Sverre H. Huseby
 139         Maridalsvn. 122, leil. 101
 140         N-0461 Oslo
 141         Norway
 142
 143         sverrehu@ifi.uio.no
 144         http://www.ifi.uio.no/~sverrehu/
 145
 146 You can use and copy this for free. If you decide to use it, please do
 147 me three small favours:
 148
 149         1. Tell me! (E-mail, postcard, letter, whatever. If you wish
 150            to give me something, please send a bottle of your
 151            favourite beer (making this BeerWare))
 152         2. Let your friends and favourite download site have a copy!
 153            (with all files intact, please..)
 154         3. Report any bugs you find!
 155