@ignore Documentation for the argp argument parser Copyright (C) 1995, 1996, 1997, 1998, 2000 Free Software Foundation, Inc. This file is part of the GNU C Library. Written by Miles Bader <miles@gnu.ai.mit.edu>. The GNU C Library is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. The GNU C Library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details. You should have received a copy of the GNU Library General Public License along with the GNU C Library; see the file COPYING.LIB. If not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ @end ignore @node Argp, Suboptions, Getopt, Parsing Program Arguments @need 5000 @section Parsing Program Options with Argp @cindex argp (program argument parser) @cindex argument parsing with argp @cindex option parsing with argp @dfn{Argp} is an interface for parsing unix-style argument vectors (@pxref{Program Arguments}). Unlike the more common @code{getopt} interface, it provides many related convenience features in addition to parsing options, such as automatically producing output in response to @samp{--help} and @samp{--version} options (as defined by the GNU coding standards). Doing these things in argp results in a more consistent look for programs that use it, and makes less likely that implementors will neglect to implement them or keep them up-to-date. Argp also provides the ability to merge several independently defined option parsers into one, mediating conflicts between them, and making the result appear seamless. A library can export an argp option parser, which programs can easily use in conjunction with their own option parser. This results in less work for user programs (indeed, some may use only argument parsers exported by libraries, and have no options of their own), and more consistent option-parsing for the abstractions implemented by the library. @pindex argp.h The header file @file{<argp.h>} should be included to use argp. @subsection The @code{argp_parse} Function The main interface to argp is the @code{argp_parse} function; often, a call to @code{argp_parse} is the only argument-parsing code needed in @code{main} (@pxref{Program Arguments}). @comment argp.h @comment GNU @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}) The @code{argp_parse} function parses the arguments in @var{argv}, of length @var{argc}, using the argp parser @var{argp} (@pxref{Argp Parsers}); a value of zero is the same as a @code{struct argp} containing all zeros. @var{flags} is a set of flag bits that modify the parsing behavior (@pxref{Argp Flags}). @var{input} is passed through to the argp parser @var{argp}, and has meaning defined by it; a typical usage is to pass a pointer to a structure which can be used for specifying parameters to the parser and passing back results from it. Unless the @code{ARGP_NO_EXIT} or @code{ARGP_NO_HELP} flags are included in @var{flags}, calling @code{argp_parse} may result in the program exiting---for instance when an unknown option is encountered. @xref{Program Termination}. If @var{arg_index} is non-null, the index of the first unparsed option in @var{argv} is returned in it. The return value is zero for successful parsing, or an error code (@pxref{Error Codes}) if an error was detected. Different argp parsers may return arbitrary error codes, but standard ones are @code{ENOMEM} if a memory allocation error occurred, or @code{EINVAL} if an unknown option or option argument was encountered. @end deftypefun @menu * Globals: Argp Global Variables. Global argp parameters. * Parsers: Argp Parsers. Defining parsers for use with @code{argp_parse}. * Flags: Argp Flags. Flags that modify the behavior of @code{argp_parse}. * Help: Argp Help. Printing help messages when not parsing. * Examples: Argp Examples. Simple examples of programs using argp. * Customization: Argp User Customization. Users may control the @samp{--help} output format. @end menu @node Argp Global Variables, Argp Parsers, , Argp @subsection Argp Global Variables These variables make it very easy for every user program to implement the @samp{--version} option and provide a bug-reporting address in the @samp{--help} output (which is implemented by argp regardless). @comment argp.h @comment GNU @deftypevar {const char *} argp_program_version If defined or set by the user program to a non-zero value, then a @samp{--version} option is added when parsing with @code{argp_parse} (unless the @code{ARGP_NO_HELP} flag is used), which will print this string followed by a newline and exit (unless the @code{ARGP_NO_EXIT} flag is used). @end deftypevar @comment argp.h @comment GNU @deftypevar {const char *} argp_program_bug_address If defined or set by the user program to a non-zero value, @code{argp_program_bug_address} should point to a string that is the bug-reporting address for the program. It will be printed at the end of the standard output for the @samp{--help} option, embedded in a sentence that says something like @samp{Report bugs to @var{address}.}. @end deftypevar @need 1500 @comment argp.h @comment GNU @defvar argp_program_version_hook If defined or set by the user program to a non-zero value, then a @samp{--version} option is added when parsing with @code{argp_parse} (unless the @code{ARGP_NO_HELP} flag is used), which calls this function to print the version, and then exits with a status of 0 (unless the @code{ARGP_NO_EXIT} flag is used). It should point to a function with the following type signature: @smallexample void @var{print-version} (FILE *@var{stream}, struct argp_state *@var{state}) @end smallexample @noindent @xref{Argp Parsing State}, for an explanation of @var{state}. This variable takes precedent over @code{argp_program_version}, and is useful if a program has version information that cannot be easily specified as a simple string. @end defvar @comment argp.h @comment GNU @deftypevar error_t argp_err_exit_status The exit status that argp will use when exiting due to a parsing error. If not defined or set by the user program, this defaults to @code{EX_USAGE} from @file{<sysexits.h>}. @end deftypevar @node Argp Parsers, Argp Flags, Argp Global Variables, Argp @subsection Specifying Argp Parsers The first argument to the @code{argp_parse} function is a pointer to a @code{struct argp}, which known as an @dfn{argp parser}: @comment argp.h @comment GNU @deftp {Data Type} {struct argp} This structure specifies how to parse a given set of options and arguments, perhaps in conjunction with other argp parsers. It has the following fields: @table @code @item const struct argp_option *options A pointer to a vector of @code{argp_option} structures specifying which options this argp parser understands; it may be zero if there are no options at all. @xref{Argp Option Vectors}. @item argp_parser_t parser A pointer to a function that defines actions for this parser; it is called for each option parsed, and at other well-defined points in the parsing process. A value of zero is the same as a pointer to a function that always returns @code{ARGP_ERR_UNKNOWN}. @xref{Argp Parser Functions}. @item const char *args_doc If non-zero, a string describing what non-option arguments are wanted by this parser; it is only used to print the @samp{Usage:} message. If it contains newlines, the strings separated by them are considered alternative usage patterns, and printed on separate lines (lines after the first are prefixed by @samp{ or: } instead of @samp{Usage:}). @item const char *doc If non-zero, a string containing extra text to be printed before and after the options in a long help message, with the two sections separated by a vertical tab (@code{'\v'}, @code{'\013'}) character. By convention, the documentation before the options is just a short string saying what the program does, and that afterwards is longer, describing the behavior in more detail. @item const struct argp_child *children A pointer to a vector of @code{argp_children} structures specifying additional argp parsers that should be combined with this one. @xref{Argp Children}. @item char *(*help_filter)(int @var{key}, const char *@var{text}, void *@var{input}) If non-zero, a pointer to a function to filter the output of help messages. @xref{Argp Help Filtering}. @end table @end deftp The @code{options}, @code{parser}, @code{args_doc}, and @code{doc} fields are usually all that are needed. If an argp parser is defined as an initialized C variable, only the used fields need be specified in the initializer---the rest will default to zero due to the way C structure initialization works (this fact is exploited for most argp structures, grouping the most-used fields near the beginning, so that unused fields can simply be left unspecified). @menu * Options: Argp Option Vectors. Specifying options in an argp parser. * Argp Parser Functions:: Defining actions for an argp parser. * Children: Argp Children. Combining multiple argp parsers. * Help Filtering: Argp Help Filtering. Customizing help output for an argp parser. @end menu @node Argp Option Vectors, Argp Parser Functions, Argp Parsers, Argp Parsers @subsection Specifying Options in an Argp Parser The @code{options} field in a @code{struct argp} points to a vector of @code{struct argp_option} structures, each of which specifies an option that argp parser supports (actually, sometimes multiple entries may used for a single option if it has many names). It should be terminated by an entry with zero in all fields (note that when using an initialized C array for options, writing @code{@{ 0 @}} is enough to achieve this). @comment argp.h @comment GNU @deftp {Data Type} {struct argp_option} This structure specifies a single option that an argp parser understands, and how to parse and document it. It has the following fields: @table @code @item const char *name The long name for this option, corresponding to the long option @samp{--@var{name}}; this field can be zero if this option only has a short name. To specify multiple names for an option, additional entries may follow this one, with the @code{OPTION_ALIAS} flag set (@pxref{Argp Option Flags}). @item int key The integer key that is provided to the argp parser's parsing function when this option is being parsed. Also, if @var{key} has a value that is a printable @sc{ascii} character (i.e., @code{isascii (@var{key})} is true), it @emph{also} specifies a short option @samp{-@var{char}}, where @var{char} is the @sc{ascii} character with the code @var{key}. @item const char *arg If non-zero, this is the name of an argument associated with this option, which must be provided (e.g., with the @samp{--@var{name}=@var{value}} or @samp{-@var{char} @var{value}} syntaxes) unless the @code{OPTION_ARG_OPTIONAL} flag (@pxref{Argp Option Flags}) is set, in which case it @emph{may} be provided. @item int flags Flags associated with this option (some of which are referred to above). @xref{Argp Option Flags}. @item const char *doc A documentation string for this option, for printing in help messages. If both the @code{name} and @code{key} fields are zero, this string will be printed out-dented from the normal option column, making it useful as a group header (it will be the first thing printed in its group); in this usage, it's conventional to end the string with a @samp{:} character. @item int group The group this option is in. In a long help message, options are sorted alphabetically within each group, and the groups presented in the order 0, 1, 2, @dots{}, @var{n}, @minus{}@var{m}, @dots{}, @minus{}2, @minus{}1. Every entry in an options array with this field 0 will inherit the group number of the previous entry, or zero if it's the first one, unless its a group header (@code{name} and @code{key} fields both zero), in which case, the previous entry + 1 is the default. Automagic options such as @samp{--help} are put into group @minus{}1. Note that because of C structure initialization rules, this field often need not be specified, because 0 is the right value. @end table @end deftp @menu * Flags: Argp Option Flags. Flags for options. @end menu @node Argp Option Flags, , , Argp Option Vectors @subsubsection Flags for Argp Options The following flags may be or'd together in the @code{flags} field of a @code{struct argp_option}, and control various aspects of how that option is parsed or displayed in help messages: @vtable @code @comment argp.h @comment GNU @item OPTION_ARG_OPTIONAL The argument associated with this option is optional. @comment argp.h @comment GNU @item OPTION_HIDDEN This option isn't displayed in any help messages. @comment argp.h @comment GNU @item OPTION_ALIAS This option is an alias for the closest previous non-alias option. This means that it will be displayed in the same help entry, and will inherit fields other than @code{name} and @code{key} from the aliased option. @comment argp.h @comment GNU @item OPTION_DOC This option isn't actually an option (and so should be ignored by the actual option parser), but rather an arbitrary piece of documentation that should be displayed in much the same manner as the options (known as a @dfn{documentation option}). If this flag is set, then the option @code{name} field is displayed unmodified (e.g., no @samp{--} prefix is added) at the left-margin (where a @emph{short} option would normally be displayed), and the documentation string in the normal place. For purposes of sorting, any leading whitespace and punctuation is ignored, except that if the first non-whitespace character is not @samp{-}, this entry is displayed after all options (and @code{OPTION_DOC} entries with a leading @samp{-}) in the same group. @comment argp.h @comment GNU @item OPTION_NO_USAGE This option shouldn't be included in `long' usage messages (but is still included in help messages). This is mainly intended for options that are completely documented in an argp's @code{args_doc} field (@pxref{Argp Parsers}), in which case including the option in the generic usage list would be redundant. For instance, if @code{args_doc} is @code{"FOO BAR\n-x BLAH"}, and the @samp{-x} option's purpose is to distinguish these two cases, @samp{-x} should probably be marked @code{OPTION_NO_USAGE}. @end vtable @node Argp Parser Functions, Argp Children, Argp Option Vectors, Argp Parsers @subsection Argp Parser Functions The function pointed to by the @code{parser} field in a @code{struct argp} (@pxref{Argp Parsers}) defines what actions take place in response to each option or argument that is parsed, and is also used as a hook, to allow a parser to do something at certain other points during parsing. @need 2000 Argp parser functions have the following type signature: @cindex argp parser functions @smallexample error_t @var{parser} (int @var{key}, char *@var{arg}, struct argp_state *@var{state}) @end smallexample @noindent where the arguments are as follows: @table @var @item key For each option that is parsed, @var{parser} is called with a value of @var{key} from that option's @code{key} field in the option vector (@pxref{Argp Option Vectors}). @var{parser} is also called at other times with special reserved keys, such as @code{ARGP_KEY_ARG} for non-option arguments. @xref{Argp Special Keys}. @item arg If @var{key} is an option, @var{arg} is the value given for it, or zero if no value was specified. Only options that have a non-zero @code{arg} field can ever have a value, and those must @emph{always} have a value, unless the @code{OPTION_ARG_OPTIONAL} flag was specified (if the input being parsed specifies a value for an option that doesn't allow one, an error results before @var{parser} ever gets called). If @var{key} is @code{ARGP_KEY_ARG}, @var{arg} is a non-option argument; other special keys always have a zero @var{arg}. @item state @var{state} points to a @code{struct argp_state}, containing useful information about the current parsing state for use by @var{parser}. @xref{Argp Parsing State}. @end table When @var{parser} is called, it should perform whatever action is appropriate for @var{key}, and return either @code{0} for success, @code{ARGP_ERR_UNKNOWN}, if the value of @var{key} is not handled by this parser function, or a unix error code if a real error occurred (@pxref{Error Codes}). @comment argp.h @comment GNU @deftypevr Macro int ARGP_ERR_UNKNOWN Argp parser functions should return @code{ARGP_ERR_UNKNOWN} for any @var{key} value they do not recognize, or for non-option arguments (@code{@var{key} == ARGP_KEY_ARG}) that they do not wish to handle. @end deftypevr @need 3000 A typical parser function uses a switch statement on @var{key}: @smallexample error_t parse_opt (int key, char *arg, struct argp_state *state) @{ switch (key) @{ case @var{option_key}: @var{action} break; @dots{} default: return ARGP_ERR_UNKNOWN; @} return 0; @} @end smallexample @menu * Keys: Argp Special Keys. Special values for the @var{key} argument. * State: Argp Parsing State. What the @var{state} argument refers to. * Functions: Argp Helper Functions. Functions to help during argp parsing. @end menu @node Argp Special Keys, Argp Parsing State, , Argp Parser Functions @subsubsection Special Keys for Argp Parser Functions In addition to key values corresponding to user options, the @var{key} argument to argp parser functions may have a number of other special values (@var{arg} and @var{state} refer to parser function arguments; @pxref{Argp Parser Functions}): @vtable @code @comment argp.h @comment GNU @item ARGP_KEY_ARG This is not an option at all, but rather a command line argument, whose value is pointed to by @var{arg}. When there are multiple parser functions (due to argp parsers being combined), it's impossible to know which one wants to handle an argument, so each is called in turn, until one returns 0 or an error other than @code{ARGP_ERR_UNKNOWN}; if an argument is handled by no one, @code{argp_parse} immediately returns success, without parsing any more arguments. Once a parser function returns success for this key, that fact is recorded, and the @code{ARGP_KEY_NO_ARGS} case won't be used. @emph{However}, if while processing the argument, a parser function decrements the @code{next} field of its @var{state} argument, the option won't be considered processed; this is to allow you to actually modify the argument (perhaps into an option), and have it processed again. @comment argp.h @comment GNU @item ARGP_KEY_ARGS If a parser function returns @code{ARGP_ERR_UNKNOWN} for @code{ARGP_KEY_ARG}, it is immediately called again with the key @code{ARGP_KEY_ARGS}, which has a similar meaning, but is slightly more convenient for consuming all remaining arguments. @var{arg} is 0, and the tail of the argument vector may be found at @code{@var{state}->argv + @var{state}->next}. If success is returned for this key, and @code{@var{state}->next} is unchanged, then all remaining arguments are considered to have been consumed, otherwise, the amount by which @code{@var{state}->next} has been adjust indicates how many were used. For instance, here's an example that uses both, for different args: @smallexample ... case ARGP_KEY_ARG: if (@var{state}->arg_num == 0) /* First argument */ first_arg = @var{arg}; else /* Let the next case parse it. */ return ARGP_KEY_UNKNOWN; break; case ARGP_KEY_ARGS: remaining_args = @var{state}->argv + @var{state}->next; num_remaining_args = @var{state}->argc - @var{state}->next; break; @end smallexample @comment argp.h @comment GNU @item ARGP_KEY_END There are no more command line arguments at all. The parser functions are called in different order (means children first) for this value which allows each parser to clean up its state for the parent. @comment argp.h @comment GNU @item ARGP_KEY_NO_ARGS Because it's common to want to do some special processing if there aren't any non-option args, parser functions are called with this key if they didn't successfully process any non-option arguments. Called just before @code{ARGP_KEY_END} (where more general validity checks on previously parsed arguments can take place). @comment argp.h @comment GNU @item ARGP_KEY_INIT Passed in before any parsing is done. Afterwards, the values of each element of the @code{child_input} field of @var{state}, if any, are copied to each child's state to be the initial value of the @code{input} when @emph{their} parsers are called. @comment argp.h @comment GNU @item ARGP_KEY_SUCCESS Passed in when parsing has successfully been completed (even if there are still arguments remaining). @comment argp.h @comment GNU @item ARGP_KEY_ERROR Passed in if an error has occurred, and parsing terminated (in which case a call with a key of @code{ARGP_KEY_SUCCESS} is never made). @comment argp.h @comment GNU @item ARGP_KEY_FINI The final key ever seen by any parser (even after @code{ARGP_KEY_SUCCESS} and @code{ARGP_KEY_ERROR}). Any resources allocated by @code{ARGP_KEY_INIT} may be freed here (although sometimes certain resources allocated there are to be returned to the caller after a successful parse; in that case, those particular resources can be freed in the @code{ARGP_KEY_ERROR} case). @end vtable In all cases, @code{ARGP_KEY_INIT} is the first key seen by parser functions, and @code{ARGP_KEY_FINI} the last (unless an error was returned by the parser for @code{ARGP_KEY_INIT}). Other keys can occur in one the following orders (@var{opt} refers to an arbitrary option key): @table @asis @item @var{opt}@dots{} @code{ARGP_KEY_NO_ARGS} @code{ARGP_KEY_END} @code{ARGP_KEY_SUCCESS} The arguments being parsed contained no non-option arguments at all. @item ( @var{opt} | @code{ARGP_KEY_ARG} )@dots{} @code{ARGP_KEY_END} @code{ARGP_KEY_SUCCESS} All non-option arguments were successfully handled by a parser function (there may be multiple parser functions if multiple argp parsers were combined). @item ( @var{opt} | @code{ARGP_KEY_ARG} )@dots{} @code{ARGP_KEY_SUCCESS} Some non-option argument was unrecognized. This occurs when every parser function returns @code{ARGP_KEY_UNKNOWN} for an argument, in which case parsing stops at that argument. If @var{arg_index} is a null pointer otherwise an error occurs. @end table In all cases, if a non-null value for @var{arg_index} was passed to @code{argp_parse}, the index of the first unparsed command-line argument is passed back in it. If an error occurs (either detected by argp, or because a parser function returned an error value), then each parser is called with @code{ARGP_KEY_ERROR}, and no further calls are made except the final call with @code{ARGP_KEY_FINI}. @node Argp Helper Functions, , Argp Parsing State, Argp Parser Functions @subsubsection Functions For Use in Argp Parsers Argp provides a number of functions for the user of argp parser functions (@pxref{Argp Parser Functions}), mostly for producing error messages. These take as their first argument the @var{state} argument to the parser function (@pxref{Argp Parsing State}). @cindex usage messages, in argp @comment argp.h @comment GNU @deftypefun void argp_usage (const struct argp_state *@var{state}) Output the standard usage message for the argp parser referred to by @var{state} to @code{@var{state}->err_stream} and terminate the program with @code{exit (argp_err_exit_status)} (@pxref{Argp Global Variables}). @end deftypefun @cindex syntax error messages, in argp @comment argp.h @comment GNU @deftypefun void argp_error (const struct argp_state *@var{state}, const char *@var{fmt}, @dots{}) Print the printf format string @var{fmt} and following args, preceded by the program name and @samp{:}, and followed by a @w{@samp{Try @dots{} --help}} message, and terminate the program with an exit status of @code{argp_err_exit_status} (@pxref{Argp Global Variables}). @end deftypefun @cindex error messages, in argp @comment argp.h @comment GNU @deftypefun void argp_failure (const struct argp_state *@var{state}, int @var{status}, int @var{errnum}, const char *@var{fmt}, @dots{}) Similarly to the standard gnu error-reporting function @code{error}, print the printf format string @var{fmt} and following args, preceded by the program name and @samp{:}, and followed by the standard unix error text for @var{errnum} if it is non-zero; then if @var{status} is non-zero, terminate the program with that as its exit status. The difference between this function and @code{argp_error} is that @code{argp_error} is for @emph{parsing errors}, whereas @code{argp_failure} is for other problems that occur during parsing but don't reflect a syntactic problem with the input---such as illegal values for options, bad phase of the moon, etc. @end deftypefun @comment argp.h @comment GNU @deftypefun void argp_state_help (const struct argp_state *@var{state}, FILE *@var{stream}, unsigned @var{flags}) Output a help message for the argp parser referred to by @var{state} to @var{stream}. The @var{flags} argument determines what sort of help message is produced. @xref{Argp Help Flags}. @end deftypefun Error output is sent to @code{@var{state}->err_stream}, and the program name printed is @code{@var{state}->name}. The output or program termination behavior of these functions may be suppressed if the @code{ARGP_NO_EXIT} or @code{ARGP_NO_ERRS} flags, respectively, were passed to @code{argp_parse}. @xref{Argp Flags}. This behavior is useful if an argp parser is exported for use by other programs (e.g., by a library), and may be used in a context where it is not desirable to terminate the program in response to parsing errors. In argp parsers intended for such general use, calls to any of these functions should be followed by code return of an appropriate error code for the case where the program @emph{doesn't} terminate; for example: @smallexample if (@var{bad argument syntax}) @{ argp_usage (@var{state}); return EINVAL; @} @end smallexample @noindent If it's known that a parser function will only be used when @code{ARGP_NO_EXIT} is not set, the return may be omitted. @node Argp Parsing State, Argp Helper Functions, Argp Special Keys, Argp Parser Functions @subsubsection Argp Parsing State The third argument to argp parser functions (@pxref{Argp Parser Functions}) is a pointer to a @code{struct argp_state}, which contains information about the state of the option parsing. @comment argp.h @comment GNU @deftp {Data Type} {struct argp_state} This structure has the following fields, which may be modified as noted: @table @code @item const struct argp *const root_argp The top level argp parser being parsed. Note that this is often @emph{not} the same @code{struct argp} passed into @code{argp_parse} by the invoking program (@pxref{Argp}), but instead an internal argp parser that contains options implemented by @code{argp_parse} itself (such as @samp{--help}). @item int argc @itemx char **argv The argument vector being parsed. May be modified. @item int next The index in @code{argv} of the next argument to be parsed. May be modified. One way to consume all remaining arguments in the input is to set @code{@var{state}->next = @var{state}->argc} (perhaps after recording the value of the @code{next} field to find the consumed arguments). Also, you can cause the current option to be re-parsed by decrementing this field, and then modifying @code{@var{state}->argv[@var{state}->next]} to be the option that should be reexamined. @item unsigned flags The flags supplied to @code{argp_parse}. May be modified, although some flags may only take effect when @code{argp_parse} is first invoked. @xref{Argp Flags}. @item unsigned arg_num While calling a parsing function with the @var{key} argument @code{ARGP_KEY_ARG}, this is the number of the current arg, starting at 0, and incremented after each such call returns. At all other times, this is the number of such arguments that have been processed. @item int quoted If non-zero, the index in @code{argv} of the first argument following a special @samp{--} argument (which prevents anything following being interpreted as an option). Only set once argument parsing has proceeded past this point. @item void *input An arbitrary pointer passed in from the caller of @code{argp_parse}, in the @var{input} argument. @item void **child_inputs Values to pass to child parsers. This vector will be the same length as the number of children in the current parser, and each child parser will be given the value of @code{@var{state}->child_inputs[@var{i}]} as @emph{its} @code{@var{state}->input} field, where @var{i} is the index of the child in the this parser's @code{children} field. @xref{Argp Children}. @item void *hook For the parser function's use. Initialized to 0, but otherwise ignored by argp. @item char *name The name used when printing messages. This is initialized to @code{argv[0]}, or @code{program_invocation_name} if that is unavailable. @item FILE *err_stream @itemx FILE *out_stream Stdio streams used when argp prints something; error messages are printed to @code{err_stream}, and all other output (such as @samp{--help} output) to @code{out_stream}. These are initialized to @code{stderr} and @code{stdout} respectively (@pxref{Standard Streams}). @item void *pstate Private, for use by the argp implementation. @end table @end deftp @node Argp Children, Argp Help Filtering, Argp Parser Functions, Argp Parsers @subsection Combining Multiple Argp Parsers The @code{children} field in a @code{struct argp} allows other argp parsers to be combined with the referencing one to parse a single set of arguments. It should point to a vector of @code{struct argp_child}, terminated by an entry having a value of zero in the @code{argp} field. Where conflicts between combined parsers arise (for instance, if two specify an option with the same name), they are resolved in favor of the parent argp parsers, or earlier argp parsers in the list of children. @comment argp.h @comment GNU @deftp {Data Type} {struct argp_child} An entry in the list of subsidiary argp parsers pointed to by the @code{children} field in a @code{struct argp}. The fields are as follows: @table @code @item const struct argp *argp The child argp parser, or zero to end the list. @item int flags Flags for this child. @item const char *header If non-zero, an optional header to be printed in help output before the child options. As a side-effect, a non-zero value forces the child options to be grouped together; to achieve this effect without actually printing a header string, use a value of @code{""}. As with header strings specified in an option entry, the value conventionally has @samp{:} as the last character. @xref{Argp Option Vectors}. @item int group Where to group the child options relative to the other (`consolidated') options in the parent argp parser. The values are the same as the @code{group} field in @code{struct argp_option} (@pxref{Argp Option Vectors}), but all child-groupings follow parent options at a particular group level. If both this field and @code{header} are zero, then the child's options aren't grouped together at all, but rather merged with the parent options (merging the child's grouping levels with the parents). @end table @end deftp @node Argp Flags, Argp Help, Argp Parsers, Argp @subsection Flags for @code{argp_parse} The default behavior of @code{argp_parse} is designed to be convenient for the most common case of parsing program command line argument. To modify these defaults, the following flags may be or'd together in the @var{flags} argument to @code{argp_parse}: @vtable @code @comment argp.h @comment GNU @item ARGP_PARSE_ARGV0 Don't ignore the first element of the @var{argv} argument to @code{argp_parse}. Normally (and always unless @code{ARGP_NO_ERRS} is set) the first element of the argument vector is skipped for option parsing purposes, as it corresponds to the program name in a command line. @comment argp.h @comment GNU @item ARGP_NO_ERRS Don't print error messages for unknown options to @code{stderr}; unless this flag is set, @code{ARGP_PARSE_ARGV0} is ignored, as @code{argv[0]} is used as the program name in the error messages. This flag implies @code{ARGP_NO_EXIT} (on the assumption that silent exiting upon errors is bad behaviour). @comment argp.h @comment GNU @item ARGP_NO_ARGS Don't parse any non-option args. Normally non-option args are parsed by calling the parse functions with a key of @code{ARGP_KEY_ARG}, and the actual arg as the value. This flag needn't normally be set, as the normal behavior is to stop parsing as soon as some argument isn't accepted by a parsing function. @xref{Argp Parser Functions}. @comment argp.h @comment GNU @item ARGP_IN_ORDER Parse options and arguments in the same order they occur on the command line---normally they're rearranged so that all options come first @comment argp.h @comment GNU @item ARGP_NO_HELP Don't provide the standard long option @samp{--help}, which ordinarily causes usage and option help information to be output to @code{stdout}, and @code{exit (0)} called. @comment argp.h @comment GNU @item ARGP_NO_EXIT Don't exit on errors (they may still result in error messages). @comment argp.h @comment GNU @item ARGP_LONG_ONLY Use the gnu getopt `long-only' rules for parsing arguments. This allows long-options to be recognized with only a single @samp{-} (for instances, @samp{-help}), but results in a generally somewhat less useful interface, that conflicts with the way most GNU programs work. For this reason, its use is discouraged. @comment argp.h @comment GNU @item ARGP_SILENT Turns off any message-printing/exiting options, specifically @code{ARGP_NO_EXIT}, @code{ARGP_NO_ERRS}, and @code{ARGP_NO_HELP}. @end vtable @node Argp Help Filtering, , Argp Children, Argp Parsers @need 2000 @subsection Customizing Argp Help Output The @code{help_filter} field in a @code{struct argp} is a pointer to a function to filter the text of help messages before displaying them. They have a function signature like: @smallexample char *@var{help-filter} (int @var{key}, const char *@var{text}, void *@var{input}) @end smallexample @noindent where @var{key} is either a key from an option, in which case @var{text} is that option's help text (@pxref{Argp Option Vectors}), or one of the special keys with names beginning with @samp{ARGP_KEY_HELP_}, describing which other help text @var{text} is (@pxref{Argp Help Filter Keys}). The function should return either @var{text}, if it should be used as-is, a replacement string, which should be allocated using @code{malloc}, and will be freed by argp, or zero, meaning `print nothing'. The value of @var{text} supplied is @emph{after} any translation has been done, so if any of the replacement text also needs translation, that should be done by the filter function. @var{input} is either the input supplied to @code{argp_parse}, or zero, if @code{argp_help} was called directly by the user. @menu * Keys: Argp Help Filter Keys. Special @var{key} values for help filter functions. @end menu @node Argp Help Filter Keys, , , Argp Help Filtering @subsubsection Special Keys for Argp Help Filter Functions The following special values may be passed to an argp help filter function as the first argument, in addition to key values for user options, and specify which help text the @var{text} argument contains: @vtable @code @comment argp.h @comment GNU @item ARGP_KEY_HELP_PRE_DOC Help text preceding options. @comment argp.h @comment GNU @item ARGP_KEY_HELP_POST_DOC Help text following options. @comment argp.h @comment GNU @item ARGP_KEY_HELP_HEADER Option header string. @comment argp.h @comment GNU @item ARGP_KEY_HELP_EXTRA After all other documentation; @var{text} is zero for this key. @comment argp.h @comment GNU @item ARGP_KEY_HELP_DUP_ARGS_NOTE The explanatory note emitted when duplicate option arguments have been suppressed. @comment argp.h @comment GNU @item ARGP_KEY_HELP_ARGS_DOC The argument doc string (the @code{args_doc} field from the argp parser; @pxref{Argp Parsers}). @end vtable @node Argp Help, Argp Examples, Argp Flags, Argp @subsection The @code{argp_help} Function Normally programs using argp need not worry too much about printing argument-usage-type help messages, because the standard @samp{--help} option is handled automatically by argp, and the typical error cases can be handled using @code{argp_usage} and @code{argp_error} (@pxref{Argp Helper Functions}). However, if it's desirable to print a standard help message in some context other than parsing the program options, argp offers the @code{argp_help} interface. @comment argp.h @comment GNU @deftypefun void argp_help (const struct argp *@var{argp}, FILE *@var{stream}, unsigned @var{flags}, char *@var{name}) Output a help message for the argp parser @var{argp} to @var{stream}. What sort of messages is printed is determined by @var{flags}. Any options such as @samp{--help} that are implemented automatically by argp itself will @emph{not} be present in the help output; for this reason, it is better to use @code{argp_state_help} if calling from within an argp parser function. @xref{Argp Helper Functions}. @end deftypefun @menu * Flags: Argp Help Flags. Specifying what sort of help message to print. @end menu @node Argp Help Flags, , , Argp Help @subsection Flags for the @code{argp_help} Function When calling @code{argp_help} (@pxref{Argp Help}), or @code{argp_state_help} (@pxref{Argp Helper Functions}), exactly what is output is determined by the @var{flags} argument, which should consist of any of the following flags, or'd together: @vtable @code @item ARGP_HELP_USAGE A unix @samp{Usage:} message that explicitly lists all options. @item ARGP_HELP_SHORT_USAGE A unix @samp{Usage:} message that displays only an appropriate placeholder to indicate where the options go; useful for showing the non-option argument syntax. @item ARGP_HELP_SEE A @samp{Try @dots{} for more help} message; @samp{@dots{}} contains the program name and @samp{--help}. @item ARGP_HELP_LONG A verbose option help message that gives each option understood along with its documentation string. @item ARGP_HELP_PRE_DOC The part of the argp parser doc string that precedes the verbose option help. @item ARGP_HELP_POST_DOC The part of the argp parser doc string that follows the verbose option help. @item ARGP_HELP_DOC @code{(ARGP_HELP_PRE_DOC | ARGP_HELP_POST_DOC)} @item ARGP_HELP_BUG_ADDR A message saying where to report bugs for this program, if the @code{argp_program_bug_address} variable contains one. @item ARGP_HELP_LONG_ONLY Modify any output appropriately to reflect @code{ARGP_LONG_ONLY} mode. @end vtable The following flags are only understood when used with @code{argp_state_help}, and control whether the function returns after printing its output, or terminates the program: @vtable @code @item ARGP_HELP_EXIT_ERR Terminate the program with @code{exit (argp_err_exit_status)}. @item ARGP_HELP_EXIT_OK Terminate the program with @code{exit (0)}. @end vtable The following flags are combinations of the basic ones for printing standard messages: @vtable @code @item ARGP_HELP_STD_ERR Assuming an error message for a parsing error has already printed, prints a note on how to get help, and terminates the program with an error. @item ARGP_HELP_STD_USAGE Prints a standard usage message and terminates the program with an error. This is used when no more specific error message is appropriate. @item ARGP_HELP_STD_HELP Prints the standard response for a @samp{--help} option, and terminates the program successfully. @end vtable @node Argp Examples, Argp User Customization, Argp Help, Argp @subsection Argp Examples These example programs demonstrate the basic usage of argp. @menu * 1: Argp Example 1. A minimal program using argp. * 2: Argp Example 2. A program using only default options. * 3: Argp Example 3. A simple program with user options. * 4: Argp Example 4. Combining multiple argp parsers. @end menu @node Argp Example 1, Argp Example 2, , Argp Examples @subsubsection A Minimal Program Using Argp This is (probably) the smallest possible program that uses argp. It won't do much except give an error messages and exit when there are any arguments, and print a (rather pointless) message for @samp{--help}. @smallexample @include argp-ex1.c.texi @end smallexample @node Argp Example 2, Argp Example 3, Argp Example 1, Argp Examples @subsubsection A Program Using Argp with Only Default Options This program doesn't use any options or arguments, but uses argp to be compliant with the GNU standard command line format. In addition to making sure no arguments are given, and implementing a @samp{--help} option, this example will have a @samp{--version} option, and will put the given documentation string and bug address in the @samp{--help} output, as per GNU standards. The variable @code{argp} contains the argument parser specification; adding fields to this structure is the way most parameters are passed to @code{argp_parse} (the first three fields are usually used, but not in this small program). There are also two global variables that argp knows about defined here, @code{argp_program_version} and @code{argp_program_bug_address} (they are global variables because they will almost always be constant for a given program, even if it uses different argument parsers for various tasks). @smallexample @include argp-ex2.c.texi @end smallexample @node Argp Example 3, Argp Example 4, Argp Example 2, Argp Examples @subsubsection A Program Using Argp with User Options This program uses the same features as example 2, and adds user options and arguments. We now use the first four fields in @code{argp} (@pxref{Argp Parsers}), and specifies @code{parse_opt} as the parser function (@pxref{Argp Parser Functions}). Note that in this example, @code{main} uses a structure to communicate with the @code{parse_opt} function, a pointer to which it passes in the @code{input} argument to @code{argp_parse} (@pxref{Argp}), and is retrieved by @code{parse_opt} through the @code{input} field in its @code{state} argument (@pxref{Argp Parsing State}). Of course, it's also possible to use global variables instead, but using a structure like this is somewhat more flexible and clean. @smallexample @include argp-ex3.c.texi @end smallexample @node Argp Example 4, , Argp Example 3, Argp Examples @subsubsection A Program Using Multiple Combined Argp Parsers This program uses the same features as example 3, but has more options, and somewhat more structure in the @samp{--help} output. It also shows how you can `steal' the remainder of the input arguments past a certain point, for programs that accept a list of items, and the special @var{key} value @code{ARGP_KEY_NO_ARGS}, which is only given if no non-option arguments were supplied to the program (@pxref{Argp Special Keys}). For structuring the help output, two features are used: @emph{headers}, which are entries in the options vector (@pxref{Argp Option Vectors}) with the first four fields being zero, and a two part documentation string (in the variable @code{doc}), which allows documentation both before and after the options (@pxref{Argp Parsers}); the two parts of @code{doc} are separated by a vertical-tab character (@code{'\v'}, or @code{'\013'}). By convention, the documentation before the options is just a short string saying what the program does, and that afterwards is longer, describing the behavior in more detail. All documentation strings are automatically filled for output, although newlines may be included to force a line break at a particular point. All documentation strings are also passed to the @code{gettext} function, for possible translation into the current locale. @smallexample @include argp-ex4.c.texi @end smallexample @node Argp User Customization, , Argp Examples, Argp @subsection Argp User Customization @cindex ARGP_HELP_FMT environment variable The way formatting of argp @samp{--help} output may be controlled to some extent by a program's users, by setting the @code{ARGP_HELP_FMT} environment variable to a comma-separated list (whitespace is ignored) of the following tokens: @table @samp @item dup-args @itemx no-dup-args Turn @dfn{duplicate-argument-mode} on or off. In duplicate argument mode, if an option which accepts an argument has multiple names, the argument is shown for each name; otherwise, it is only shown for the first long option, and a note is emitted later so the user knows that it applies to the other names as well. The default is @samp{no-dup-args}, which is less consistent, but prettier. @item dup-args-note @item no-dup-args-note Enable or disable the note informing the user of suppressed option argument duplication. The default is @samp{dup-args-note}. @item short-opt-col=@var{n} Show the first short option in column @var{n} (default 2). @item long-opt-col=@var{n} Show the first long option in column @var{n} (default 6). @item doc-opt-col=@var{n} Show `documentation options' (@pxref{Argp Option Flags}) in column @var{n} (default 2). @item opt-doc-col=@var{n} Show the documentation for options starting in column @var{n} (default 29). @item header-col=@var{n} Indent group headers (which document groups of options) to column @var{n} (default 1). @item usage-indent=@var{n} Indent continuation lines in @samp{Usage:} messages to column @var{n} (default 12). @item rmargin=@var{n} Word wrap help output at or before column @var{n} (default 79). @end table