Debian Codegraph @

lib/util/shhopt.README

raw
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