diff options
Diffstat (limited to 'support/argp.texi')
| -rw-r--r-- | support/argp.texi | 1157 |
1 files changed, 0 insertions, 1157 deletions
diff --git a/support/argp.texi b/support/argp.texi deleted file mode 100644 index 8c41f07..0000000 --- a/support/argp.texi +++ /dev/null @@ -1,1157 +0,0 @@ -@ignore - Documentation for the argp argument parser - - Copyright (C) 1995, 1996, 1997 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}, @w{int @var{argc}, char **@var{argv}}, @w{unsigned @var{flags}}, @w{int *@var{arg_index}}, @w{void *@var{input}}) -The @code{argp_parse} function parses the arguments in 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}. - -The return value is zero for successful parsing, or a unix 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 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 prefix 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 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 which 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 - return ARGP_KEY_UNKNOWN; /* Let the next case parse it. */ - 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. - -@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 a -non-zero value for @var{arg_index} was passed to @code{argp_parse}, the -index of this argument is returned in it, otherwise an error occurs. -@end table - -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}, @w{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}, @w{int @var{status}, int @var{errnum},} @w{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}, @w{FILE *@var{stream}}, @w{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 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}, @w{FILE *@var{stream}}, @w{unsigned @var{flags}}, @w{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 -@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 -@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 -@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 -@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 |