3 * $Id: mdwopt.c,v 1.2 1997/08/04 10:24:23 mdw Exp $
5 * Options parsing, similar to GNU @getopt_long@
7 * (c) 1996 Mark Wooding
10 /*----- Licencing 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 General Public License as published by
16 * the Free Software Foundation; either version 2 of the License, or
17 * (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 General Public License for more details.
24 * You should have received a copy of the GNU General Public License
25 * along with `mdwopt'; if not, write to the Free Software Foundation,
26 * Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
29 /*----- Revision history --------------------------------------------------*
32 * Revision 1.2 1997/08/04 10:24:23 mdw
33 * Sources placed under CVS control.
35 * Revision 1.4 1997/07/29 21:11:35 mdw
36 * Reformatted. Fixed buffer overflow when dealing with environment
37 * variables. Included NT in list of daft operating systems with `\' as a
38 * path separator. Fixed address of the FSF.
40 * Revision 1.3 1997/02/26 00:41:10 mdw
41 * Added GPL notice to the top. Slight formatting changes.
43 * Revision 1.2 1996/10/28 13:12:13 mdw
44 * Fixed calls to ctype.h routines. Arguments are cast to unsigned char
45 * to avoid invoking undefined behaviour caused by signedness of chars.
47 * Revision 1.1 1996/09/24 18:01:28 mdw
52 /*----- External dependencies ---------------------------------------------*/
61 /*----- Configuration things ----------------------------------------------*/
65 #elif defined(__OS2__) || defined(__MSDOS__) || defined(__WINNT__)
67 #else /* Assume a sane filing system */
71 /*----- Global variables --------------------------------------------------*/
73 mdwopt_data mdwopt_global
= {0, 0, 0, 1, 0, 0, 0, 0, 0};
76 ord__permute
= 0, /* Permute the options (default) */
77 ord__return
= 1, /* Return non-option things */
78 ord__posix
= 2, /* Do POSIX-type hacking */
79 ord__negate
= 4 /* Magic negate-next-thing flag */
82 /*----- Main code ---------------------------------------------------------*/
84 /* --- @mo__nextWord@ --- *
86 * Arguments: @int argc@ = number of command line options
87 * @char *argv[]@ = pointer to command line options
88 * @mdwopt_data *data@ = pointer to persistent state
90 * Returns: Pointer to the next word to handle, or 0
92 * Use: Extracts the next word from the command line or environment
96 static char *mo__nextWord(int argc
, char *const *argv
, mdwopt_data
*data
)
98 if (data
->ind
== -1) {
101 while (isspace((unsigned char)*p
))
104 while (*p
&& !isspace((unsigned char)*p
))
115 if (data
->next
== argc
)
117 return (argv
[data
->next
++]);
120 /* --- @mo__permute@ --- *
122 * Arguments: @char *argv[]@ = pointer to command line arguments
123 * @mdwopt_data *data@ = pointer to persistent data
127 * Use: Moves a command line option into the right place.
130 static void mo__permute(char *const *argv
, mdwopt_data
*data
)
132 char **v
= (char **)argv
;
133 if (data
->ind
!= -1) {
134 int i
= data
->next
- 1;
136 while (i
> data
->ind
) {
145 /* --- @mo__findOpt@ --- *
147 * Arguments: @int o@ = which option to search for
148 * @const char *shortopt@ = short options string to search
149 * @mdwopt_data *data@ = pointer to persistant state
151 * Returns: Pointer to rest of short options string (including magic
154 * Use: Looks up a short option in the given string.
157 static const char *mo__findOpt(int o
, const char *shortopt
,
160 const char *p
= shortopt
; /* Point to short opts table */
162 if (!*p
) /* No more options left */
165 if (o
!= *p
|| (p
[1] != '+' && data
->order
& ord__negate
)) {
166 p
++; /* Skip this option entry */
167 while (*p
== '+') /* Jump a `%|+|%' sign */
169 while (*p
== ':') /* And jump any `%|:|%' characters */
170 p
++; /* Just in case there are any */
177 /* --- @mdwopt@ --- *
179 * Arguments: @int argc@ = number of command line arguments
180 * @char * const *argv@ = pointer to command line arguments
181 * @const char *shortopt@ = pointer to short options information
182 * @const struct option *longopts@ = pointer to long opts info
183 * @int *longind@ = where to store matched longopt
184 * @mdwopt_data *data@ = persistent state for the parser
185 * @int flags@ = various useful flags
187 * Returns: Value of option found next, or an error character, or
188 * @EOF@ for the last thing.
190 * Use: Reads options. The routine should be more-or-less compatible
191 * with standard getopts, although it provides many more
192 * features even than the standard GNU implementation.
194 * The precise manner of options parsing is determined by
195 * various flag settings, which are described below. By setting
196 * flag values appropriately, you can achieve behaviour very
197 * similar to most other getopt routines.
200 * How options parsing appears to users
202 * A command line consists of a number of `words' (which may
203 * contain spaces, according to various shell quoting
204 * conventions). A word may be an option, an argument to an
205 * option, or a non-option. An option begins with a special
206 * character, usually `%|-|%', although `%|+|%' is also used
207 * sometimes. As special exceptions, the word containing only a
208 * `%|-|%' is considered to be a non-option, since it usually
209 * represents standard input or output as a filename, and the
210 * word containing a double-dash `%|--|%' is used to mark all
211 * following words as being non-options regardless of their
214 * Traditionally, all words after the first non-option have been
215 * considered to be non-options automatically, so that options
216 * must be specified before filenames. However, this
217 * implementation can extract all the options from the command
218 * line regardless of their position. This can usually be
219 * disabled by setting one of the environment variables
220 * `%|POSIXLY_CORRECT|%' or `%|_POSIX_OPTION_ORDER|%'.
222 * There are two different styles of options: `short' and
225 * Short options are the sort which Unix has known for ages: an
226 * option is a single letter, preceded by a `%|-|%'. Short
227 * options can be joined together to save space (and possibly to
228 * make silly words): e.g., instead of giving options
229 * `%|-x -y|%', a user could write `%|-xy|%'. Some short
230 * options can have arguments, which appear after the option
231 * letter, either immediately following, or in the next `word'
232 * (so an option with an argument could be written as
233 * `%|-o foo|%' or as `%|-ofoo|%'). Note that options with
234 * optional arguments must be written in the second style.
236 * When a short option controls a flag setting, it is sometimes
237 * possible to explicitly turn the flag off, as well as turning
238 * it on, (usually to override default options). This is
239 * usually done by using a `%|+|%' instead of a `%|-|%' to
240 * introduce the option.
242 * Long options, as popularised by the GNU utilities, are given
243 * long-ish memorable names, preceded by a double-dash `%|--|%'.
244 * Since their names are more than a single character, long
245 * options can't be combined in the same way as short options.
246 * Arguments to long options may be given either in the same
247 * `word', separated from the option name by an equals sign, or
248 * in the following `word'.
250 * Long option names can be abbreviated if necessary, as long
251 * as the abbreviation is unique. This means that options can
252 * have sensible and memorable names but still not require much
253 * typing from an experienced user.
255 * Like short options, long options can control flag settings.
256 * The options to manipulate these settings come in pairs: an
257 * option of the form `%|--set-flag|%' might set the flag, while
258 * an option of the form `%|--no-set-flag|%' might clear it.
260 * It is usual for applications to provide both short and long
261 * options with identical behaviour. Some applications with
262 * lots of options may only provide long options (although they
263 * will often be only two or three characters long). In this
264 * case, long options can be preceded with a single `%|-|%'
265 * character, and negated by a `%|+|%' character.
267 * Finally, some (older) programs accept arguments of the form
268 * `%%@.{"-"<number>}%%', to set some numerical parameter,
269 * typically a line count of some kind.
272 * How programs parse options
274 * An application parses its options by calling mdwopt
275 * repeatedly. Each time it is called, mdwopt returns a value
276 * describing the option just read, and stores information about
277 * the option in a data block. The value %$-1$% is returned
278 * when there are no more options to be read. The `%|?|%'
279 * character is returned when an error is encountered.
281 * Before starting to parse options, the value @data->ind@ must
282 * be set to 0 or 1. The value of @data->err@ can also be set,
283 * to choose whether errors are reported by mdwopt.
285 * The program's `@argc@' and `@argv@' arguments are passed to
286 * the options parser, so that it can read the command line. A
287 * flags word is also passed, allowing the program fine control
288 * over parsing. The flags are described above.
290 * Short options are described by a string, which once upon a
291 * time just contained the permitted option characters. Now the
292 * options string begins with a collection of flag characters,
293 * and various flag characters can be put after options
294 * characters to change their properties.
296 * If the first character of the short options string is
297 * `%|+|%', `%|-|%' or `%|!|%', the order in which options are
298 * read is modified, as follows:
300 * `%|+|%' forces the POSIX order to be used. As soon as a non-
301 * option is found, mdwopt returns %$-1$%.
303 * `%|-|%' makes mdwopt treat non-options as being `special'
304 * sorts of option. When a non-option word is found, the
305 * value 0 is returned, and the actual text of the word
306 * is stored as being the option's argument.
308 * `%|!|%' forces the default order to be used. The entire
309 * command line is scanned for options, which are
310 * returned in order. However, during this process,
311 * the options are moved in the @argv@ array, so that
312 * they appear before the non- options.
314 * A `%|:|%' character may be placed after the ordering flag (or
315 * at the very beginning if no ordering flag is given) which
316 * indicates that the character `%|:|%', rather than `%|?|%',
317 * should be returned if a missing argument error is detected.
319 * Each option in the string can be followed by a `%|+|%' sign,
320 * indicating that it can be negated, a `%|:|%' sign indicating
321 * that it requires an argument, or a `%|::|%' string,
322 * indicating an optional argument. Both `%|+|%' and `%|:|%' or
323 * `%|::|%' may be given, although the `%|+|%' must come first.
325 * If an option is found, the option character is returned to
326 * the caller. A pointer to an argument is stored in
327 * @data->arg@, or @NULL@ is stored if there was no argument.
328 * If a negated option was found, the option character is
329 * returned ORred with @gFlag_negated@ (bit 8 set).
331 * Long options are described in a table. Each entry in the
332 * table is of type @struct option@, and the table is terminated
333 * by an entry whose @name@ field is null. Each option has
334 * a flags word which, due to historical reasons, is called
335 * @has_arg@. This describes various properties of the option,
336 * such as what sort of argument it takes, and whether it can
339 * When mdwopt finds a long option, it looks the name up in the
340 * table. The index of the matching entry is stored in the
341 * @longind@ variable, passed to mdwopt (unless @longind@ is 0):
342 * a value of %$-1$% indicates that no long option was
343 * found. The behaviour is then dependent on the values in the
344 * table entry. If @flag@ is nonzero, it points to an integer
345 * to be modified by mdwopt. Usually the value in the @val@
346 * field is simply stored in the @flag@ variable. If the flag
347 * @gFlag_switch@ is set, however, the value is combined with
348 * the existing value of the flags using a bitwise OR. If
349 * @gFlag_negate@ is set, then the flag bit will be cleared if a
350 * matching negated long option is found. The value 0 is
353 * If @flag@ is zero, the value in @val@ is returned by mdwopt,
354 * possibly with bit 8 set if the option was negated.
356 * Arguments for long options are stored in @data->arg@, as
359 * Numeric options, if enabled, cause the value `%|#|%' to be
360 * returned, and the numeric value to be stored in @data->opt@.
362 * If the flag @gFlag_envVar@ is set on entry, options will be
363 * extracted from an environment variable whose name is built by
364 * capitalising all the letters of the program's name. (This
365 * allows a user to have different default settings for a
366 * program, by calling it through different symbolic links.) */
368 int mdwopt(int argc
, char *const *argv
,
369 const char *shortopt
,
370 const struct option
*longopts
, int *longind
,
371 mdwopt_data
*data
, int flags
)
373 /* --- Local variables --- */
375 char *p
, *q
, *r
; /* Some useful things to have */
376 char *prefix
; /* Prefix from this option */
377 int i
; /* Always useful */
378 char noarg
= '?'; /* Standard missing-arg char */
380 /* --- Sort out our data --- */
382 if (!data
) /* If default data requested */
383 data
= &mdwopt_global
; /* Then use the global stuff */
385 /* --- See if this is the first time --- */
387 if (data
->ind
== 0 || (data
->ind
== 1 && ~flags
& gFlag_noProgName
)) {
389 /* --- Sort out default returning order --- */
391 if (getenv("_POSIX_OPTION_ORDER") || /* Examine environment for opts */
392 getenv("POSIXLY_CORRECT")) /* To see if we disable features */
393 data
->order
= ord__posix
; /* If set, use POSIX ordering */
395 data
->order
= ord__permute
; /* Otherwise mangle the options */
397 /* --- Now see what the caller actually wants --- */
399 switch (shortopt
[0]) { /* Look at the first character */
400 case '-': /* `%|-|%' turns on in-orderness */
401 data
->order
= ord__return
;
403 case '+': /* `%|+|%' turns on POSIXness */
404 data
->order
= ord__posix
;
406 case '!': /* `%|!|%' ignores POSIXness */
407 data
->order
= ord__permute
;
411 /* --- Now decide on the program's name --- */
413 if (~flags
& gFlag_noProgName
) {
414 p
= q
= (char *)argv
[0];
421 data
->ind
= data
->next
= 1;
424 /* --- See about environment variables --- *
426 * Be careful. The program may be setuid, and an attacker might have
427 * given us a long name in @argv[0]@. If the name is very long, don't
428 * support this option.
431 if (flags
& gFlag_envVar
&& strlen(data
->prog
) < 48) {
435 /* --- For RISC OS, support a different format --- *
437 * Acorn's RISC OS tends to put settings in variables named
438 * `App$Options' rather than `APP'. Under RISC OS, I'll support
439 * both methods, just to avoid confuddlement.
443 sprintf(buf
, "%s$Options", data
->prog
);
448 p
= buf
; /* Point to a buffer */
449 q
= data
->prog
; /* Point to program name */
450 while (*q
) /* While characters left here */
451 *p
++ = toupper(*q
++); /* Copy and uppercase */
452 *p
++ = 0; /* Terminate my copy of this */
453 p
= getenv(buf
); /* Get the value of the variable */
459 /* --- Copy the options string into a buffer --- */
461 if (p
) { /* If it is defined */
462 q
= malloc(strlen(p
) + 1); /* Allocate space for a copy */
463 if (!q
) { /* If that failed */
464 fprintf(stderr
, /* Report a nice error */
465 "%s: Not enough memory to read settings in "
466 "environment variable\n",
468 } else { /* Otherwise */
469 strcpy(q
, p
); /* Copy the text over */
470 data
->ind
= -1; /* Mark that we're parsing envvar */
471 data
->env
= data
->estart
= q
; /* And store the pointer away */
478 data
->ind
= data
->next
= 0;
481 /* --- Do some initial bodgery --- *
483 * The @shortopt@ string can have some interesting characters at the
484 * beginning. We'll skip past them.
487 switch (shortopt
[0]) {
495 if (shortopt
[0] == ':') {
500 if (longind
) /* Allow longind to be null */
501 *longind
= -1; /* Clear this to avoid confusion */
502 data
->opt
= -1; /* And this too */
503 data
->arg
= 0; /* No option set up here */
505 /* --- Now go off and search for an option --- */
507 if (!data
->list
|| !*data
->list
) {
508 data
->order
&= 3; /* Clear negation flag */
510 /* --- Now we need to find the next option --- *
512 * Exactly how we do this depends on the settings of the order variable.
513 * We identify options as being things starting with `%|-|%', and which
514 * aren't equal to `%|-|%' or `%|--|%'. We'll look for options until:
516 * * We find something which isn't an option AND @order == ord__posix@
517 * * We find a `%|--|%'
518 * * We reach the end of the list
520 * There are some added little wrinkles, which we'll meet as we go.
523 for (;;) { /* Keep looping for a while */
524 p
= mo__nextWord(argc
, argv
, data
); /* Get the next word out */
525 if (!p
) /* If there's no next word */
526 return (EOF
); /* There's no more now */
528 /* --- See if we've found an option --- */
530 if ((p
[0] == '-' || (p
[0] == '+' && flags
& gFlag_negation
)) &&
532 if (strcmp(p
, "--") == 0) { /* If this is the magic marker */
533 mo__permute(argv
, data
); /* Stow the magic marker item */
534 return (EOF
); /* There's nothing else to do */
536 break; /* We've found something! */
539 /* --- Figure out how to proceed --- */
541 switch (data
->order
& 3) {
542 case ord__posix
: /* POSIX option order */
543 return (EOF
); /* This is easy */
545 case ord__permute
: /* Permute the option order */
547 case ord__return
: /* Return each argument */
548 mo__permute(argv
, data
); /* Insert word in same place */
549 data
->arg
= p
; /* Point to the argument */
550 return (0); /* Return the value */
554 /* --- We found an option --- */
556 mo__permute(argv
, data
); /* Do any permuting necessary */
558 /* --- Check for a numeric option --- *
560 * We only check the first character (or the second if the first is a
561 * sign). This ought to be enough.
564 if (flags
& gFlag_numbers
&& (p
[0] == '-' || flags
& gFlag_negNumber
)) {
565 if (((p
[1] == '+' || p
[1] == '-') && isdigit((unsigned char)p
[2])) ||
566 isdigit((unsigned char)p
[1])) {
567 data
->opt
= strtol(p
+ 1, &data
->arg
, 10);
568 while (isspace((unsigned char)data
->arg
[0]))
572 return (p
[0] == '-' ?
'#' : '#' | gFlag_negated
);
576 /* --- Check for a long option --- */
579 data
->order
|= ord__negate
;
581 if (((p
[0] == '-' && p
[1] == '-') ||
582 (flags
& gFlag_noShorts
&& !mo__findOpt(p
[1], shortopt
, data
))) &&
583 (~flags
& gFlag_noLongs
)) /* Is this a long option? */
585 int match
= -1; /* Count matches as we go */
587 if (p
[0] == '+') { /* If it's negated */
588 data
->order
|= ord__negate
; /* Set the negate flag */
589 p
++; /* Point to the main text */
590 prefix
= "+"; /* Set the prefix string up */
591 } else if (p
[1] == '-') { /* If this is a `%|--|%' option */
592 if ((flags
& gFlag_negation
) && strncmp(p
+ 2, "no-", 3) == 0) {
593 p
+= 5; /* Point to main text */
594 prefix
= "--no-"; /* And set the prefix */
595 data
->order
|= ord__negate
; /* Set the negatedness flag */
597 p
+= 2; /* Point to the main text */
598 prefix
= "--"; /* Remember the prefix string */
601 if ((flags
& gFlag_negation
) && strncmp(p
+ 1, "no-", 3) == 0) {
602 p
+= 4; /* Find the text */
603 prefix
= "-no-"; /* Set the prefix */
604 data
->order
|= ord__negate
; /* Set negatedness flag */
606 p
++; /* Otherwise find the text */
607 prefix
= "-"; /* And remember the prefix */
611 for (i
= 0; longopts
[i
].name
; i
++) { /* Loop through the options */
612 if ((data
->order
& ord__negate
) &&
613 (~longopts
[i
].has_arg
& gFlag_negate
))
614 continue; /* If neg and opt doesn't allow */
616 r
= (char *) longopts
[i
].name
; /* Point to the name string */
617 q
= p
; /* Point to the string start */
618 for (;;) { /* Do a loop here */
619 if (*q
== 0 || *q
== '=') { /* End of the option string? */
620 if (*r
== 0) { /* If end of other string */
621 match
= i
; /* This is the match */
622 goto botched
; /* And exit the loop now */
624 if (match
== -1) { /* If no match currently */
625 match
= i
; /* Then this is it, here */
626 break; /* Stop looking now */
628 match
= -1; /* Else it's ambiguous */
629 goto botched
; /* So give up right now */
632 else if (*q
!= *r
) /* Otherwise if mismatch */
633 break; /* Abort this loop */
634 q
++, r
++; /* Increment the counters */
639 if (match
== -1) { /* If we couldn't find a match */
641 fprintf(stderr
, "%s: unrecognised option `%s%s'\n",
648 if (longind
) /* Allow longind to be null */
649 *longind
= match
; /* Store the match away */
651 /* --- Handle argument behaviour --- */
653 while (*p
!= 0 && *p
!= '=') /* Find the argument string */
655 p
= (*p ? p
+ 1 : 0); /* Sort out argument presence */
656 q
= (char *) longopts
[match
].name
; /* Remember the name here */
658 switch (longopts
[match
].has_arg
& 3) {
663 "%s: option `%s%s' does not accept arguments\n",
671 case required_argument
:
672 if (!p
) { /* If no argument given */
673 p
= mo__nextWord(argc
, argv
, data
);
675 if (!p
) { /* If no more arguments */
677 fprintf(stderr
, "%s: option `%s%s' requires an argument\n",
684 mo__permute(argv
, data
);
688 case optional_argument
:
694 /* --- Do correct things now we have a match --- */
696 if (longopts
[match
].flag
) { /* If he has a @flag@ argument */
697 if (longopts
[match
].has_arg
& gFlag_switch
) {
698 if (data
->order
& ord__negate
)
699 *longopts
[match
].flag
&= ~longopts
[match
].val
;
701 *longopts
[match
].flag
|= longopts
[match
].val
;
703 if (data
->order
& ord__negate
)
704 *longopts
[match
].flag
= 0;
706 *longopts
[match
].flag
= longopts
[match
].val
;
708 return (0); /* And return something */
710 if (data
->order
& ord__negate
)
711 return (longopts
[match
].val
| gFlag_negated
);
713 return (longopts
[match
].val
);
717 /* --- Do short options things --- */
720 if (p
[0] == '+') /* If starts with a `%|+|%' */
721 data
->order
|= ord__negate
;
722 data
->list
= p
+ 1; /* Omit leading `%|-|%'/`%|+|%' */
726 /* --- Now process the short options --- */
728 i
= *data
->list
++; /* Get the next option letter */
729 data
->opt
= i
; /* Store this away nicely */
731 p
= (char *) mo__findOpt(i
, shortopt
, data
);
732 if (!p
) { /* No more options left */
734 fprintf(stderr
, "%s: unknown option `%c%c'\n",
736 data
->order
& ord__negate ?
'+' : '-',
742 data
->opt
= i
; /* Store this for the caller */
744 /* --- Sort out an argument, if we expect one --- */
746 if (p
[0] == ':') { /* If we expect an option */
747 q
= (data
->list
[0] ? data
->list
: 0); /* If argument expected, use it */
748 data
->list
= 0; /* Kill the remaining options */
749 if (p
[1] != ':' && !q
) { /* If no arg, and not optional */
751 /* --- Same code as before --- */
753 q
= mo__nextWord(argc
, argv
, data
); /* Read the next word */
754 if (!q
) { /* If no more arguments */
756 fprintf(stderr
, "%s: option `%c%c' requires an argument\n",
758 data
->order
& ord__negate ?
'+' : '-',
763 mo__permute(argv
, data
);
768 return ((data
->order
& ord__negate
) ? i
| gFlag_negated
: i
);
771 /*----- That's all, folks -------------------------------------------------*/