3 * $Id: mdwopt.h,v 1.8 1999/08/19 18:37:43 mdw Exp $
5 * Options parsing, similar to GNU @getopt_long@
7 * (c) 1996 Straylight/Edgeware
10 /*----- Licensing notice --------------------------------------------------*
12 * This file is part of many programs.
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.
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.
24 * You should have received a copy of the GNU Library General Public
25 * License along with `mdwopt'; if not, write to the Free
26 * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
30 /*----- Revision history --------------------------------------------------*
33 * Revision 1.8 1999/08/19 18:37:43 mdw
36 * Revision 1.7 1999/08/19 18:35:10 mdw
37 * Add a couple more flag constants.
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.
43 * Revision 1.5 1999/05/19 20:23:59 mdw
44 * Change naming to match newer mLib conventions.
46 * Revision 1.4 1999/05/15 10:25:38 mdw
47 * Fix copyright information.
49 * Revision 1.3 1999/05/14 18:51:42 mdw
50 * Reformat the LGPL notice slightly.
52 * Revision 1.2 1999/05/13 22:57:23 mdw
53 * Change `-ise' to `-ize' throughout.
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.
58 * --- Previous lives ---
61 * Revision 1.5 1997/08/09 20:27:59 mdw
62 * Fix spelling of `Licensing'.
64 * Revision 1.4 1997/07/29 21:11:49 mdw
65 * Fixed address of the FSF.
67 * Revision 1.3 1996/12/31 19:41:33 mdw
70 * Revision 1.2 1996/11/23 00:47:25 mdw
71 * Added `MdwOpt' object from the `anagram' source code.
73 * Revision 1.1 1996/09/24 18:01:43 mdw
81 /*----- Options handling structures ---------------------------------------*/
87 /* --- @mdwopt_data@ --- *
89 * Contains all the information needed by the @mdwopt@ routine to do its
90 * work. Try not to use @prog@ any more. If you're using mLib, the @quis@/
91 * @ego@ interface works better.
96 /* --- Public variables --- */
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]@) */
104 /* --- Private variables --- *
106 * Don't play with these, please.
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 */
117 /*----- Global variables --------------------------------------------------*/
119 extern mdwopt_data mdwopt_global
; /* The default global data */
121 /* --- For compatibility with older programs (and prettiness) --- *
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@.
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 */
134 /*----- Type definitions --------------------------------------------------*/
136 /* --- Long options definition table --- */
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 */
145 /* --- Old-style names for argument flags in long options table --- */
148 no_argument
, /* No argument required */
149 required_argument
, /* User must specify argument */
150 optional_argument
/* Argument is optional */
153 /* --- New style flag names --- */
156 OPTF_NOARG
= 0, /* No argument */
157 OPTF_ARGREQ
= 1, /* Required argument */
158 OPTF_ARGOPT
= 2, /* Optional argument */
159 OPTF_ARG
= 3, /* Argument type bitmask */
160 OPTF_SWITCH
= 4, /* OR val into flag, don't store */
161 OPTF_NEGATE
= 8 /* Allow long option to be negated */
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 */
175 OPTF_NEGATED
= 256 /* Option flag was negated by user */
178 /* --- Older new-style names --- */
181 gFlag_argReq
= 1, gFlag_argOpt
= 2, gFlag_switch
= 4, gFlag_negate
= 8
185 gFlag_noLongs
= 1, gFlag_noShorts
= 2, gFlag_numbers
= 4,
186 gFlag_negation
= 8, gFlag_envVar
= 16, gFlag_noProgName
= 32,
194 /*----- Main code ---------------------------------------------------------*/
196 /* --- @mdwopt@ --- *
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
206 * Returns: Value of option found next, or an error character, or
207 * @EOF@ for the last thing.
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.
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.
219 * How options parsing appears to users
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
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|%'.
241 * There are two different styles of options: `short' and
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.
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.
261 * Long options, as popularized by the GNU utilities, are given
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'.
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.
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.
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.
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.
291 * How programs parse options
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.
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.
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.
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.
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:
319 * `%|+|%' forces the POSIX order to be used. As soon as a non-
320 * option is found, mdwopt returns %$-1$%.
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.
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.
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.
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.
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
348 * returned ORred with @OPTF_NEGATED@ (bit 8 set).
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
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
366 * @OPTF_SWITCH@ is set, however, the value is combined with
367 * the existing value of the flags using a bitwise OR. If
368 * @OPTF_NEGATE@ is set, then the flag bit will be cleared if a
369 * matching negated long option is found. The value 0 is
372 * If @flag@ is zero, the value in @val@ is returned by mdwopt,
373 * possibly with bit 8 set if the option was negated.
375 * Arguments for long options are stored in @data->arg@, as
378 * Numeric options, if enabled, cause the value `%|#|%' to be
379 * returned, and the numeric value to be stored in @data->opt@.
381 * If the flag @OPTF_ENVVAR@ is set on entry, options will be
382 * extracted from an environment variable whose name is built by
383 * capitalizing all the letters of the program's name. (This
384 * allows a user to have different default settings for a
385 * program, by calling it through different symbolic links.)
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*/);
393 /* --- Macros for more commonly used routines --- */
395 #define getopt(c, v, o) mdwopt(c, v, o, 0, 0, 0, OPTF_NOLONGS)
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) \
398 mdwopt(c, v, o, l, li, 0, OPTF_NOSHORTS)
404 /*----- C++ wrapper class -------------------------------------------------*/
408 /* --- Class: @MdwOpt@ --- *
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
422 * @prog@ -- return program name from @argv[0]@
423 * @next@ -- return next option read from the table
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.
434 const char *shortopts
;
435 const struct option
*longopts
;
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
) {
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
); }
458 return (mdwopt(argc
, argv
, shortopts
,
459 longopts
, &long_ind
, &data
, flags
));
465 /*----- That's all, folks -------------------------------------------------*/