(Argp Special Keys): Document order in which parsers are called for
[kopensolaris-gnu/glibc.git] / manual / argp.texi
1 @ignore
2    Documentation for the argp argument parser
3
4    Copyright (C) 1995, 1996, 1997, 1998, 2000 Free Software Foundation, Inc.
5    This file is part of the GNU C Library.
6    Written by Miles Bader <miles@gnu.ai.mit.edu>.
7
8    The GNU C Library is free software; you can redistribute it and/or
9    modify it under the terms of the GNU Library General Public License as
10    published by the Free Software Foundation; either version 2 of the
11    License, or (at your option) any later version.
12
13    The GNU C Library is distributed in the hope that it will be useful,
14    but WITHOUT ANY WARRANTY; without even the implied warranty of
15    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
16    Library General Public License for more details.
17
18    You should have received a copy of the GNU Library General Public
19    License along with the GNU C Library; see the file COPYING.LIB.  If not,
20    write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
21    Boston, MA 02111-1307, USA.  */
22 @end ignore
23
24 @node Argp, Suboptions, Getopt, Parsing Program Arguments
25 @need 5000
26 @section Parsing Program Options with Argp
27 @cindex argp (program argument parser)
28 @cindex argument parsing with argp
29 @cindex option parsing with argp
30
31 @dfn{Argp} is an interface for parsing unix-style argument vectors
32 (@pxref{Program Arguments}).
33
34 Unlike the more common @code{getopt} interface, it provides many related
35 convenience features in addition to parsing options, such as
36 automatically producing output in response to @samp{--help} and
37 @samp{--version} options (as defined by the GNU coding standards).
38 Doing these things in argp results in a more consistent look for
39 programs that use it, and makes less likely that implementors will
40 neglect to implement them or keep them up-to-date.
41
42 Argp also provides the ability to merge several independently defined
43 option parsers into one, mediating conflicts between them, and making
44 the result appear seamless.  A library can export an argp option parser,
45 which programs can easily use in conjunction with their own option
46 parser.  This results in less work for user programs (indeed, some may
47 use only argument parsers exported by libraries, and have no options of
48 their own), and more consistent option-parsing for the abstractions
49 implemented by the library.
50
51 @pindex argp.h
52 The header file @file{<argp.h>} should be included to use argp.
53
54 @subsection The @code{argp_parse} Function
55
56 The main interface to argp is the @code{argp_parse} function; often, a
57 call to @code{argp_parse} is the only argument-parsing code needed in
58 @code{main} (@pxref{Program Arguments}).
59
60 @comment argp.h
61 @comment GNU
62 @deftypefun {error_t} argp_parse (const struct argp *@var{argp}, int @var{argc}, char **@var{argv}, unsigned @var{flags}, int *@var{arg_index}, void *@var{input})
63 The @code{argp_parse} function parses the arguments in @var{argv}, of
64 length @var{argc}, using the argp parser @var{argp} (@pxref{Argp
65 Parsers}); a value of zero is the same as a @code{struct argp}
66 containing all zeros.  @var{flags} is a set of flag bits that modify the
67 parsing behavior (@pxref{Argp Flags}).  @var{input} is passed through to
68 the argp parser @var{argp}, and has meaning defined by it; a typical
69 usage is to pass a pointer to a structure which can be used for
70 specifying parameters to the parser and passing back results from it.
71
72 Unless the @code{ARGP_NO_EXIT} or @code{ARGP_NO_HELP} flags are included
73 in @var{flags}, calling @code{argp_parse} may result in the program
74 exiting---for instance when an unknown option is encountered.
75 @xref{Program Termination}.
76
77 If @var{arg_index} is non-null, the index of the first unparsed option
78 in @var{argv} is returned in it.
79
80 The return value is zero for successful parsing, or an error code
81 (@pxref{Error Codes}) if an error was detected.  Different argp parsers
82 may return arbitrary error codes, but standard ones are @code{ENOMEM} if
83 a memory allocation error occurred, or @code{EINVAL} if an unknown option
84 or option argument was encountered.
85 @end deftypefun
86
87 @menu
88 * Globals: Argp Global Variables.  Global argp parameters.
89 * Parsers: Argp Parsers.        Defining parsers for use with @code{argp_parse}.
90 * Flags: Argp Flags.            Flags that modify the behavior of @code{argp_parse}.
91 * Help: Argp Help.              Printing help messages when not parsing.
92 * Examples: Argp Examples.      Simple examples of programs using argp.
93 * Customization: Argp User Customization.
94                                 Users may control the @samp{--help} output format.
95 @end menu
96
97 @node Argp Global Variables, Argp Parsers, , Argp
98 @subsection Argp Global Variables
99
100 These variables make it very easy for every user program to implement
101 the @samp{--version} option and provide a bug-reporting address in the
102 @samp{--help} output (which is implemented by argp regardless).
103
104 @comment argp.h
105 @comment GNU
106 @deftypevar {const char *} argp_program_version
107 If defined or set by the user program to a non-zero value, then a
108 @samp{--version} option is added when parsing with @code{argp_parse}
109 (unless the @code{ARGP_NO_HELP} flag is used), which will print this
110 string followed by a newline and exit (unless the @code{ARGP_NO_EXIT}
111 flag is used).
112 @end deftypevar
113
114 @comment argp.h
115 @comment GNU
116 @deftypevar {const char *} argp_program_bug_address
117 If defined or set by the user program to a non-zero value,
118 @code{argp_program_bug_address} should point to a string that is the
119 bug-reporting address for the program.  It will be printed at the end of
120 the standard output for the @samp{--help} option, embedded in a sentence
121 that says something like @samp{Report bugs to @var{address}.}.
122 @end deftypevar
123
124 @need 1500
125 @comment argp.h
126 @comment GNU
127 @defvar argp_program_version_hook
128 If defined or set by the user program to a non-zero value, then a
129 @samp{--version} option is added when parsing with @code{argp_parse}
130 (unless the @code{ARGP_NO_HELP} flag is used), which calls this function
131 to print the version, and then exits with a status of 0 (unless the
132 @code{ARGP_NO_EXIT} flag is used).  It should point to a function with
133 the following type signature:
134
135 @smallexample
136 void @var{print-version} (FILE *@var{stream}, struct argp_state *@var{state})
137 @end smallexample
138
139 @noindent
140 @xref{Argp Parsing State}, for an explanation of @var{state}.
141
142 This variable takes precedent over @code{argp_program_version}, and is
143 useful if a program has version information that cannot be easily
144 specified as a simple string.
145 @end defvar
146
147 @comment argp.h
148 @comment GNU
149 @deftypevar error_t argp_err_exit_status
150 The exit status that argp will use when exiting due to a parsing error.
151 If not defined or set by the user program, this defaults to
152 @code{EX_USAGE} from @file{<sysexits.h>}.
153 @end deftypevar
154
155 @node Argp Parsers, Argp Flags, Argp Global Variables, Argp
156 @subsection Specifying Argp Parsers
157
158 The first argument to the @code{argp_parse} function is a pointer to a
159 @code{struct argp}, which known as an @dfn{argp parser}:
160
161 @comment argp.h
162 @comment GNU
163 @deftp {Data Type} {struct argp}
164 This structure specifies how to parse a given set of options and
165 arguments, perhaps in conjunction with other argp parsers.  It has the
166 following fields:
167
168 @table @code
169 @item const struct argp_option *options
170 A pointer to a vector of @code{argp_option} structures specifying which
171 options this argp parser understands; it may be zero if there are no
172 options at all.  @xref{Argp Option Vectors}.
173
174 @item argp_parser_t parser
175 A pointer to a function that defines actions for this parser; it is
176 called for each option parsed, and at other well-defined points in the
177 parsing process.  A value of zero is the same as a pointer to a
178 function that always returns @code{ARGP_ERR_UNKNOWN}.
179 @xref{Argp Parser Functions}.
180
181 @item const char *args_doc
182 If non-zero, a string describing what non-option arguments are wanted by
183 this parser; it is only used to print the @samp{Usage:} message.  If it
184 contains newlines, the strings separated by them are considered
185 alternative usage patterns, and printed on separate lines (lines after
186 the first are prefixed by @samp{ or: } instead of @samp{Usage:}).
187
188 @item const char *doc
189 If non-zero, a string containing extra text to be printed before and
190 after the options in a long help message, with the two sections
191 separated by a vertical tab (@code{'\v'}, @code{'\013'}) character.  By
192 convention, the documentation before the options is just a short string
193 saying what the program does, and that afterwards is longer, describing
194 the behavior in more detail.
195
196 @item const struct argp_child *children
197 A pointer to a vector of @code{argp_children} structures specifying
198 additional argp parsers that should be combined with this one.
199 @xref{Argp Children}.
200
201 @item char *(*help_filter)(int @var{key}, const char *@var{text}, void *@var{input})
202 If non-zero, a pointer to a function to filter the output of help
203 messages.  @xref{Argp Help Filtering}.
204 @end table
205 @end deftp
206
207 The @code{options}, @code{parser}, @code{args_doc}, and @code{doc}
208 fields are usually all that are needed.  If an argp parser is defined as
209 an initialized C variable, only the used fields need be specified in
210 the initializer---the rest will default to zero due to the way C
211 structure initialization works (this fact is exploited for most argp
212 structures, grouping the most-used fields near the beginning, so that
213 unused fields can simply be left unspecified).
214
215 @menu
216 * Options: Argp Option Vectors.   Specifying options in an argp parser.
217 * Argp Parser Functions::         Defining actions for an argp parser.
218 * Children: Argp Children.        Combining multiple argp parsers.
219 * Help Filtering: Argp Help Filtering.  Customizing help output for an argp parser.
220 @end menu
221
222 @node Argp Option Vectors, Argp Parser Functions, Argp Parsers, Argp Parsers
223 @subsection Specifying Options in an Argp Parser
224
225 The @code{options} field in a @code{struct argp} points to a vector of
226 @code{struct argp_option} structures, each of which specifies an option
227 that argp parser supports (actually, sometimes multiple entries may used
228 for a single option if it has many names).  It should be terminated by
229 an entry with zero in all fields (note that when using an initialized C
230 array for options, writing @code{@{ 0 @}} is enough to achieve this).
231
232 @comment argp.h
233 @comment GNU
234 @deftp {Data Type} {struct argp_option}
235 This structure specifies a single option that an argp parser
236 understands, and how to parse and document it.  It has the following fields:
237
238 @table @code
239 @item const char *name
240 The long name for this option, corresponding to the long option
241 @samp{--@var{name}}; this field can be zero if this option only has a
242 short name.  To specify multiple names for an option, additional entries
243 may follow this one, with the @code{OPTION_ALIAS} flag set (@pxref{Argp
244 Option Flags}).
245
246 @item int key
247 The integer key that is provided to the argp parser's parsing function
248 when this option is being parsed.  Also, if @var{key} has a value that
249 is a printable @sc{ascii} character (i.e., @code{isascii (@var{key})} is
250 true), it @emph{also} specifies a short option @samp{-@var{char}}, where
251 @var{char} is the @sc{ascii} character with the code @var{key}.
252
253 @item const char *arg
254 If non-zero, this is the name of an argument associated with this
255 option, which must be provided (e.g., with the
256 @samp{--@var{name}=@var{value}} or @samp{-@var{char} @var{value}}
257 syntaxes) unless the @code{OPTION_ARG_OPTIONAL} flag (@pxref{Argp Option
258 Flags}) is set, in which case it @emph{may} be provided.
259
260 @item int flags
261 Flags associated with this option (some of which are referred to above).
262 @xref{Argp Option Flags}.
263
264 @item const char *doc
265 A documentation string for this option, for printing in help messages.
266
267 If both the @code{name} and @code{key} fields are zero, this string
268 will be printed out-dented from the normal option column, making it
269 useful as a group header (it will be the first thing printed in its
270 group); in this usage, it's conventional to end the string with a
271 @samp{:} character.
272
273 @item int group
274 The group this option is in.
275
276 In a long help message, options are sorted alphabetically within each
277 group, and the groups presented in the order 0, 1, 2, @dots{}, @var{n},
278 @minus{}@var{m}, @dots{}, @minus{}2, @minus{}1.  Every entry in an
279 options array with this
280 field 0 will inherit the group number of the previous entry, or zero if
281 it's the first one, unless its a group header (@code{name} and
282 @code{key} fields both zero), in which case, the previous entry + 1 is
283 the default.  Automagic options such as @samp{--help} are put into group
284 @minus{}1.
285
286 Note that because of C structure initialization rules, this field
287 often need not be specified, because 0 is the right value.
288 @end table
289 @end deftp
290
291 @menu
292 * Flags: Argp Option Flags.     Flags for options.
293 @end menu
294
295 @node Argp Option Flags, , , Argp Option Vectors
296 @subsubsection Flags for Argp Options
297
298 The following flags may be or'd together in the @code{flags} field of a
299 @code{struct argp_option}, and control various aspects of how that
300 option is parsed or displayed in help messages:
301
302 @vtable @code
303 @comment argp.h
304 @comment GNU
305 @item OPTION_ARG_OPTIONAL
306 The argument associated with this option is optional.
307
308 @comment argp.h
309 @comment GNU
310 @item OPTION_HIDDEN
311 This option isn't displayed in any help messages.
312
313 @comment argp.h
314 @comment GNU
315 @item OPTION_ALIAS
316 This option is an alias for the closest previous non-alias option.  This
317 means that it will be displayed in the same help entry, and will inherit
318 fields other than @code{name} and @code{key} from the aliased option.
319
320 @comment argp.h
321 @comment GNU
322 @item OPTION_DOC
323 This option isn't actually an option (and so should be ignored by the
324 actual option parser), but rather an arbitrary piece of documentation
325 that should be displayed in much the same manner as the options (known
326 as a @dfn{documentation option}).
327
328 If this flag is set, then the option @code{name} field is displayed
329 unmodified (e.g., no @samp{--} prefix is added) at the left-margin
330 (where a @emph{short} option would normally be displayed), and the
331 documentation string in the normal place.  For purposes of sorting, any
332 leading whitespace and punctuation is ignored, except that if the first
333 non-whitespace character is not @samp{-}, this entry is displayed after
334 all options (and @code{OPTION_DOC} entries with a leading @samp{-}) in
335 the same group.
336
337 @comment argp.h
338 @comment GNU
339 @item OPTION_NO_USAGE
340 This option shouldn't be included in `long' usage messages (but is still
341 included in help messages).  This is mainly intended for options that
342 are completely documented in an argp's @code{args_doc} field
343 (@pxref{Argp Parsers}), in which case including the option
344 in the generic usage list would be redundant.
345
346 For instance, if @code{args_doc} is @code{"FOO BAR\n-x BLAH"}, and the
347 @samp{-x} option's purpose is to distinguish these two cases, @samp{-x}
348 should probably be marked @code{OPTION_NO_USAGE}.
349 @end vtable
350
351 @node Argp Parser Functions, Argp Children, Argp Option Vectors, Argp Parsers
352 @subsection Argp Parser Functions
353
354 The function pointed to by the @code{parser} field in a @code{struct
355 argp} (@pxref{Argp Parsers}) defines what actions take place in response
356 to each option or argument that is parsed, and is also used as a hook,
357 to allow a parser to do something at certain other points during
358 parsing.
359
360 @need 2000
361 Argp parser functions have the following type signature:
362
363 @cindex argp parser functions
364 @smallexample
365 error_t @var{parser} (int @var{key}, char *@var{arg}, struct argp_state *@var{state})
366 @end smallexample
367
368 @noindent
369 where the arguments are as follows:
370
371 @table @var
372 @item key
373 For each option that is parsed, @var{parser} is called with a value of
374 @var{key} from that option's @code{key} field in the option vector
375 (@pxref{Argp Option Vectors}).  @var{parser} is also called at other
376 times with special reserved keys, such as @code{ARGP_KEY_ARG} for
377 non-option arguments.  @xref{Argp Special Keys}.
378
379 @item arg
380 If @var{key} is an option, @var{arg} is the value given for it, or zero
381 if no value was specified.  Only options that have a non-zero @code{arg}
382 field can ever have a value, and those must @emph{always} have a value,
383 unless the @code{OPTION_ARG_OPTIONAL} flag was specified (if the input
384 being parsed specifies a value for an option that doesn't allow one, an
385 error results before @var{parser} ever gets called).
386
387 If @var{key} is @code{ARGP_KEY_ARG}, @var{arg} is a non-option argument;
388 other special keys always have a zero @var{arg}.
389
390 @item state
391 @var{state} points to a @code{struct argp_state}, containing useful
392 information about the current parsing state for use by @var{parser}.
393 @xref{Argp Parsing State}.
394 @end table
395
396 When @var{parser} is called, it should perform whatever action is
397 appropriate for @var{key}, and return either @code{0} for success,
398 @code{ARGP_ERR_UNKNOWN}, if the value of @var{key} is not handled by
399 this parser function, or a unix error code if a real error occurred
400 (@pxref{Error Codes}).
401
402 @comment argp.h
403 @comment GNU
404 @deftypevr Macro int ARGP_ERR_UNKNOWN
405 Argp parser functions should return @code{ARGP_ERR_UNKNOWN} for any
406 @var{key} value they do not recognize, or for non-option arguments
407 (@code{@var{key} == ARGP_KEY_ARG}) that they do not wish to handle.
408 @end deftypevr
409
410 @need 3000
411 A typical parser function uses a switch statement on @var{key}:
412
413 @smallexample
414 error_t
415 parse_opt (int key, char *arg, struct argp_state *state)
416 @{
417   switch (key)
418     @{
419     case @var{option_key}:
420       @var{action}
421       break;
422     @dots{}
423     default:
424       return ARGP_ERR_UNKNOWN;
425     @}
426   return 0;
427 @}
428 @end smallexample
429
430 @menu
431 * Keys: Argp Special Keys.           Special values for the @var{key} argument.
432 * State: Argp Parsing State.         What the @var{state} argument refers to.
433 * Functions: Argp Helper Functions.  Functions to help during argp parsing.
434 @end menu
435
436 @node Argp Special Keys, Argp Parsing State, , Argp Parser Functions
437 @subsubsection Special Keys for Argp Parser Functions
438
439 In addition to key values corresponding to user options, the @var{key}
440 argument to argp parser functions may have a number of other special
441 values (@var{arg} and @var{state} refer to parser function arguments;
442 @pxref{Argp Parser Functions}):
443
444 @vtable @code
445 @comment argp.h
446 @comment GNU
447 @item ARGP_KEY_ARG
448 This is not an option at all, but rather a command line argument, whose
449 value is pointed to by @var{arg}.
450
451 When there are multiple parser functions (due to argp parsers being
452 combined), it's impossible to know which one wants to handle an
453 argument, so each is called in turn, until one returns 0 or an error
454 other than @code{ARGP_ERR_UNKNOWN}; if an argument is handled by no one,
455 @code{argp_parse} immediately returns success, without parsing any more
456 arguments.
457
458 Once a parser function returns success for this key, that fact is
459 recorded, and the @code{ARGP_KEY_NO_ARGS} case won't be used.
460 @emph{However}, if while processing the argument, a parser function
461 decrements the @code{next} field of its @var{state} argument, the option
462 won't be considered processed; this is to allow you to actually modify
463 the argument (perhaps into an option), and have it processed again.
464
465 @comment argp.h
466 @comment GNU
467 @item ARGP_KEY_ARGS
468 If a parser function returns @code{ARGP_ERR_UNKNOWN} for
469 @code{ARGP_KEY_ARG}, it is immediately called again with the key
470 @code{ARGP_KEY_ARGS}, which has a similar meaning, but is slightly more
471 convenient for consuming all remaining arguments.  @var{arg} is 0, and
472 the tail of the argument vector may be found at @code{@var{state}->argv
473 + @var{state}->next}.  If success is returned for this key, and
474 @code{@var{state}->next} is unchanged, then all remaining arguments are
475 considered to have been consumed, otherwise, the amount by which
476 @code{@var{state}->next} has been adjust indicates how many were used.
477 For instance, here's an example that uses both, for different args:
478
479 @smallexample
480 ...
481 case ARGP_KEY_ARG:
482   if (@var{state}->arg_num == 0)
483     /* First argument */
484     first_arg = @var{arg};
485   else
486     /* Let the next case parse it.  */
487     return ARGP_KEY_UNKNOWN;
488   break;
489 case ARGP_KEY_ARGS:
490   remaining_args = @var{state}->argv + @var{state}->next;
491   num_remaining_args = @var{state}->argc - @var{state}->next;
492   break;
493 @end smallexample
494
495 @comment argp.h
496 @comment GNU
497 @item ARGP_KEY_END
498 There are no more command line arguments at all.  The parser functions
499 are called in different order (means children first) for this value
500 which allows each parser to clean up its state for the parent.
501
502 @comment argp.h
503 @comment GNU
504 @item ARGP_KEY_NO_ARGS
505 Because it's common to want to do some special processing if there
506 aren't any non-option args, parser functions are called with this key if
507 they didn't successfully process any non-option arguments.  Called just
508 before @code{ARGP_KEY_END} (where more general validity checks on
509 previously parsed arguments can take place).
510
511 @comment argp.h
512 @comment GNU
513 @item ARGP_KEY_INIT
514 Passed in before any parsing is done.  Afterwards, the values of each
515 element of the @code{child_input} field of @var{state}, if any, are
516 copied to each child's state to be the initial value of the @code{input}
517 when @emph{their} parsers are called.
518
519 @comment argp.h
520 @comment GNU
521 @item ARGP_KEY_SUCCESS
522 Passed in when parsing has successfully been completed (even if there are
523 still arguments remaining).
524
525 @comment argp.h
526 @comment GNU
527 @item ARGP_KEY_ERROR
528 Passed in if an error has occurred, and parsing terminated (in which case
529 a call with a key of @code{ARGP_KEY_SUCCESS} is never made).
530
531 @comment argp.h
532 @comment GNU
533 @item ARGP_KEY_FINI
534 The final key ever seen by any parser (even after
535 @code{ARGP_KEY_SUCCESS} and @code{ARGP_KEY_ERROR}).  Any resources
536 allocated by @code{ARGP_KEY_INIT} may be freed here (although sometimes
537 certain resources allocated there are to be returned to the caller after
538 a successful parse; in that case, those particular resources can be
539 freed in the @code{ARGP_KEY_ERROR} case).
540 @end vtable
541
542 In all cases, @code{ARGP_KEY_INIT} is the first key seen by parser
543 functions, and @code{ARGP_KEY_FINI} the last (unless an error was
544 returned by the parser for @code{ARGP_KEY_INIT}).  Other keys can occur
545 in one the following orders (@var{opt} refers to an arbitrary option
546 key):
547
548 @table @asis
549 @item @var{opt}@dots{} @code{ARGP_KEY_NO_ARGS} @code{ARGP_KEY_END} @code{ARGP_KEY_SUCCESS}
550 The arguments being parsed contained no non-option arguments at all.
551
552 @item ( @var{opt} | @code{ARGP_KEY_ARG} )@dots{} @code{ARGP_KEY_END} @code{ARGP_KEY_SUCCESS}
553 All non-option arguments were successfully handled by a parser function
554 (there may be multiple parser functions if multiple argp parsers were
555 combined).
556
557 @item ( @var{opt} | @code{ARGP_KEY_ARG} )@dots{} @code{ARGP_KEY_SUCCESS}
558 Some non-option argument was unrecognized.
559
560 This occurs when every parser function returns @code{ARGP_KEY_UNKNOWN}
561 for an argument, in which case parsing stops at that argument.  If
562 @var{arg_index} is a null pointer otherwise an error occurs.
563 @end table
564
565 In all cases, if a non-null value for @var{arg_index} was passed to
566 @code{argp_parse}, the index of the first unparsed command-line argument
567 is passed back in it.
568
569 If an error occurs (either detected by argp, or because a parser
570 function returned an error value), then each parser is called with
571 @code{ARGP_KEY_ERROR}, and no further calls are made except the final
572 call with @code{ARGP_KEY_FINI}.
573
574 @node Argp Helper Functions, , Argp Parsing State, Argp Parser Functions
575 @subsubsection Functions For Use in Argp Parsers
576
577 Argp provides a number of functions for the user of argp parser
578 functions (@pxref{Argp Parser Functions}), mostly for producing error
579 messages.  These take as their first argument the @var{state} argument
580 to the parser function (@pxref{Argp Parsing State}).
581
582 @cindex usage messages, in argp
583 @comment argp.h
584 @comment GNU
585 @deftypefun void argp_usage (const struct argp_state *@var{state})
586 Output the standard usage message for the argp parser referred to by
587 @var{state} to @code{@var{state}->err_stream} and terminate the program
588 with @code{exit (argp_err_exit_status)} (@pxref{Argp Global Variables}).
589 @end deftypefun
590
591 @cindex syntax error messages, in argp
592 @comment argp.h
593 @comment GNU
594 @deftypefun void argp_error (const struct argp_state *@var{state}, const char *@var{fmt}, @dots{})
595 Print the printf format string @var{fmt} and following args, preceded by
596 the program name and @samp{:}, and followed by a @w{@samp{Try @dots{}
597 --help}} message, and terminate the program with an exit status of
598 @code{argp_err_exit_status} (@pxref{Argp Global Variables}).
599 @end deftypefun
600
601 @cindex error messages, in argp
602 @comment argp.h
603 @comment GNU
604 @deftypefun void argp_failure (const struct argp_state *@var{state}, int @var{status}, int @var{errnum}, const char *@var{fmt}, @dots{})
605 Similarly to the standard gnu error-reporting function @code{error},
606 print the printf format string @var{fmt} and following args, preceded by
607 the program name and @samp{:}, and followed by the standard unix error
608 text for @var{errnum} if it is non-zero; then if @var{status} is
609 non-zero, terminate the program with that as its exit status.
610
611 The difference between this function and @code{argp_error} is that
612 @code{argp_error} is for @emph{parsing errors}, whereas
613 @code{argp_failure} is for other problems that occur during parsing but
614 don't reflect a syntactic problem with the input---such as illegal
615 values for options, bad phase of the moon, etc.
616 @end deftypefun
617
618 @comment argp.h
619 @comment GNU
620 @deftypefun void argp_state_help (const struct argp_state *@var{state}, FILE *@var{stream}, unsigned @var{flags})
621 Output a help message for the argp parser referred to by @var{state} to
622 @var{stream}.  The @var{flags} argument determines what sort of help
623 message is produced.  @xref{Argp Help Flags}.
624 @end deftypefun
625
626 Error output is sent to @code{@var{state}->err_stream}, and the program
627 name printed is @code{@var{state}->name}.
628
629 The output or program termination behavior of these functions may be
630 suppressed if the @code{ARGP_NO_EXIT} or @code{ARGP_NO_ERRS} flags,
631 respectively, were passed to @code{argp_parse}.  @xref{Argp Flags}.
632
633 This behavior is useful if an argp parser is exported for use by other
634 programs (e.g., by a library), and may be used in a context where it is
635 not desirable to terminate the program in response to parsing errors.
636 In argp parsers intended for such general use, calls to any of these
637 functions should be followed by code return of an appropriate error code
638 for the case where the program @emph{doesn't} terminate; for example:
639
640 @smallexample
641 if (@var{bad argument syntax})
642   @{
643      argp_usage (@var{state});
644      return EINVAL;
645   @}
646 @end smallexample
647
648 @noindent
649 If it's known that a parser function will only be used when
650 @code{ARGP_NO_EXIT} is not set, the return may be omitted.
651
652 @node Argp Parsing State, Argp Helper Functions, Argp Special Keys, Argp Parser Functions
653 @subsubsection Argp Parsing State
654
655 The third argument to argp parser functions (@pxref{Argp Parser
656 Functions}) is a pointer to a @code{struct argp_state}, which contains
657 information about the state of the option parsing.
658
659 @comment argp.h
660 @comment GNU
661 @deftp {Data Type} {struct argp_state}
662 This structure has the following fields, which may be modified as noted:
663
664 @table @code
665 @item const struct argp *const root_argp
666 The top level argp parser being parsed.  Note that this is often
667 @emph{not} the same @code{struct argp} passed into @code{argp_parse} by
668 the invoking program (@pxref{Argp}), but instead an internal argp parser
669 that contains options implemented by @code{argp_parse} itself (such as
670 @samp{--help}).
671
672 @item int argc
673 @itemx char **argv
674 The argument vector being parsed.  May be modified.
675
676 @item int next
677 The index in @code{argv} of the next argument to be parsed.  May be modified.
678
679 One way to consume all remaining arguments in the input is to set
680 @code{@var{state}->next = @var{state}->argc} (perhaps after recording
681 the value of the @code{next} field to find the consumed arguments).
682 Also, you can cause the current option to be re-parsed by decrementing
683 this field, and then modifying
684 @code{@var{state}->argv[@var{state}->next]} to be the option that should
685 be reexamined.
686
687 @item unsigned flags
688 The flags supplied to @code{argp_parse}.  May be modified, although some
689 flags may only take effect when @code{argp_parse} is first invoked.
690 @xref{Argp Flags}.
691
692 @item unsigned arg_num
693 While calling a parsing function with the @var{key} argument
694 @code{ARGP_KEY_ARG}, this is the number of the current arg, starting at
695 0, and incremented after each such call returns.  At all other times,
696 this is the number of such arguments that have been processed.
697
698 @item int quoted
699 If non-zero, the index in @code{argv} of the first argument following a
700 special @samp{--} argument (which prevents anything following being
701 interpreted as an option).  Only set once argument parsing has proceeded
702 past this point.
703
704 @item void *input
705 An arbitrary pointer passed in from the caller of @code{argp_parse}, in
706 the @var{input} argument.
707
708 @item void **child_inputs
709 Values to pass to child parsers.  This vector will be the same length as
710 the number of children in the current parser, and each child parser will
711 be given the value of @code{@var{state}->child_inputs[@var{i}]} as
712 @emph{its} @code{@var{state}->input} field, where @var{i} is the index
713 of the child in the this parser's @code{children} field.  @xref{Argp
714 Children}.
715
716 @item void *hook
717 For the parser function's use.  Initialized to 0, but otherwise ignored
718 by argp.
719
720 @item char *name
721 The name used when printing messages.  This is initialized to
722 @code{argv[0]}, or @code{program_invocation_name} if that is
723 unavailable.
724
725 @item FILE *err_stream
726 @itemx FILE *out_stream
727 Stdio streams used when argp prints something; error messages are
728 printed to @code{err_stream}, and all other output (such as
729 @samp{--help} output) to @code{out_stream}.  These are initialized to
730 @code{stderr} and @code{stdout} respectively (@pxref{Standard Streams}).
731
732 @item void *pstate
733 Private, for use by the argp implementation.
734 @end table
735 @end deftp
736
737 @node Argp Children, Argp Help Filtering, Argp Parser Functions, Argp Parsers
738 @subsection Combining Multiple Argp Parsers
739
740 The @code{children} field in a @code{struct argp} allows other argp
741 parsers to be combined with the referencing one to parse a single set of
742 arguments.  It should point to a vector of @code{struct argp_child},
743 terminated by an entry having a value of zero in the @code{argp} field.
744
745 Where conflicts between combined parsers arise (for instance, if two
746 specify an option with the same name), they are resolved in favor of
747 the parent argp parsers, or earlier argp parsers in the list of children.
748
749 @comment argp.h
750 @comment GNU
751 @deftp {Data Type} {struct argp_child}
752 An entry in the list of subsidiary argp parsers pointed to by the
753 @code{children} field in a @code{struct argp}.  The fields are as follows:
754
755 @table @code
756 @item const struct argp *argp
757 The child argp parser, or zero to end the list.
758
759 @item int flags
760 Flags for this child.
761
762 @item const char *header
763 If non-zero, an optional header to be printed in help output before the
764 child options.  As a side-effect, a non-zero value forces the child
765 options to be grouped together; to achieve this effect without actually
766 printing a header string, use a value of @code{""}.  As with header
767 strings specified in an option entry, the value conventionally has
768 @samp{:} as the last character.  @xref{Argp Option Vectors}.
769
770 @item int group
771 Where to group the child options relative to the other (`consolidated')
772 options in the parent argp parser.  The values are the same as the
773 @code{group} field in @code{struct argp_option} (@pxref{Argp Option
774 Vectors}), but all child-groupings follow parent options at a particular
775 group level.  If both this field and @code{header} are zero, then the
776 child's options aren't grouped together at all, but rather merged with
777 the parent options (merging the child's grouping levels with the
778 parents).
779 @end table
780 @end deftp
781
782 @node Argp Flags, Argp Help, Argp Parsers, Argp
783 @subsection Flags for @code{argp_parse}
784
785 The default behavior of @code{argp_parse} is designed to be convenient
786 for the most common case of parsing program command line argument.  To
787 modify these defaults, the following flags may be or'd together in the
788 @var{flags} argument to @code{argp_parse}:
789
790 @vtable @code
791 @comment argp.h
792 @comment GNU
793 @item ARGP_PARSE_ARGV0
794 Don't ignore the first element of the @var{argv} argument to
795 @code{argp_parse}.  Normally (and always unless @code{ARGP_NO_ERRS} is
796 set) the first element of the argument vector is skipped for option
797 parsing purposes, as it corresponds to the program name in a command
798 line.
799
800 @comment argp.h
801 @comment GNU
802 @item ARGP_NO_ERRS
803 Don't print error messages for unknown options to @code{stderr}; unless
804 this flag is set, @code{ARGP_PARSE_ARGV0} is ignored, as @code{argv[0]}
805 is used as the program name in the error messages.  This flag implies
806 @code{ARGP_NO_EXIT} (on the assumption that silent exiting upon errors
807 is bad behaviour).
808
809 @comment argp.h
810 @comment GNU
811 @item ARGP_NO_ARGS
812 Don't parse any non-option args.  Normally non-option args are parsed by
813 calling the parse functions with a key of @code{ARGP_KEY_ARG}, and the
814 actual arg as the value.  This flag needn't normally be set, as the
815 normal behavior is to stop parsing as soon as some argument isn't
816 accepted by a parsing function.  @xref{Argp Parser Functions}.
817
818 @comment argp.h
819 @comment GNU
820 @item ARGP_IN_ORDER
821 Parse options and arguments in the same order they occur on the command
822 line---normally they're rearranged so that all options come first
823
824 @comment argp.h
825 @comment GNU
826 @item ARGP_NO_HELP
827 Don't provide the standard long option @samp{--help}, which ordinarily
828 causes usage and option help information to be output to @code{stdout},
829 and @code{exit (0)} called.
830
831 @comment argp.h
832 @comment GNU
833 @item ARGP_NO_EXIT
834 Don't exit on errors (they may still result in error messages).
835
836 @comment argp.h
837 @comment GNU
838 @item ARGP_LONG_ONLY
839 Use the gnu getopt `long-only' rules for parsing arguments.  This
840 allows long-options to be recognized with only a single @samp{-} (for
841 instances, @samp{-help}), but results in a generally somewhat less
842 useful interface, that conflicts with the way most GNU programs work.
843 For this reason, its use is discouraged.
844
845 @comment argp.h
846 @comment GNU
847 @item ARGP_SILENT
848 Turns off any message-printing/exiting options, specifically
849 @code{ARGP_NO_EXIT}, @code{ARGP_NO_ERRS}, and @code{ARGP_NO_HELP}.
850 @end vtable
851
852 @node Argp Help Filtering, , Argp Children, Argp Parsers
853 @need 2000
854 @subsection Customizing Argp Help Output
855
856 The @code{help_filter} field in a @code{struct argp} is a pointer to a
857 function to filter the text of help messages before displaying them.
858 They have a function signature like:
859
860 @smallexample
861 char *@var{help-filter} (int @var{key}, const char *@var{text}, void *@var{input})
862 @end smallexample
863
864 @noindent
865 where @var{key} is either a key from an option, in which case @var{text}
866 is that option's help text (@pxref{Argp Option Vectors}), or one of the
867 special keys with names beginning with @samp{ARGP_KEY_HELP_}, describing
868 which other help text @var{text} is (@pxref{Argp Help Filter Keys}).
869
870 The function should return either @var{text}, if it should be used
871 as-is, a replacement string, which should be allocated using
872 @code{malloc}, and will be freed by argp, or zero, meaning `print
873 nothing'.  The value of @var{text} supplied is @emph{after} any
874 translation has been done, so if any of the replacement text also needs
875 translation, that should be done by the filter function.  @var{input} is
876 either the input supplied to @code{argp_parse}, or zero, if
877 @code{argp_help} was called directly by the user.
878
879 @menu
880 * Keys: Argp Help Filter Keys.  Special @var{key} values for help filter functions.
881 @end menu
882
883 @node Argp Help Filter Keys, , , Argp Help Filtering
884 @subsubsection Special Keys for Argp Help Filter Functions
885
886 The following special values may be passed to an argp help filter
887 function as the first argument, in addition to key values for user
888 options, and specify which help text the @var{text} argument contains:
889
890 @vtable @code
891 @comment argp.h
892 @comment GNU
893 @item ARGP_KEY_HELP_PRE_DOC
894 Help text preceding options.
895
896 @comment argp.h
897 @comment GNU
898 @item ARGP_KEY_HELP_POST_DOC
899 Help text following options.
900
901 @comment argp.h
902 @comment GNU
903 @item ARGP_KEY_HELP_HEADER
904 Option header string.
905
906 @comment argp.h
907 @comment GNU
908 @item ARGP_KEY_HELP_EXTRA
909 After all other documentation; @var{text} is zero for this key.
910
911 @comment argp.h
912 @comment GNU
913 @item ARGP_KEY_HELP_DUP_ARGS_NOTE
914 The explanatory note emitted when duplicate option arguments have been
915 suppressed.
916
917 @comment argp.h
918 @comment GNU
919 @item ARGP_KEY_HELP_ARGS_DOC
920 The argument doc string (the @code{args_doc} field from the argp parser;
921 @pxref{Argp Parsers}).
922 @end vtable
923
924 @node Argp Help, Argp Examples, Argp Flags, Argp
925 @subsection The @code{argp_help} Function
926
927 Normally programs using argp need not worry too much about printing
928 argument-usage-type help messages, because the standard @samp{--help}
929 option is handled automatically by argp, and the typical error cases can
930 be handled using @code{argp_usage} and @code{argp_error} (@pxref{Argp
931 Helper Functions}).
932
933 However, if it's desirable to print a standard help message in some
934 context other than parsing the program options, argp offers the
935 @code{argp_help} interface.
936
937 @comment argp.h
938 @comment GNU
939 @deftypefun void argp_help (const struct argp *@var{argp}, FILE *@var{stream}, unsigned @var{flags}, char *@var{name})
940 Output a help message for the argp parser @var{argp} to @var{stream}.
941 What sort of messages is printed is determined by @var{flags}.
942
943 Any options such as @samp{--help} that are implemented automatically by
944 argp itself will @emph{not} be present in the help output; for this
945 reason, it is better to use @code{argp_state_help} if calling from
946 within an argp parser function.  @xref{Argp Helper Functions}.
947 @end deftypefun
948
949 @menu
950 * Flags: Argp Help Flags.       Specifying what sort of help message to print.
951 @end menu
952
953 @node Argp Help Flags, , , Argp Help
954 @subsection Flags for the @code{argp_help} Function
955
956 When calling @code{argp_help} (@pxref{Argp Help}), or
957 @code{argp_state_help} (@pxref{Argp Helper Functions}), exactly what is
958 output is determined by the @var{flags} argument, which should consist
959 of any of the following flags, or'd together:
960
961 @vtable @code
962 @item ARGP_HELP_USAGE
963 A unix @samp{Usage:} message that explicitly lists all options.
964
965 @item ARGP_HELP_SHORT_USAGE
966 A unix @samp{Usage:} message that displays only an appropriate
967 placeholder to indicate where the options go; useful for showing
968 the non-option argument syntax.
969
970 @item ARGP_HELP_SEE
971 A @samp{Try @dots{} for more help} message; @samp{@dots{}} contains the
972 program name and @samp{--help}.
973
974 @item ARGP_HELP_LONG
975 A verbose option help message that gives each option understood along
976 with its documentation string.
977
978 @item ARGP_HELP_PRE_DOC
979 The part of the argp parser doc string that precedes the verbose option help.
980
981 @item ARGP_HELP_POST_DOC
982 The part of the argp parser doc string that follows the verbose option help.
983
984 @item ARGP_HELP_DOC
985 @code{(ARGP_HELP_PRE_DOC | ARGP_HELP_POST_DOC)}
986
987 @item ARGP_HELP_BUG_ADDR
988 A message saying where to report bugs for this program, if the
989 @code{argp_program_bug_address} variable contains one.
990
991 @item ARGP_HELP_LONG_ONLY
992 Modify any output appropriately to reflect @code{ARGP_LONG_ONLY} mode.
993 @end vtable
994
995 The following flags are only understood when used with
996 @code{argp_state_help}, and control whether the function returns after
997 printing its output, or terminates the program:
998
999 @vtable @code
1000 @item ARGP_HELP_EXIT_ERR
1001 Terminate the program with @code{exit (argp_err_exit_status)}.
1002
1003 @item ARGP_HELP_EXIT_OK
1004 Terminate the program with @code{exit (0)}.
1005 @end vtable
1006
1007 The following flags are combinations of the basic ones for printing
1008 standard messages:
1009
1010 @vtable @code
1011 @item ARGP_HELP_STD_ERR
1012 Assuming an error message for a parsing error has already printed,
1013 prints a note on how to get help, and terminates the program with an
1014 error.
1015
1016 @item ARGP_HELP_STD_USAGE
1017 Prints a standard usage message and terminates the program with an
1018 error.  This is used when no more specific error message is appropriate.
1019
1020 @item ARGP_HELP_STD_HELP
1021 Prints the standard response for a @samp{--help} option, and terminates
1022 the program successfully.
1023 @end vtable
1024
1025 @node Argp Examples, Argp User Customization, Argp Help, Argp
1026 @subsection Argp Examples
1027
1028 These example programs demonstrate the basic usage of argp.
1029
1030 @menu
1031 * 1: Argp Example 1.            A minimal program using argp.
1032 * 2: Argp Example 2.            A program using only default options.
1033 * 3: Argp Example 3.            A simple program with user options.
1034 * 4: Argp Example 4.            Combining multiple argp parsers.
1035 @end menu
1036
1037 @node Argp Example 1, Argp Example 2, , Argp Examples
1038 @subsubsection A Minimal Program Using Argp
1039
1040 This is (probably) the smallest possible program that uses argp.
1041 It won't do much except give an error messages and exit when there are any
1042 arguments, and print a (rather pointless) message for @samp{--help}.
1043
1044 @smallexample
1045 @include argp-ex1.c.texi
1046 @end smallexample
1047
1048 @node Argp Example 2, Argp Example 3, Argp Example 1, Argp Examples
1049 @subsubsection A Program Using Argp with Only Default Options
1050
1051 This program doesn't use any options or arguments, but uses argp to be
1052 compliant with the GNU standard command line format.
1053
1054 In addition to making sure no arguments are given, and implementing a
1055 @samp{--help} option, this example will have a @samp{--version} option,
1056 and will put the given documentation string and bug address in the
1057 @samp{--help} output, as per GNU standards.
1058
1059 The variable @code{argp} contains the argument parser specification;
1060 adding fields to this structure is the way most parameters are passed to
1061 @code{argp_parse} (the first three fields are usually used, but not in
1062 this small program).  There are also two global variables that argp
1063 knows about defined here, @code{argp_program_version} and
1064 @code{argp_program_bug_address} (they are global variables because they
1065 will almost always be constant for a given program, even if it uses
1066 different argument parsers for various tasks).
1067
1068 @smallexample
1069 @include argp-ex2.c.texi
1070 @end smallexample
1071
1072 @node Argp Example 3, Argp Example 4, Argp Example 2, Argp Examples
1073 @subsubsection A Program Using Argp with User Options
1074
1075 This program uses the same features as example 2, and adds user options
1076 and arguments.
1077
1078 We now use the first four fields in @code{argp} (@pxref{Argp Parsers}),
1079 and specifies @code{parse_opt} as the parser function (@pxref{Argp
1080 Parser Functions}).
1081
1082 Note that in this example, @code{main} uses a structure to communicate
1083 with the @code{parse_opt} function, a pointer to which it passes in the
1084 @code{input} argument to @code{argp_parse} (@pxref{Argp}), and is
1085 retrieved by @code{parse_opt} through the @code{input} field in its
1086 @code{state} argument (@pxref{Argp Parsing State}).  Of course, it's
1087 also possible to use global variables instead, but using a structure
1088 like this is somewhat more flexible and clean.
1089
1090 @smallexample
1091 @include argp-ex3.c.texi
1092 @end smallexample
1093
1094 @node Argp Example 4, , Argp Example 3, Argp Examples
1095 @subsubsection A Program Using Multiple Combined Argp Parsers
1096
1097 This program uses the same features as example 3, but has more options,
1098 and somewhat more structure in the @samp{--help} output.  It also shows
1099 how you can `steal' the remainder of the input arguments past a certain
1100 point, for programs that accept a list of items, and the special
1101 @var{key} value @code{ARGP_KEY_NO_ARGS}, which is only given if no
1102 non-option arguments were supplied to the program (@pxref{Argp Special
1103 Keys}).
1104
1105 For structuring the help output, two features are used: @emph{headers},
1106 which are entries in the options vector (@pxref{Argp Option Vectors})
1107 with the first four fields being zero, and a two part documentation
1108 string (in the variable @code{doc}), which allows documentation both
1109 before and after the options (@pxref{Argp Parsers}); the
1110 two parts of @code{doc} are separated by a vertical-tab character
1111 (@code{'\v'}, or @code{'\013'}).  By convention, the documentation
1112 before the options is just a short string saying what the program does,
1113 and that afterwards is longer, describing the behavior in more detail.
1114 All documentation strings are automatically filled for output, although
1115 newlines may be included to force a line break at a particular point.
1116 All documentation strings are also passed to the @code{gettext}
1117 function, for possible translation into the current locale.
1118
1119 @smallexample
1120 @include argp-ex4.c.texi
1121 @end smallexample
1122
1123 @node Argp User Customization, , Argp Examples, Argp
1124 @subsection Argp User Customization
1125
1126 @cindex ARGP_HELP_FMT environment variable
1127 The way formatting of argp @samp{--help} output may be controlled to
1128 some extent by a program's users, by setting the @code{ARGP_HELP_FMT}
1129 environment variable to a comma-separated list (whitespace is ignored)
1130 of the following tokens:
1131
1132 @table @samp
1133 @item dup-args
1134 @itemx no-dup-args
1135 Turn @dfn{duplicate-argument-mode} on or off.  In duplicate argument
1136 mode, if an option which accepts an argument has multiple names, the
1137 argument is shown for each name; otherwise, it is only shown for the
1138 first long option, and a note is emitted later so the user knows that it
1139 applies to the other names as well.  The default is @samp{no-dup-args},
1140 which is less consistent, but prettier.
1141
1142 @item dup-args-note
1143 @item no-dup-args-note
1144 Enable or disable the note informing the user of suppressed option
1145 argument duplication.  The default is @samp{dup-args-note}.
1146
1147 @item short-opt-col=@var{n}
1148 Show the first short option in column @var{n} (default 2).
1149
1150 @item long-opt-col=@var{n}
1151 Show the first long option in column @var{n} (default 6).
1152
1153 @item doc-opt-col=@var{n}
1154 Show `documentation options' (@pxref{Argp Option Flags}) in column
1155 @var{n} (default 2).
1156
1157 @item opt-doc-col=@var{n}
1158 Show the documentation for options starting in column @var{n} (default 29).
1159
1160 @item header-col=@var{n}
1161 Indent group headers (which document groups of options) to column
1162 @var{n} (default 1).
1163
1164 @item usage-indent=@var{n}
1165 Indent continuation lines in @samp{Usage:} messages to column @var{n}
1166 (default 12).
1167
1168 @item rmargin=@var{n}
1169 Word wrap help output at or before column @var{n} (default 79).
1170 @end table