3 * $Id: mdwopt.c,v 1.3 1999/05/14 18:51:42 mdw Exp $
5 * Options parsing, similar to GNU @getopt_long@
7 * (c) 1996 Mark Wooding
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.3 1999/05/14 18:51:42 mdw
34 * Reformat the LGPL notice slightly.
36 * Revision 1.2 1999/05/13 22:57:23 mdw
37 * Change `-ise' to `-ize' throughout.
39 * Revision 1.1.1.1 1999/05/05 19:23:47 mdw
40 * New import. The old CVS repository was lost in a disk disaster.
42 * --- Previous lives ---
45 * Revision 1.7 1997/09/11 09:19:11 mdw
46 * (mo__nextWord): Arrrgh. Don't free the environment variable buffer!
47 * People are still using it!
49 * Revision 1.6 1997/09/11 09:05:54 mdw
50 * (mo__nextWord): Fix bug which returns too many words from environment
53 * Revision 1.5 1997/08/09 20:27:59 mdw
54 * Fix spelling of `Licensing'.
56 * Revision 1.4 1997/07/29 21:11:35 mdw
57 * Reformatted. Fixed buffer overflow when dealing with environment
58 * variables. Included NT in list of daft operating systems with `\' as a
59 * path separator. Fixed address of the FSF.
61 * Revision 1.3 1997/02/26 00:41:10 mdw
62 * Added GPL notice to the top. Slight formatting changes.
64 * Revision 1.2 1996/10/28 13:12:13 mdw
65 * Fixed calls to ctype.h routines. Arguments are cast to unsigned char
66 * to avoid invoking undefined behaviour caused by signedness of chars.
68 * Revision 1.1 1996/09/24 18:01:28 mdw
73 /*----- External dependencies ---------------------------------------------*/
82 /*----- Configuration things ----------------------------------------------*/
86 #elif defined(__OS2__) || defined(__MSDOS__) || defined(__WINNT__)
88 #else /* Assume a sane filing system */
92 /*----- Global variables --------------------------------------------------*/
94 mdwopt_data mdwopt_global = {0, 0, 0, 1, 0, 0, 0, 0, 0};
97 ord__permute = 0, /* Permute the options (default) */
98 ord__return = 1, /* Return non-option things */
99 ord__posix = 2, /* Do POSIX-type hacking */
100 ord__negate = 4 /* Magic negate-next-thing flag */
103 /*----- Main code ---------------------------------------------------------*/
105 /* --- @mo__nextWord@ --- *
107 * Arguments: @int argc@ = number of command line options
108 * @char *argv[]@ = pointer to command line options
109 * @mdwopt_data *data@ = pointer to persistent state
111 * Returns: Pointer to the next word to handle, or 0
113 * Use: Extracts the next word from the command line or environment
117 static char *mo__nextWord(int argc, char *const *argv, mdwopt_data *data)
119 if (data->ind == -1) {
122 while (isspace((unsigned char)*p))
125 while (*p && !isspace((unsigned char)*p))
136 if (data->next == argc)
138 return (argv[data->next++]);
141 /* --- @mo__permute@ --- *
143 * Arguments: @char *argv[]@ = pointer to command line arguments
144 * @mdwopt_data *data@ = pointer to persistent data
148 * Use: Moves a command line option into the right place.
151 static void mo__permute(char *const *argv, mdwopt_data *data)
153 char **v = (char **)argv;
154 if (data->ind != -1) {
155 int i = data->next - 1;
157 while (i > data->ind) {
166 /* --- @mo__findOpt@ --- *
168 * Arguments: @int o@ = which option to search for
169 * @const char *shortopt@ = short options string to search
170 * @mdwopt_data *data@ = pointer to persistant state
172 * Returns: Pointer to rest of short options string (including magic
175 * Use: Looks up a short option in the given string.
178 static const char *mo__findOpt(int o, const char *shortopt,
181 const char *p = shortopt; /* Point to short opts table */
183 if (!*p) /* No more options left */
186 if (o != *p || (p[1] != '+' && data->order & ord__negate)) {
187 p++; /* Skip this option entry */
188 while (*p == '+') /* Jump a `%|+|%' sign */
190 while (*p == ':') /* And jump any `%|:|%' characters */
191 p++; /* Just in case there are any */
198 /* --- @mdwopt@ --- *
200 * Arguments: @int argc@ = number of command line arguments
201 * @char * const *argv@ = pointer to command line arguments
202 * @const char *shortopt@ = pointer to short options information
203 * @const struct option *longopts@ = pointer to long opts info
204 * @int *longind@ = where to store matched longopt
205 * @mdwopt_data *data@ = persistent state for the parser
206 * @int flags@ = various useful flags
208 * Returns: Value of option found next, or an error character, or
209 * @EOF@ for the last thing.
211 * Use: Reads options. The routine should be more-or-less compatible
212 * with standard getopts, although it provides many more
213 * features even than the standard GNU implementation.
215 * The precise manner of options parsing is determined by
216 * various flag settings, which are described below. By setting
217 * flag values appropriately, you can achieve behaviour very
218 * similar to most other getopt routines.
221 * How options parsing appears to users
223 * A command line consists of a number of `words' (which may
224 * contain spaces, according to various shell quoting
225 * conventions). A word may be an option, an argument to an
226 * option, or a non-option. An option begins with a special
227 * character, usually `%|-|%', although `%|+|%' is also used
228 * sometimes. As special exceptions, the word containing only a
229 * `%|-|%' is considered to be a non-option, since it usually
230 * represents standard input or output as a filename, and the
231 * word containing a double-dash `%|--|%' is used to mark all
232 * following words as being non-options regardless of their
235 * Traditionally, all words after the first non-option have been
236 * considered to be non-options automatically, so that options
237 * must be specified before filenames. However, this
238 * implementation can extract all the options from the command
239 * line regardless of their position. This can usually be
240 * disabled by setting one of the environment variables
241 * `%|POSIXLY_CORRECT|%' or `%|_POSIX_OPTION_ORDER|%'.
243 * There are two different styles of options: `short' and
246 * Short options are the sort which Unix has known for ages: an
247 * option is a single letter, preceded by a `%|-|%'. Short
248 * options can be joined together to save space (and possibly to
249 * make silly words): e.g., instead of giving options
250 * `%|-x -y|%', a user could write `%|-xy|%'. Some short
251 * options can have arguments, which appear after the option
252 * letter, either immediately following, or in the next `word'
253 * (so an option with an argument could be written as
254 * `%|-o foo|%' or as `%|-ofoo|%'). Note that options with
255 * optional arguments must be written in the second style.
257 * When a short option controls a flag setting, it is sometimes
258 * possible to explicitly turn the flag off, as well as turning
259 * it on, (usually to override default options). This is
260 * usually done by using a `%|+|%' instead of a `%|-|%' to
261 * introduce the option.
263 * Long options, as popularized by the GNU utilities, are given
264 * long-ish memorable names, preceded by a double-dash `%|--|%'.
265 * Since their names are more than a single character, long
266 * options can't be combined in the same way as short options.
267 * Arguments to long options may be given either in the same
268 * `word', separated from the option name by an equals sign, or
269 * in the following `word'.
271 * Long option names can be abbreviated if necessary, as long
272 * as the abbreviation is unique. This means that options can
273 * have sensible and memorable names but still not require much
274 * typing from an experienced user.
276 * Like short options, long options can control flag settings.
277 * The options to manipulate these settings come in pairs: an
278 * option of the form `%|--set-flag|%' might set the flag, while
279 * an option of the form `%|--no-set-flag|%' might clear it.
281 * It is usual for applications to provide both short and long
282 * options with identical behaviour. Some applications with
283 * lots of options may only provide long options (although they
284 * will often be only two or three characters long). In this
285 * case, long options can be preceded with a single `%|-|%'
286 * character, and negated by a `%|+|%' character.
288 * Finally, some (older) programs accept arguments of the form
289 * `%%@.{"-"<number>}%%', to set some numerical parameter,
290 * typically a line count of some kind.
293 * How programs parse options
295 * An application parses its options by calling mdwopt
296 * repeatedly. Each time it is called, mdwopt returns a value
297 * describing the option just read, and stores information about
298 * the option in a data block. The value %$-1$% is returned
299 * when there are no more options to be read. The `%|?|%'
300 * character is returned when an error is encountered.
302 * Before starting to parse options, the value @data->ind@ must
303 * be set to 0 or 1. The value of @data->err@ can also be set,
304 * to choose whether errors are reported by mdwopt.
306 * The program's `@argc@' and `@argv@' arguments are passed to
307 * the options parser, so that it can read the command line. A
308 * flags word is also passed, allowing the program fine control
309 * over parsing. The flags are described above.
311 * Short options are described by a string, which once upon a
312 * time just contained the permitted option characters. Now the
313 * options string begins with a collection of flag characters,
314 * and various flag characters can be put after options
315 * characters to change their properties.
317 * If the first character of the short options string is
318 * `%|+|%', `%|-|%' or `%|!|%', the order in which options are
319 * read is modified, as follows:
321 * `%|+|%' forces the POSIX order to be used. As soon as a non-
322 * option is found, mdwopt returns %$-1$%.
324 * `%|-|%' makes mdwopt treat non-options as being `special'
325 * sorts of option. When a non-option word is found, the
326 * value 0 is returned, and the actual text of the word
327 * is stored as being the option's argument.
329 * `%|!|%' forces the default order to be used. The entire
330 * command line is scanned for options, which are
331 * returned in order. However, during this process,
332 * the options are moved in the @argv@ array, so that
333 * they appear before the non- options.
335 * A `%|:|%' character may be placed after the ordering flag (or
336 * at the very beginning if no ordering flag is given) which
337 * indicates that the character `%|:|%', rather than `%|?|%',
338 * should be returned if a missing argument error is detected.
340 * Each option in the string can be followed by a `%|+|%' sign,
341 * indicating that it can be negated, a `%|:|%' sign indicating
342 * that it requires an argument, or a `%|::|%' string,
343 * indicating an optional argument. Both `%|+|%' and `%|:|%' or
344 * `%|::|%' may be given, although the `%|+|%' must come first.
346 * If an option is found, the option character is returned to
347 * the caller. A pointer to an argument is stored in
348 * @data->arg@, or @NULL@ is stored if there was no argument.
349 * If a negated option was found, the option character is
350 * returned ORred with @gFlag_negated@ (bit 8 set).
352 * Long options are described in a table. Each entry in the
353 * table is of type @struct option@, and the table is terminated
354 * by an entry whose @name@ field is null. Each option has
355 * a flags word which, due to historical reasons, is called
356 * @has_arg@. This describes various properties of the option,
357 * such as what sort of argument it takes, and whether it can
360 * When mdwopt finds a long option, it looks the name up in the
361 * table. The index of the matching entry is stored in the
362 * @longind@ variable, passed to mdwopt (unless @longind@ is 0):
363 * a value of %$-1$% indicates that no long option was
364 * found. The behaviour is then dependent on the values in the
365 * table entry. If @flag@ is nonzero, it points to an integer
366 * to be modified by mdwopt. Usually the value in the @val@
367 * field is simply stored in the @flag@ variable. If the flag
368 * @gFlag_switch@ is set, however, the value is combined with
369 * the existing value of the flags using a bitwise OR. If
370 * @gFlag_negate@ is set, then the flag bit will be cleared if a
371 * matching negated long option is found. The value 0 is
374 * If @flag@ is zero, the value in @val@ is returned by mdwopt,
375 * possibly with bit 8 set if the option was negated.
377 * Arguments for long options are stored in @data->arg@, as
380 * Numeric options, if enabled, cause the value `%|#|%' to be
381 * returned, and the numeric value to be stored in @data->opt@.
383 * If the flag @gFlag_envVar@ is set on entry, options will be
384 * extracted from an environment variable whose name is built by
385 * capitalising all the letters of the program's name. (This
386 * allows a user to have different default settings for a
387 * program, by calling it through different symbolic links.) */
389 int mdwopt(int argc, char *const *argv,
390 const char *shortopt,
391 const struct option *longopts, int *longind,
392 mdwopt_data *data, int flags)
394 /* --- Local variables --- */
396 char *p, *q, *r; /* Some useful things to have */
397 char *prefix; /* Prefix from this option */
398 int i; /* Always useful */
399 char noarg = '?'; /* Standard missing-arg char */
401 /* --- Sort out our data --- */
403 if (!data) /* If default data requested */
404 data = &mdwopt_global; /* Then use the global stuff */
406 /* --- See if this is the first time --- */
408 if (data->ind == 0 || (data->ind == 1 && ~flags & gFlag_noProgName)) {
410 /* --- Sort out default returning order --- */
412 if (getenv("_POSIX_OPTION_ORDER") || /* Examine environment for opts */
413 getenv("POSIXLY_CORRECT")) /* To see if we disable features */
414 data->order = ord__posix; /* If set, use POSIX ordering */
416 data->order = ord__permute; /* Otherwise mangle the options */
418 /* --- Now see what the caller actually wants --- */
420 switch (shortopt[0]) { /* Look at the first character */
421 case '-': /* `%|-|%' turns on in-orderness */
422 data->order = ord__return;
424 case '+': /* `%|+|%' turns on POSIXness */
425 data->order = ord__posix;
427 case '!': /* `%|!|%' ignores POSIXness */
428 data->order = ord__permute;
432 /* --- Now decide on the program's name --- */
434 if (~flags & gFlag_noProgName) {
435 p = q = (char *)argv[0];
442 data->ind = data->next = 1;
445 /* --- See about environment variables --- *
447 * Be careful. The program may be setuid, and an attacker might have
448 * given us a long name in @argv[0]@. If the name is very long, don't
449 * support this option.
452 if (flags & gFlag_envVar && strlen(data->prog) < 48) {
456 /* --- For RISC OS, support a different format --- *
458 * Acorn's RISC OS tends to put settings in variables named
459 * `App$Options' rather than `APP'. Under RISC OS, I'll support
460 * both methods, just to avoid confuddlement.
464 sprintf(buf, "%s$Options", data->prog);
469 p = buf; /* Point to a buffer */
470 q = data->prog; /* Point to program name */
471 while (*q) /* While characters left here */
472 *p++ = toupper(*q++); /* Copy and uppercase */
473 *p++ = 0; /* Terminate my copy of this */
474 p = getenv(buf); /* Get the value of the variable */
480 /* --- Copy the options string into a buffer --- */
482 if (p) { /* If it is defined */
483 q = malloc(strlen(p) + 1); /* Allocate space for a copy */
484 if (!q) { /* If that failed */
485 fprintf(stderr, /* Report a nice error */
486 "%s: Not enough memory to read settings in "
487 "environment variable\n",
489 } else { /* Otherwise */
490 strcpy(q, p); /* Copy the text over */
491 data->ind = -1; /* Mark that we're parsing envvar */
492 data->env = data->estart = q; /* And store the pointer away */
499 data->ind = data->next = 0;
502 /* --- Do some initial bodgery --- *
504 * The @shortopt@ string can have some interesting characters at the
505 * beginning. We'll skip past them.
508 switch (shortopt[0]) {
516 if (shortopt[0] == ':') {
521 if (longind) /* Allow longind to be null */
522 *longind = -1; /* Clear this to avoid confusion */
523 data->opt = -1; /* And this too */
524 data->arg = 0; /* No option set up here */
526 /* --- Now go off and search for an option --- */
528 if (!data->list || !*data->list) {
529 data->order &= 3; /* Clear negation flag */
531 /* --- Now we need to find the next option --- *
533 * Exactly how we do this depends on the settings of the order variable.
534 * We identify options as being things starting with `%|-|%', and which
535 * aren't equal to `%|-|%' or `%|--|%'. We'll look for options until:
537 * * We find something which isn't an option AND @order == ord__posix@
538 * * We find a `%|--|%'
539 * * We reach the end of the list
541 * There are some added little wrinkles, which we'll meet as we go.
544 for (;;) { /* Keep looping for a while */
545 p = mo__nextWord(argc, argv, data); /* Get the next word out */
546 if (!p) /* If there's no next word */
547 return (EOF); /* There's no more now */
549 /* --- See if we've found an option --- */
551 if ((p[0] == '-' || (p[0] == '+' && flags & gFlag_negation)) &&
553 if (strcmp(p, "--") == 0) { /* If this is the magic marker */
554 mo__permute(argv, data); /* Stow the magic marker item */
555 return (EOF); /* There's nothing else to do */
557 break; /* We've found something! */
560 /* --- Figure out how to proceed --- */
562 switch (data->order & 3) {
563 case ord__posix: /* POSIX option order */
564 return (EOF); /* This is easy */
566 case ord__permute: /* Permute the option order */
568 case ord__return: /* Return each argument */
569 mo__permute(argv, data); /* Insert word in same place */
570 data->arg = p; /* Point to the argument */
571 return (0); /* Return the value */
575 /* --- We found an option --- */
577 mo__permute(argv, data); /* Do any permuting necessary */
579 /* --- Check for a numeric option --- *
581 * We only check the first character (or the second if the first is a
582 * sign). This ought to be enough.
585 if (flags & gFlag_numbers && (p[0] == '-' || flags & gFlag_negNumber)) {
586 if (((p[1] == '+' || p[1] == '-') && isdigit((unsigned char)p[2])) ||
587 isdigit((unsigned char)p[1])) {
588 data->opt = strtol(p + 1, &data->arg, 10);
589 while (isspace((unsigned char)data->arg[0]))
593 return (p[0] == '-' ? '#' : '#' | gFlag_negated);
597 /* --- Check for a long option --- */
600 data->order |= ord__negate;
602 if (((p[0] == '-' && p[1] == '-') ||
603 (flags & gFlag_noShorts && !mo__findOpt(p[1], shortopt, data))) &&
604 (~flags & gFlag_noLongs)) /* Is this a long option? */
606 int match = -1; /* Count matches as we go */
608 if (p[0] == '+') { /* If it's negated */
609 data->order |= ord__negate; /* Set the negate flag */
610 p++; /* Point to the main text */
611 prefix = "+"; /* Set the prefix string up */
612 } else if (p[1] == '-') { /* If this is a `%|--|%' option */
613 if ((flags & gFlag_negation) && strncmp(p + 2, "no-", 3) == 0) {
614 p += 5; /* Point to main text */
615 prefix = "--no-"; /* And set the prefix */
616 data->order |= ord__negate; /* Set the negatedness flag */
618 p += 2; /* Point to the main text */
619 prefix = "--"; /* Remember the prefix string */
622 if ((flags & gFlag_negation) && strncmp(p + 1, "no-", 3) == 0) {
623 p += 4; /* Find the text */
624 prefix = "-no-"; /* Set the prefix */
625 data->order |= ord__negate; /* Set negatedness flag */
627 p++; /* Otherwise find the text */
628 prefix = "-"; /* And remember the prefix */
632 for (i = 0; longopts[i].name; i++) { /* Loop through the options */
633 if ((data->order & ord__negate) &&
634 (~longopts[i].has_arg & gFlag_negate))
635 continue; /* If neg and opt doesn't allow */
637 r = (char *) longopts[i].name; /* Point to the name string */
638 q = p; /* Point to the string start */
639 for (;;) { /* Do a loop here */
640 if (*q == 0 || *q == '=') { /* End of the option string? */
641 if (*r == 0) { /* If end of other string */
642 match = i; /* This is the match */
643 goto botched; /* And exit the loop now */
645 if (match == -1) { /* If no match currently */
646 match = i; /* Then this is it, here */
647 break; /* Stop looking now */
649 match = -1; /* Else it's ambiguous */
650 goto botched; /* So give up right now */
653 else if (*q != *r) /* Otherwise if mismatch */
654 break; /* Abort this loop */
655 q++, r++; /* Increment the counters */
660 if (match == -1) { /* If we couldn't find a match */
662 fprintf(stderr, "%s: unrecognized option `%s%s'\n",
669 if (longind) /* Allow longind to be null */
670 *longind = match; /* Store the match away */
672 /* --- Handle argument behaviour --- */
674 while (*p != 0 && *p != '=') /* Find the argument string */
676 p = (*p ? p + 1 : 0); /* Sort out argument presence */
677 q = (char *) longopts[match].name; /* Remember the name here */
679 switch (longopts[match].has_arg & 3) {
684 "%s: option `%s%s' does not accept arguments\n",
692 case required_argument:
693 if (!p) { /* If no argument given */
694 p = mo__nextWord(argc, argv, data);
696 if (!p) { /* If no more arguments */
698 fprintf(stderr, "%s: option `%s%s' requires an argument\n",
705 mo__permute(argv, data);
709 case optional_argument:
715 /* --- Do correct things now we have a match --- */
717 if (longopts[match].flag) { /* If he has a @flag@ argument */
718 if (longopts[match].has_arg & gFlag_switch) {
719 if (data->order & ord__negate)
720 *longopts[match].flag &= ~longopts[match].val;
722 *longopts[match].flag |= longopts[match].val;
724 if (data->order & ord__negate)
725 *longopts[match].flag = 0;
727 *longopts[match].flag = longopts[match].val;
729 return (0); /* And return something */
731 if (data->order & ord__negate)
732 return (longopts[match].val | gFlag_negated);
734 return (longopts[match].val);
738 /* --- Do short options things --- */
741 if (p[0] == '+') /* If starts with a `%|+|%' */
742 data->order |= ord__negate;
743 data->list = p + 1; /* Omit leading `%|-|%'/`%|+|%' */
747 /* --- Now process the short options --- */
749 i = *data->list++; /* Get the next option letter */
750 data->opt = i; /* Store this away nicely */
752 p = (char *) mo__findOpt(i, shortopt, data);
753 if (!p) { /* No more options left */
755 fprintf(stderr, "%s: unknown option `%c%c'\n",
757 data->order & ord__negate ? '+' : '-',
763 data->opt = i; /* Store this for the caller */
765 /* --- Sort out an argument, if we expect one --- */
767 if (p[0] == ':') { /* If we expect an option */
768 q = (data->list[0] ? data->list : 0); /* If argument expected, use it */
769 data->list = 0; /* Kill the remaining options */
770 if (p[1] != ':' && !q) { /* If no arg, and not optional */
772 /* --- Same code as before --- */
774 q = mo__nextWord(argc, argv, data); /* Read the next word */
775 if (!q) { /* If no more arguments */
777 fprintf(stderr, "%s: option `%c%c' requires an argument\n",
779 data->order & ord__negate ? '+' : '-',
784 mo__permute(argv, data);
789 return ((data->order & ord__negate) ? i | gFlag_negated : i);
792 /*----- That's all, folks -------------------------------------------------*/