1
1
/* Hierarchial argument parsing, layered over getopt.
2
Copyright (C) 1995-1999,2003-2008 Free Software Foundation, Inc.
2
Copyright (C) 1995-1999, 2003-2010 Free Software Foundation, Inc.
3
3
This file is part of the GNU C Library.
4
4
Written by Miles Bader <miles@gnu.ai.mit.edu>.
114
114
/* The argument associated with this option is optional. */
115
#define OPTION_ARG_OPTIONAL 0x1
115
#define OPTION_ARG_OPTIONAL 0x1
117
117
/* This option isn't displayed in any help messages. */
118
#define OPTION_HIDDEN 0x2
118
#define OPTION_HIDDEN 0x2
120
120
/* This option is an alias for the closest previous non-alias option. This
121
121
means that it will be displayed in the same help entry, and will inherit
122
122
fields other than NAME and KEY from the aliased option. */
123
#define OPTION_ALIAS 0x4
123
#define OPTION_ALIAS 0x4
125
125
/* This option isn't actually an option (and so should be ignored by the
126
126
actual option parser), but rather an arbitrary piece of documentation that
133
133
ignored, except that if the first non-whitespace character is not `-', this
134
134
entry is displayed after all options (and OPTION_DOC entries with a leading
135
135
`-') in the same group. */
136
#define OPTION_DOC 0x8
136
#define OPTION_DOC 0x8
138
138
/* This option shouldn't be included in `long' usage messages (but is still
139
139
included in help messages). This is mainly intended for options that are
142
142
if ARGS_DOC is "FOO BAR\n-x BLAH", and the `-x' option's purpose is to
143
143
distinguish these two cases, -x should probably be marked
144
144
OPTION_NO_USAGE. */
145
#define OPTION_NO_USAGE 0x10
145
#define OPTION_NO_USAGE 0x10
147
147
/* Valid only in conjunction with OPTION_DOC. This option disables translation
148
148
of option name. */
149
149
#define OPTION_NO_TRANS 0x20
152
struct argp; /* fwd declare this type */
153
struct argp_state; /* " */
154
struct argp_child; /* " */
152
struct argp; /* fwd declare this type */
153
struct argp_state; /* " */
154
struct argp_child; /* " */
156
156
/* The type of a pointer to an argp parsing function. */
157
157
typedef error_t (*argp_parser_t) (int key, char *arg,
158
struct argp_state *state);
158
struct argp_state *state);
160
160
/* What to return for unrecognized keys. For special ARGP_KEY_ keys, such
161
161
returns will simply be ignored. For user keys, this error will be turned
162
162
into EINVAL (if the call to argp_parse is such that errors are propagated
163
163
back to the user instead of exiting); returning EINVAL itself would result
164
164
in an immediate stop to parsing in *all* cases. */
165
#define ARGP_ERR_UNKNOWN E2BIG /* Hurd should never need E2BIG. XXX */
165
#define ARGP_ERR_UNKNOWN E2BIG /* Hurd should never need E2BIG. XXX */
167
167
/* Special values for the KEY argument to an argument parsing function.
168
168
ARGP_ERR_UNKNOWN should be returned if they aren't understood.
190
190
passed, the option won't be considered processed; this is to allow you to
191
191
actually modify the argument (perhaps into an option), and have it
192
192
processed again. */
193
#define ARGP_KEY_ARG 0
193
#define ARGP_KEY_ARG 0
194
194
/* There are remaining arguments not parsed by any parser, which may be found
195
195
starting at (STATE->argv + STATE->next). If success is returned, but
196
196
STATE->next left untouched, it's assumed that all arguments were consume,
197
197
otherwise, the parser should adjust STATE->next to reflect any arguments
199
#define ARGP_KEY_ARGS 0x1000006
199
#define ARGP_KEY_ARGS 0x1000006
200
200
/* There are no more command line arguments at all. */
201
#define ARGP_KEY_END 0x1000001
201
#define ARGP_KEY_END 0x1000001
202
202
/* Because it's common to want to do some special processing if there aren't
203
203
any non-option args, user parsers are called with this key if they didn't
204
204
successfully process any non-option arguments. Called just before
205
205
ARGP_KEY_END (where more general validity checks on previously parsed
206
206
arguments can take place). */
207
#define ARGP_KEY_NO_ARGS 0x1000002
207
#define ARGP_KEY_NO_ARGS 0x1000002
208
208
/* Passed in before any parsing is done. Afterwards, the values of each
209
209
element of the CHILD_INPUT field, if any, in the state structure is
210
210
copied to each child's state to be the initial value of the INPUT field. */
211
#define ARGP_KEY_INIT 0x1000003
211
#define ARGP_KEY_INIT 0x1000003
212
212
/* Use after all other keys, including SUCCESS & END. */
213
#define ARGP_KEY_FINI 0x1000007
213
#define ARGP_KEY_FINI 0x1000007
214
214
/* Passed in when parsing has successfully been completed (even if there are
215
215
still arguments remaining). */
216
#define ARGP_KEY_SUCCESS 0x1000004
216
#define ARGP_KEY_SUCCESS 0x1000004
217
217
/* Passed in if an error occurs. */
218
#define ARGP_KEY_ERROR 0x1000005
218
#define ARGP_KEY_ERROR 0x1000005
220
220
/* An argp structure contains a set of options declarations, a function to
221
221
deal with parsing one, documentation string, a possible vector of child
281
281
/* Possible KEY arguments to a help filter function. */
282
#define ARGP_KEY_HELP_PRE_DOC 0x2000001 /* Help text preceeding options. */
283
#define ARGP_KEY_HELP_POST_DOC 0x2000002 /* Help text following options. */
284
#define ARGP_KEY_HELP_HEADER 0x2000003 /* Option header string. */
285
#define ARGP_KEY_HELP_EXTRA 0x2000004 /* After all other documentation;
286
TEXT is NULL for this key. */
282
#define ARGP_KEY_HELP_PRE_DOC 0x2000001 /* Help text preceeding options. */
283
#define ARGP_KEY_HELP_POST_DOC 0x2000002 /* Help text following options. */
284
#define ARGP_KEY_HELP_HEADER 0x2000003 /* Option header string. */
285
#define ARGP_KEY_HELP_EXTRA 0x2000004 /* After all other documentation;
286
TEXT is NULL for this key. */
287
287
/* Explanatory note emitted when duplicate option arguments have been
289
289
#define ARGP_KEY_HELP_DUP_ARGS_NOTE 0x2000005
290
#define ARGP_KEY_HELP_ARGS_DOC 0x2000006 /* Argument doc string. */
290
#define ARGP_KEY_HELP_ARGS_DOC 0x2000006 /* Argument doc string. */
292
292
/* When an argp has a non-zero CHILDREN field, it should point to a vector of
293
293
argp_child structures, each of which describes a subsidiary argp. */
358
358
/* Streams used when argp prints something. */
359
FILE *err_stream; /* For errors; initialized to stderr. */
360
FILE *out_stream; /* For information; initialized to stdout. */
359
FILE *err_stream; /* For errors; initialized to stderr. */
360
FILE *out_stream; /* For information; initialized to stdout. */
362
void *pstate; /* Private, for use by argp. */
362
void *pstate; /* Private, for use by argp. */
365
365
/* Flags for argp_parse (note that the defaults are those that are
375
375
is set, ARGP_PARSE_ARGV0 is ignored, as ARGV[0] is used as the program
376
376
name in the error messages. This flag implies ARGP_NO_EXIT (on the
377
377
assumption that silent exiting upon errors is bad behaviour). */
378
#define ARGP_NO_ERRS 0x02
378
#define ARGP_NO_ERRS 0x02
380
380
/* Don't parse any non-option args. Normally non-option args are parsed by
381
381
calling the parse functions with a key of ARGP_KEY_ARG, and the actual arg
387
387
last time with a key of ARGP_KEY_END. This flag needn't normally be set,
388
388
as the normal behavior is to stop parsing as soon as some argument can't
390
#define ARGP_NO_ARGS 0x04
390
#define ARGP_NO_ARGS 0x04
392
392
/* Parse options and arguments in the same order they occur on the command
393
393
line -- normally they're rearranged so that all options come first. */
394
#define ARGP_IN_ORDER 0x08
394
#define ARGP_IN_ORDER 0x08
396
396
/* Don't provide the standard long option --help, which causes usage and
397
397
option help information to be output to stdout, and exit (0) called. */
398
#define ARGP_NO_HELP 0x10
398
#define ARGP_NO_HELP 0x10
400
400
/* Don't exit on errors (they may still result in error messages). */
401
#define ARGP_NO_EXIT 0x20
401
#define ARGP_NO_EXIT 0x20
403
403
/* Use the gnu getopt `long-only' rules for parsing arguments. */
404
#define ARGP_LONG_ONLY 0x40
404
#define ARGP_LONG_ONLY 0x40
406
406
/* Turns off any message-printing/exiting options. */
407
407
#define ARGP_SILENT (ARGP_NO_EXIT | ARGP_NO_ERRS | ARGP_NO_HELP)
414
414
returned. This function may also call exit unless the ARGP_NO_HELP flag
415
415
is set. INPUT is a pointer to a value to be passed in to the parser. */
416
416
extern error_t argp_parse (const struct argp *__restrict __argp,
417
int /*argc*/, char **__restrict /*argv*/,
418
unsigned __flags, int *__restrict __arg_index,
419
void *__restrict __input);
417
int /*argc*/, char **__restrict /*argv*/,
418
unsigned __flags, int *__restrict __arg_index,
419
void *__restrict __input);
420
420
extern error_t __argp_parse (const struct argp *__restrict __argp,
421
int /*argc*/, char **__restrict /*argv*/,
422
unsigned __flags, int *__restrict __arg_index,
423
void *__restrict __input);
421
int /*argc*/, char **__restrict /*argv*/,
422
unsigned __flags, int *__restrict __arg_index,
423
void *__restrict __input);
425
425
/* Global variables. */
450
450
the current parsing state, and then exits (unless the ARGP_NO_EXIT flag is
451
451
used). This variable takes precedent over ARGP_PROGRAM_VERSION. */
452
452
extern void (*argp_program_version_hook) (FILE *__restrict __stream,
453
struct argp_state *__restrict
453
struct argp_state *__restrict
456
456
/* If defined or set by the user program, it should point to string that is
457
457
the bug-reporting address for the program. It will be printed by
466
466
extern error_t argp_err_exit_status;
468
468
/* Flags for argp_help. */
469
#define ARGP_HELP_USAGE 0x01 /* a Usage: message. */
470
#define ARGP_HELP_SHORT_USAGE 0x02 /* " but don't actually print options. */
471
#define ARGP_HELP_SEE 0x04 /* a `Try ... for more help' message. */
472
#define ARGP_HELP_LONG 0x08 /* a long help message. */
473
#define ARGP_HELP_PRE_DOC 0x10 /* doc string preceding long help. */
474
#define ARGP_HELP_POST_DOC 0x20 /* doc string following long help. */
475
#define ARGP_HELP_DOC (ARGP_HELP_PRE_DOC | ARGP_HELP_POST_DOC)
476
#define ARGP_HELP_BUG_ADDR 0x40 /* bug report address */
477
#define ARGP_HELP_LONG_ONLY 0x80 /* modify output appropriately to
478
reflect ARGP_LONG_ONLY mode. */
469
#define ARGP_HELP_USAGE 0x01 /* a Usage: message. */
470
#define ARGP_HELP_SHORT_USAGE 0x02 /* " but don't actually print options. */
471
#define ARGP_HELP_SEE 0x04 /* a `Try ... for more help' message. */
472
#define ARGP_HELP_LONG 0x08 /* a long help message. */
473
#define ARGP_HELP_PRE_DOC 0x10 /* doc string preceding long help. */
474
#define ARGP_HELP_POST_DOC 0x20 /* doc string following long help. */
475
#define ARGP_HELP_DOC (ARGP_HELP_PRE_DOC | ARGP_HELP_POST_DOC)
476
#define ARGP_HELP_BUG_ADDR 0x40 /* bug report address */
477
#define ARGP_HELP_LONG_ONLY 0x80 /* modify output appropriately to
478
reflect ARGP_LONG_ONLY mode. */
480
480
/* These ARGP_HELP flags are only understood by argp_state_help. */
481
#define ARGP_HELP_EXIT_ERR 0x100 /* Call exit(1) instead of returning. */
482
#define ARGP_HELP_EXIT_OK 0x200 /* Call exit(0) instead of returning. */
481
#define ARGP_HELP_EXIT_ERR 0x100 /* Call exit(1) instead of returning. */
482
#define ARGP_HELP_EXIT_OK 0x200 /* Call exit(0) instead of returning. */
484
484
/* The standard thing to do after a program command line parsing error, if an
485
485
error message has already been printed. */
497
497
/* Output a usage message for ARGP to STREAM. FLAGS are from the set
499
499
extern void argp_help (const struct argp *__restrict __argp,
500
FILE *__restrict __stream,
501
unsigned __flags, char *__restrict __name);
500
FILE *__restrict __stream,
501
unsigned __flags, char *__restrict __name);
502
502
extern void __argp_help (const struct argp *__restrict __argp,
503
FILE *__restrict __stream, unsigned __flags,
503
FILE *__restrict __stream, unsigned __flags,
506
506
/* The following routines are intended to be called from within an argp
507
507
parsing routine (thus taking an argp_state structure as the first
514
514
/* Output, if appropriate, a usage message for STATE to STREAM. FLAGS are
515
515
from the set ARGP_HELP_*. */
516
516
extern void argp_state_help (const struct argp_state *__restrict __state,
517
FILE *__restrict __stream,
518
unsigned int __flags);
517
FILE *__restrict __stream,
518
unsigned int __flags);
519
519
extern void __argp_state_help (const struct argp_state *__restrict __state,
520
FILE *__restrict __stream,
521
unsigned int __flags);
520
FILE *__restrict __stream,
521
unsigned int __flags);
523
523
#if _LIBC || !defined __USE_EXTERN_INLINES
524
524
/* Possibly output the standard usage message for ARGP to stderr and exit. */
530
530
by the program name and `:', to stderr, and followed by a `Try ... --help'
531
531
message, then exit (1). */
532
532
extern void argp_error (const struct argp_state *__restrict __state,
533
const char *__restrict __fmt, ...)
533
const char *__restrict __fmt, ...)
534
534
__attribute__ ((__format__ (__printf__, 2, 3)));
535
535
extern void __argp_error (const struct argp_state *__restrict __state,
536
const char *__restrict __fmt, ...)
536
const char *__restrict __fmt, ...)
537
537
__attribute__ ((__format__ (__printf__, 2, 3)));
539
539
/* Similar to the standard gnu error-reporting function error(), but will
545
545
*parsing errors*, and the former is for other problems that occur during
546
546
parsing but don't reflect a (syntactic) problem with the input. */
547
547
extern void argp_failure (const struct argp_state *__restrict __state,
548
int __status, int __errnum,
549
const char *__restrict __fmt, ...)
548
int __status, int __errnum,
549
const char *__restrict __fmt, ...)
550
550
__attribute__ ((__format__ (__printf__, 4, 5)));
551
551
extern void __argp_failure (const struct argp_state *__restrict __state,
552
int __status, int __errnum,
553
const char *__restrict __fmt, ...)
552
int __status, int __errnum,
553
const char *__restrict __fmt, ...)
554
554
__attribute__ ((__format__ (__printf__, 4, 5)));
556
556
#if _LIBC || !defined __USE_EXTERN_INLINES
567
567
/* Return the input field for ARGP in the parser corresponding to STATE; used
568
568
by the help routines. */
569
569
extern void *_argp_input (const struct argp *__restrict __argp,
570
const struct argp_state *__restrict __state)
570
const struct argp_state *__restrict __state)
572
572
extern void *__argp_input (const struct argp *__restrict __argp,
573
const struct argp_state *__restrict __state)
573
const struct argp_state *__restrict __state)
576
576
#ifdef __USE_EXTERN_INLINES
added
removed
gnulib/lib/argp.h
