b91e2391 |
1 | /* -*-c-*- |
2 | * |
98ea3924 |
3 | * $Id: mdwopt.h,v 1.8 1999/08/19 18:37:43 mdw Exp $ |
b91e2391 |
4 | * |
5 | * Options parsing, similar to GNU @getopt_long@ |
6 | * |
9cecacb1 |
7 | * (c) 1996 Straylight/Edgeware |
b91e2391 |
8 | */ |
9 | |
10 | /*----- Licensing notice --------------------------------------------------* |
11 | * |
12 | * This file is part of many programs. |
13 | * |
14 | * `mdwopt' is free software; you can redistribute it and/or modify |
15 | * it under the terms of the GNU Library General Public License as |
16 | * published by the Free Software Foundation; either version 2 of the |
17 | * License, or (at your option) any later version. |
18 | * |
19 | * `mdwopt' is distributed in the hope that it will be useful, |
20 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
21 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
22 | * GNU Library General Public License for more details. |
23 | * |
24 | * You should have received a copy of the GNU Library General Public |
4033d96b |
25 | * License along with `mdwopt'; if not, write to the Free |
26 | * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, |
27 | * MA 02111-1307, USA. |
b91e2391 |
28 | */ |
29 | |
30 | /*----- Revision history --------------------------------------------------* |
31 | * |
32 | * $Log: mdwopt.h,v $ |
98ea3924 |
33 | * Revision 1.8 1999/08/19 18:37:43 mdw |
34 | * Fix stupid error. |
35 | * |
70f69247 |
36 | * Revision 1.7 1999/08/19 18:35:10 mdw |
37 | * Add a couple more flag constants. |
38 | * |
79eae586 |
39 | * Revision 1.6 1999/05/20 23:00:30 mdw |
40 | * Carry through changes to the interface properly in the documentation. |
41 | * Other little formatting things. |
42 | * |
379c3233 |
43 | * Revision 1.5 1999/05/19 20:23:59 mdw |
44 | * Change naming to match newer mLib conventions. |
45 | * |
9cecacb1 |
46 | * Revision 1.4 1999/05/15 10:25:38 mdw |
47 | * Fix copyright information. |
48 | * |
4033d96b |
49 | * Revision 1.3 1999/05/14 18:51:42 mdw |
50 | * Reformat the LGPL notice slightly. |
51 | * |
5b59e227 |
52 | * Revision 1.2 1999/05/13 22:57:23 mdw |
53 | * Change `-ise' to `-ize' throughout. |
54 | * |
55 | * Revision 1.1.1.1 1999/05/05 19:23:47 mdw |
56 | * New import. The old CVS repository was lost in a disk disaster. |
b91e2391 |
57 | * |
58 | * --- Previous lives --- |
59 | * |
60 | * %Log: mdwopt.h,v % |
61 | * Revision 1.5 1997/08/09 20:27:59 mdw |
62 | * Fix spelling of `Licensing'. |
63 | * |
64 | * Revision 1.4 1997/07/29 21:11:49 mdw |
65 | * Fixed address of the FSF. |
66 | * |
67 | * Revision 1.3 1996/12/31 19:41:33 mdw |
68 | * Formatting changes. |
69 | * |
70 | * Revision 1.2 1996/11/23 00:47:25 mdw |
71 | * Added `MdwOpt' object from the `anagram' source code. |
72 | * |
73 | * Revision 1.1 1996/09/24 18:01:43 mdw |
74 | * Initial revision |
75 | * |
76 | */ |
77 | |
78 | #ifndef MDWOPT_H |
79 | #define MDWOPT_H |
80 | |
81 | /*----- Options handling structures ---------------------------------------*/ |
82 | |
83 | #ifdef __cplusplus |
84 | extern "C" { |
85 | #endif |
86 | |
87 | /* --- @mdwopt_data@ --- * |
88 | * |
89 | * Contains all the information needed by the @mdwopt@ routine to do its |
379c3233 |
90 | * work. Try not to use @prog@ any more. If you're using mLib, the @quis@/ |
91 | * @ego@ interface works better. |
b91e2391 |
92 | */ |
93 | |
94 | typedef struct { |
379c3233 |
95 | |
b91e2391 |
96 | /* --- Public variables --- */ |
97 | |
98 | char *arg; /* Arg of current option, or 0 */ |
99 | int opt; /* Value of current option */ |
100 | int ind; /* 0 for init, index when done */ |
101 | int err; /* Set nonzero for error messages */ |
102 | char *prog; /* Program name (from @argv[0]@) */ |
103 | |
104 | /* --- Private variables --- * |
105 | * |
106 | * Don't play with these, please. |
107 | */ |
108 | |
109 | char *list; /* Current short options pointer */ |
110 | int next; /* Next argument, unpermuted */ |
111 | int order; /* Ordering of options, flags */ |
112 | char *env; /* Where we are in the env var */ |
113 | char *estart; /* Pointer to env var buffer */ |
114 | } |
115 | mdwopt_data; |
116 | |
117 | /*----- Global variables --------------------------------------------------*/ |
118 | |
119 | extern mdwopt_data mdwopt_global; /* The default global data */ |
120 | |
121 | /* --- For compatibility with older programs (and prettiness) --- * |
122 | * |
123 | * The macros here access the global structure defined above. I consider it |
124 | * to be perfectly acceptable to use these macros in new code, because it |
125 | * looks nicer than playing with @mdwopt_global@. |
126 | */ |
127 | |
128 | #define optarg (mdwopt_global.arg) /* Argument of current option */ |
129 | #define optopt (mdwopt_global.opt) /* Code of current option */ |
130 | #define opterr (mdwopt_global.err) /* Zero to report error messages */ |
131 | #define optind (mdwopt_global.ind) /* Index of first non-option */ |
132 | #define optprog (mdwopt_global.prog) /* Pointer to program name */ |
133 | |
134 | /*----- Type definitions --------------------------------------------------*/ |
135 | |
136 | /* --- Long options definition table --- */ |
137 | |
138 | struct option { |
139 | const char *name; /* Name of the long option */ |
140 | int has_arg; /* Does it have an argument? */ |
141 | int *flag; /* Address of flag variable */ |
142 | int val; /* Value to store/return */ |
143 | }; |
144 | |
145 | /* --- Old-style names for argument flags in long options table --- */ |
146 | |
147 | enum { |
148 | no_argument, /* No argument required */ |
149 | required_argument, /* User must specify argument */ |
150 | optional_argument /* Argument is optional */ |
151 | }; |
152 | |
153 | /* --- New style flag names --- */ |
154 | |
155 | enum { |
98ea3924 |
156 | OPTF_NOARG = 0, /* No argument */ |
379c3233 |
157 | OPTF_ARGREQ = 1, /* Required argument */ |
158 | OPTF_ARGOPT = 2, /* Optional argument */ |
70f69247 |
159 | OPTF_ARG = 3, /* Argument type bitmask */ |
379c3233 |
160 | OPTF_SWITCH = 4, /* OR val into flag, don't store */ |
161 | OPTF_NEGATE = 8 /* Allow long option to be negated */ |
162 | }; |
163 | |
164 | enum { |
165 | OPTF_NOLONGS = 1, /* Don't read long options */ |
166 | OPTF_NOSHORTS = 2, /* Don't read short options */ |
167 | OPTF_NUMBERS = 4, /* Read numeric options */ |
168 | OPTF_NEGATION = 8, /* Allow `%|+|%' for negations */ |
169 | OPTF_ENVVAR = 16, /* Parse options from env var */ |
170 | OPTF_NOPROGNAME = 32, /* Don't set @optprog@ */ |
171 | OPTF_NEGNUMBER = 64 /* Allow negated number options */ |
172 | }; |
173 | |
174 | enum { |
175 | OPTF_NEGATED = 256 /* Option flag was negated by user */ |
176 | }; |
177 | |
178 | /* --- Older new-style names --- */ |
179 | |
180 | enum { |
181 | gFlag_argReq = 1, gFlag_argOpt = 2, gFlag_switch = 4, gFlag_negate = 8 |
b91e2391 |
182 | }; |
183 | |
184 | enum { |
379c3233 |
185 | gFlag_noLongs = 1, gFlag_noShorts = 2, gFlag_numbers = 4, |
186 | gFlag_negation = 8, gFlag_envVar = 16, gFlag_noProgName = 32, |
187 | gFlag_negNumber = 64 |
b91e2391 |
188 | }; |
189 | |
190 | enum { |
379c3233 |
191 | gFlag_negated = 256 |
b91e2391 |
192 | }; |
193 | |
194 | /*----- Main code ---------------------------------------------------------*/ |
195 | |
196 | /* --- @mdwopt@ --- * |
197 | * |
198 | * Arguments: @int argc@ = number of command line arguments |
199 | * @char * const *argv@ = pointer to command line arguments |
200 | * @const char *shortopt@ = pointer to short options information |
201 | * @const struct option *longopts@ = pointer to long opts info |
202 | * @int *longind@ = where to store matched longopt |
203 | * @mdwopt_data *data@ = persistent state for the parser |
204 | * @int flags@ = various useful flags |
205 | * |
206 | * Returns: Value of option found next, or an error character, or |
207 | * @EOF@ for the last thing. |
208 | * |
209 | * Use: Reads options. The routine should be more-or-less compatible |
210 | * with standard getopts, although it provides many more |
211 | * features even than the standard GNU implementation. |
212 | * |
213 | * The precise manner of options parsing is determined by |
214 | * various flag settings, which are described below. By setting |
215 | * flag values appropriately, you can achieve behaviour very |
216 | * similar to most other getopt routines. |
217 | * |
218 | * |
219 | * How options parsing appears to users |
220 | * |
221 | * A command line consists of a number of `words' (which may |
222 | * contain spaces, according to various shell quoting |
223 | * conventions). A word may be an option, an argument to an |
224 | * option, or a non-option. An option begins with a special |
225 | * character, usually `%|-|%', although `%|+|%' is also used |
226 | * sometimes. As special exceptions, the word containing only a |
227 | * `%|-|%' is considered to be a non-option, since it usually |
228 | * represents standard input or output as a filename, and the |
229 | * word containing a double-dash `%|--|%' is used to mark all |
230 | * following words as being non-options regardless of their |
231 | * initial character. |
232 | * |
233 | * Traditionally, all words after the first non-option have been |
234 | * considered to be non-options automatically, so that options |
235 | * must be specified before filenames. However, this |
236 | * implementation can extract all the options from the command |
237 | * line regardless of their position. This can usually be |
238 | * disabled by setting one of the environment variables |
239 | * `%|POSIXLY_CORRECT|%' or `%|_POSIX_OPTION_ORDER|%'. |
240 | * |
241 | * There are two different styles of options: `short' and |
242 | * `long'. |
243 | * |
244 | * Short options are the sort which Unix has known for ages: an |
245 | * option is a single letter, preceded by a `%|-|%'. Short |
246 | * options can be joined together to save space (and possibly to |
247 | * make silly words): e.g., instead of giving options |
248 | * `%|-x.-y|%', a user could write `%|-xy|%'. Some short |
249 | * options can have arguments, which appear after the option |
250 | * letter, either immediately following, or in the next `word' |
251 | * (so an option with an argument could be written as |
252 | * `%|-o foo|%' or as `%|-ofoo|%'). Note that options with |
253 | * optional arguments must be written in the second style. |
254 | * |
255 | * When a short option controls a flag setting, it is sometimes |
256 | * possible to explicitly turn the flag off, as well as turning |
257 | * it on, (usually to override default options). This is |
258 | * usually done by using a `%|+|%' instead of a `%|-|%' to |
259 | * introduce the option. |
260 | * |
5b59e227 |
261 | * Long options, as popularized by the GNU utilities, are given |
b91e2391 |
262 | * long-ish memorable names, preceded by a double-dash `%|--|%'. |
263 | * Since their names are more than a single character, long |
264 | * options can't be combined in the same way as short options. |
265 | * Arguments to long options may be given either in the same |
266 | * `word', separated from the option name by an equals sign, or |
267 | * in the following `word'. |
268 | * |
269 | * Long option names can be abbreviated if necessary, as long |
270 | * as the abbreviation is unique. This means that options can |
271 | * have sensible and memorable names but still not require much |
272 | * typing from an experienced user. |
273 | * |
274 | * Like short options, long options can control flag settings. |
275 | * The options to manipulate these settings come in pairs: an |
276 | * option of the form `%|--set-flag|%' might set the flag, while |
277 | * an option of the form `%|--no-set-flag|%' might clear it. |
278 | * |
279 | * It is usual for applications to provide both short and long |
280 | * options with identical behaviour. Some applications with |
281 | * lots of options may only provide long options (although they |
282 | * will often be only two or three characters long). In this |
283 | * case, long options can be preceded with a single `%|-|%' |
284 | * character, and negated by a `%|+|%' character. |
285 | * |
286 | * Finally, some (older) programs accept arguments of the form |
287 | * `%%@.{"-"<number>}%%', to set some numerical parameter, |
288 | * typically a line count of some kind. |
289 | * |
290 | * |
291 | * How programs parse options |
292 | * |
293 | * An application parses its options by calling mdwopt |
294 | * repeatedly. Each time it is called, mdwopt returns a value |
295 | * describing the option just read, and stores information about |
296 | * the option in a data block. The value %$-1$% is returned |
297 | * when there are no more options to be read. The `%|?|%' |
298 | * character is returned when an error is encountered. |
299 | * |
300 | * Before starting to parse options, the value @data->ind@ must |
301 | * be set to 0 or 1. The value of @data->err@ can also be set, |
302 | * to choose whether errors are reported by mdwopt. |
303 | * |
304 | * The program's `@argc@' and `@argv@' arguments are passed to |
305 | * the options parser, so that it can read the command line. A |
306 | * flags word is also passed, allowing the program fine control |
307 | * over parsing. The flags are described above. |
308 | * |
309 | * Short options are described by a string, which once upon a |
310 | * time just contained the permitted option characters. Now the |
311 | * options string begins with a collection of flag characters, |
312 | * and various flag characters can be put after options |
313 | * characters to change their properties. |
314 | * |
315 | * If the first character of the short options string is |
316 | * `%|+|%', `%|-|%' or `%|!|%', the order in which options are |
317 | * read is modified, as follows: |
318 | * |
319 | * `%|+|%' forces the POSIX order to be used. As soon as a non- |
320 | * option is found, mdwopt returns %$-1$%. |
321 | * |
322 | * `%|-|%' makes mdwopt treat non-options as being `special' |
323 | * sorts of option. When a non-option word is found, the |
324 | * value 0 is returned, and the actual text of the word |
325 | * is stored as being the option's argument. |
326 | * |
327 | * `%|!|%' forces the default order to be used. The entire |
328 | * command line is scanned for options, which are |
329 | * returned in order. However, during this process, |
330 | * the options are moved in the @argv@ array, so that |
331 | * they appear before the non- options. |
332 | * |
333 | * A `%|:|%' character may be placed after the ordering flag (or |
334 | * at the very beginning if no ordering flag is given) which |
335 | * indicates that the character `%|:|%', rather than `%|?|%', |
336 | * should be returned if a missing argument error is detected. |
337 | * |
338 | * Each option in the string can be followed by a `%|+|%' sign, |
339 | * indicating that it can be negated, a `%|:|%' sign indicating |
340 | * that it requires an argument, or a `%|::|%' string, |
341 | * indicating an optional argument. Both `%|+|%' and `%|:|%' or |
342 | * `%|::|%' may be given, although the `%|+|%' must come first. |
343 | * |
344 | * If an option is found, the option character is returned to |
345 | * the caller. A pointer to an argument is stored in |
346 | * @data->arg@, or @NULL@ is stored if there was no argument. |
347 | * If a negated option was found, the option character is |
79eae586 |
348 | * returned ORred with @OPTF_NEGATED@ (bit 8 set). |
b91e2391 |
349 | * |
350 | * Long options are described in a table. Each entry in the |
351 | * table is of type @struct option@, and the table is terminated |
352 | * by an entry whose @name@ field is null. Each option has |
353 | * a flags word which, due to historical reasons, is called |
354 | * @has_arg@. This describes various properties of the option, |
355 | * such as what sort of argument it takes, and whether it can |
356 | * be negated. |
357 | * |
358 | * When mdwopt finds a long option, it looks the name up in the |
359 | * table. The index of the matching entry is stored in the |
360 | * @longind@ variable, passed to mdwopt (unless @longind@ is 0): |
361 | * a value of %$-1$% indicates that no long option was |
362 | * found. The behaviour is then dependent on the values in the |
363 | * table entry. If @flag@ is nonzero, it points to an integer |
364 | * to be modified by mdwopt. Usually the value in the @val@ |
365 | * field is simply stored in the @flag@ variable. If the flag |
79eae586 |
366 | * @OPTF_SWITCH@ is set, however, the value is combined with |
b91e2391 |
367 | * the existing value of the flags using a bitwise OR. If |
79eae586 |
368 | * @OPTF_NEGATE@ is set, then the flag bit will be cleared if a |
b91e2391 |
369 | * matching negated long option is found. The value 0 is |
370 | * returned. |
371 | * |
372 | * If @flag@ is zero, the value in @val@ is returned by mdwopt, |
373 | * possibly with bit 8 set if the option was negated. |
374 | * |
375 | * Arguments for long options are stored in @data->arg@, as |
376 | * before. |
377 | * |
378 | * Numeric options, if enabled, cause the value `%|#|%' to be |
379 | * returned, and the numeric value to be stored in @data->opt@. |
380 | * |
79eae586 |
381 | * If the flag @OPTF_ENVVAR@ is set on entry, options will be |
b91e2391 |
382 | * extracted from an environment variable whose name is built by |
79eae586 |
383 | * capitalizing all the letters of the program's name. (This |
b91e2391 |
384 | * allows a user to have different default settings for a |
79eae586 |
385 | * program, by calling it through different symbolic links.) |
386 | */ |
b91e2391 |
387 | |
388 | extern int mdwopt(int /*argc*/, char *const */*argv*/, |
389 | const char */*shortopt*/, |
390 | const struct option */*longopts*/, int */*longind*/, |
391 | mdwopt_data */*data*/, int /*flags*/); |
392 | |
393 | /* --- Macros for more commonly used routines --- */ |
394 | |
79eae586 |
395 | #define getopt(c, v, o) mdwopt(c, v, o, 0, 0, 0, OPTF_NOLONGS) |
b91e2391 |
396 | #define getopt_long(c, v, o, l, li) mdwopt(c, v, o, l, li, 0, 0) |
397 | #define getopt_long_only(c, v, o, l, li) \ |
79eae586 |
398 | mdwopt(c, v, o, l, li, 0, OPTF_NOSHORTS) |
b91e2391 |
399 | |
400 | #ifdef __cplusplus |
401 | } |
402 | #endif |
403 | |
404 | /*----- C++ wrapper class -------------------------------------------------*/ |
405 | |
406 | #ifdef __cplusplus |
407 | |
408 | /* --- Class: @MdwOpt@ --- * |
409 | * |
410 | * Parent: --- |
411 | * |
412 | * Methods: @MdwOpt@ -- construct a new mdwopt object with the given |
413 | * arguments. These are remembered for later use. |
414 | * @arg@ -- return the argument of the current option |
415 | * arguments. These are remembered for later use. |
416 | * @arg@ -- return the argument of the current option |
417 | * @opt@ -- return the value of the current option |
418 | * @ind@ -- return the index of the next unread argument |
419 | * @longind@ -- return index of current long option in table |
420 | * @errors@ -- return or set whether we report errors to the |
421 | * user |
422 | * @prog@ -- return program name from @argv[0]@ |
423 | * @next@ -- return next option read from the table |
424 | * |
425 | * Use: A simple C++ class for encapsulating the options parser. |
426 | * The methods are all nice and simple, and extremely similar |
427 | * to the normal C interface described above. |
428 | */ |
429 | |
430 | class MdwOpt { |
431 | protected: |
432 | int argc; |
433 | char * const *argv; |
434 | const char *shortopts; |
435 | const struct option *longopts; |
436 | int long_ind; |
437 | int flags; |
438 | |
439 | mdwopt_data data; |
440 | |
441 | public: |
442 | MdwOpt(int c, char * const *v, const char *so, |
443 | const struct option *lo, int f=0) : |
444 | argc(c), argv(v), shortopts(so), longopts(lo), flags(f) { |
445 | data.ind = 0; |
446 | data.err = 1; |
447 | } |
448 | |
449 | const char *arg(void) const { return (data.arg); } |
450 | int opt(void) const { return (data.opt); } |
451 | int errors(void) const { return (data.err); } |
452 | int errors(int e) { int oe = data.err; data.err = e; return (oe); } |
453 | int ind(void) const { return (data.ind); } |
454 | int longind(void) const { return (long_ind); } |
455 | const char *prog(void) const { return (data.prog); } |
456 | |
457 | int next(void) { |
458 | return (mdwopt(argc, argv, shortopts, |
459 | longopts, &long_ind, &data, flags)); |
460 | } |
461 | }; |
462 | |
463 | #endif |
464 | |
465 | /*----- That's all, folks -------------------------------------------------*/ |
466 | |
467 | #endif |