| 1 |
Shhopt was originally written by Sverre H. Huseby, and extended by |
| 2 |
Bryan Henderson starting in March 2000 for use in Netpbm. |
| 3 |
|
| 4 |
Below is the README file from Huseby's package. |
| 5 |
|
| 6 |
The file LICENSE.TXT in this directory contains the license (the |
| 7 |
Artistic License) under which Bryan took and redistributed Shhopt and |
| 8 |
the license under which Bryan offers the modified Shhopt to others. |
| 9 |
|
| 10 |
Bryan made the following changes to shhopt for Netpbm. |
| 11 |
|
| 12 |
- OPT_FLOAT (floating point number) data type added |
| 13 |
|
| 14 |
- symbols prefixed with "pm_". |
| 15 |
|
| 16 |
- pm_optParseOptions2() added. Advantages over pm_optParseOptions(): You |
| 17 |
can have a syntax where there is no such thing as a short option |
| 18 |
(e.g. -a. Maybe stacked like -tanp). Then the long options can |
| 19 |
have either 1 or 2 dashes (e.g. -width or --width). Of course, -w |
| 20 |
could be an abbreviation of -width; that's not the same thing as a |
| 21 |
short option. |
| 22 |
|
| 23 |
- pm_optParseOptions3() added. Advantages over pm_optParseOptions2(): |
| 24 |
Tells you whether (how many times, actually) an option was |
| 25 |
specified - no need to play games with defaults. Also, no need |
| 26 |
to initialize an option value variable. |
| 27 |
|
| 28 |
- optStruct longName changed from char * to const char * to avoid |
| 29 |
compiler warnings (with -Wwrite-strings) when you assign a string |
| 30 |
literal to it (which is the normal case). |
| 31 |
|
| 32 |
- OPTENTRY/OPTENT3 macros added for declaring the option definition |
| 33 |
array. |
| 34 |
|
| 35 |
- replace isdigit() with ISDIGIT() from Netpbm nstring.h so weird |
| 36 |
8-bit characters don't cause incorrect results. |
| 37 |
|
| 38 |
- OPT_NAMELIST and OPT_STRINGLIST added. |
| 39 |
|
| 40 |
WARNING: pm_optParseOptionsX modify their argv argument (the array of |
| 41 |
pointers, not the the things to which they point). |
| 42 |
|
| 43 |
WARNING: The option values returned by pm_optParseOptionsX for options of type |
| 44 |
OPT_STRING reside in the program's argument space (the memory addressed by the |
| 45 |
program's argv array). |
| 46 |
|
| 47 |
------------------------------------------------------------------------------ |
| 48 |
|
| 49 |
|
| 50 |
shhopt - library for parsing command line options. |
| 51 |
================================================== |
| 52 |
|
| 53 |
This is a set of functions for parsing command line options. Both |
| 54 |
traditional one-character options, and GNU-style --long-options are |
| 55 |
supported. |
| 56 |
|
| 57 |
|
| 58 |
What separates this from traditional getopt? |
| 59 |
-------------------------------------------- |
| 60 |
|
| 61 |
This library does more of the parsing for you. You set up a special |
| 62 |
structure describing the names and types of the options you want your |
| 63 |
program to support. In the structure you also give addresses of |
| 64 |
variables to update or functions to call for the various |
| 65 |
options. By calling optParseOptions, all options in argv are parsed |
| 66 |
and removed from argv. What is left, are the non-optional arguments to |
| 67 |
your program. |
| 68 |
|
| 69 |
The down-side of this, is that you won't be able to make a program |
| 70 |
where the position of the options between the non-options are |
| 71 |
significant. |
| 72 |
|
| 73 |
shhopt is distributed under the "Artistic license" (aka. the Perl |
| 74 |
license), which IMHO gives more freedom than GPL or LGPL. For a copy |
| 75 |
of the Artistic license, see |
| 76 |
|
| 77 |
http://www.opensource.org/licenses/artistic-license.html |
| 78 |
|
| 79 |
For more information on Open Source licenses, go to |
| 80 |
|
| 81 |
http://www.opensource.org/licenses/ |
| 82 |
|
| 83 |
|
| 84 |
Usage |
| 85 |
----- |
| 86 |
|
| 87 |
To see how to use this library, take a look at the sample program |
| 88 |
example.c. |
| 89 |
|
| 90 |
A brief explanation: |
| 91 |
|
| 92 |
To parse your command line, you need to create and initialize an array |
| 93 |
of optStruct's. Each element in the array describes a long and short |
| 94 |
version of an option and specifies what type of option it is and how |
| 95 |
to handle it. |
| 96 |
|
| 97 |
The structure fields (see also shhopt.h): |
| 98 |
|
| 99 |
`shortName' is the short option name without the leading '-'. |
| 100 |
|
| 101 |
`longName' is the long option name without the leading "--". |
| 102 |
|
| 103 |
`type' specifies what type of option this is. (Does it expect an |
| 104 |
argument? Is it a flag? If it takes an argument, what type |
| 105 |
should it be?) |
| 106 |
|
| 107 |
`arg' is either a function to be called with the argument from |
| 108 |
the commandline, or a pointer to a location in which to store |
| 109 |
the value. |
| 110 |
|
| 111 |
`flags' indicates whether `arg' points to a function or a storage |
| 112 |
location. |
| 113 |
|
| 114 |
The different argument types: |
| 115 |
|
| 116 |
`OPT_END' flags this as the last element in the options array. |
| 117 |
|
| 118 |
`OPT_FLAG' indicates an option that takes no arguments. If `arg' is |
| 119 |
not a function pointer, the value of `arg' will be set to 1 if |
| 120 |
this flag is found on the command line. |
| 121 |
|
| 122 |
`OPT_STRING' expects a string argument. |
| 123 |
|
| 124 |
`OPT_INT' expects an int argument. |
| 125 |
|
| 126 |
`OPT_UINT' expects an unsigned int argument. |
| 127 |
|
| 128 |
`OPT_LONG' expects a long argument. |
| 129 |
|
| 130 |
`OPT_ULONG' expects an unsigned long argument. |
| 131 |
|
| 132 |
The different flag types: |
| 133 |
|
| 134 |
`OPT_CALLFUNC' indicates that `arg' is a function pointer. If this |
| 135 |
is not given, `arg' is taken as a pointer to a variable. |
| 136 |
|
| 137 |
|
| 138 |
Notes |
| 139 |
----- |
| 140 |
|
| 141 |
* A dash (`-') by itself is not taken as any kind of an option, as |
| 142 |
several programs use this to indicate the special files stdin and |
| 143 |
stdout. It is thus left as a normal argument to the program. |
| 144 |
|
| 145 |
* Two dashes (`--') as an argument, is taken to mean that the rest of |
| 146 |
the arguments should not be scanned for options. This simplifies |
| 147 |
giving names of files that start with a dash. |
| 148 |
|
| 149 |
* Short (one-character) options accept parameters in two ways, either |
| 150 |
directly following the option in the same argv-entry, or in the next |
| 151 |
argv-entry: |
| 152 |
|
| 153 |
-sPARAMETER |
| 154 |
-s PARAMETER |
| 155 |
|
| 156 |
* Long options accept parameters in two ways: |
| 157 |
|
| 158 |
--long-option=PARAMETER |
| 159 |
--long-option PARAMETER |
| 160 |
|
| 161 |
To follow the GNU-tradition, your program documentation should use |
| 162 |
the first form. |
| 163 |
|
| 164 |
* Several one-character options may be combined after a single |
| 165 |
dash. If any of the options requires a parameter, the rest of the |
| 166 |
string is taken as this parameter. If there is no "rest of the |
| 167 |
string", the next argument is taken as the parameter. |
| 168 |
|
| 169 |
* There is no support for floating point (double) arguments to |
| 170 |
options. This is to avoid unnecessary linking with the math |
| 171 |
library. See example.c for how to get around this by writing a |
| 172 |
function converting a string argument to a double (functions |
| 173 |
strToDouble and doubleFunc). |
| 174 |
|
| 175 |
|
| 176 |
Portability |
| 177 |
----------- |
| 178 |
|
| 179 |
If your libc lacks strtoul, you will need to link with GNU's -liberty, |
| 180 |
that may be found by anonymous ftp to ftp://ftp.gnu.org/pub/gnu/ |
| 181 |
|
| 182 |
The library has (more or less recently) been compiled and `tested' on |
| 183 |
the following systems: |
| 184 |
|
| 185 |
IRIX Release 5.3 IP22 |
| 186 |
GNU/Linux 2.2.11 |
| 187 |
SunOS Release 4.1.3_U1 (-liberty needed) |
| 188 |
ULTRIX V4.4 (Rev. 69) |
| 189 |
|
| 190 |
All compilations were done using GNU's gcc, and GNU's make. |
| 191 |
|
| 192 |
|
| 193 |
Author |
| 194 |
------ |
| 195 |
|
| 196 |
The program is written by |
| 197 |
|
| 198 |
Sverre H. Huseby [email protected] |
| 199 |
Lofthusvn. 11 B http://home.sol.no/~sverrehu/ |
| 200 |
N-0587 Oslo |
| 201 |
Norway |
| 202 |
|
| 203 |
You can use and copy this for _free_, but I would be very happy if you |
| 204 |
send me an E-mail and tell me that you use it. If you insist on paying |
| 205 |
something, please donate some money to an organization that strives to |
| 206 |
make the world a better place for everyone. |
| 207 |
|
| 208 |
I don't like bugs, so please help me removing them by reporting |
| 209 |
whatever you find! |
| 210 |
|