Parsing Program Options with Argp
=================================

Argp is an interface for parsing unix-style argument vectors (see Program Arguments).

Unlike the more common getopt interface, it provides many related convenience features in addition to parsing options, such as automatically producing output in response to --help and --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.

The header file <argp.h> should be included to use argp.

The argp_parse Function
-----------------------

The main interface to argp is the argp_parse function; often, a call to argp_parse is the only argument-parsing code needed in main (see Program Arguments).

 -- Function: error_t argp_parse (const struct argp *ARGP, int ARGC, char **ARGV, unsigned FLAGS, int *ARG_INDEX, void *INPUT)
     The argp_parse function parses the arguments in ARGV, of length ARGC, using the argp parser ARGP (see Argp Parsers); a value of zero is the same as a struct argp containing all zeros.  FLAGS is a set of flag bits that modify the parsing behavior (see Argp Flags).  INPUT is passed through to the argp parser 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 ARGP_NO_EXIT or ARGP_NO_HELP flags are included in FLAGS, calling argp_parse may result in the program exiting---for instance when an unknown option is encountered. See Program Termination.

     The return value is zero for successful parsing, or a unix error code (see Error Codes) if an error was detected.  Different argp parsers may return arbitrary error codes, but standard ones are ENOMEM if a memory allocation error occurred, or EINVAL if an unknown option or option argument was encountered.

Argp Global Variables
---------------------

These variables make it very easy for every user program to implement the --version option and provide a bug-reporting address in the --help output (which is implemented by argp regardless).

 -- Variable: const char * argp_program_version
     If defined or set by the user program to a non-zero value, then a --version option is added when parsing with argp_parse (unless the ARGP_NO_HELP flag is used), which will print this string followed by a newline and exit (unless the ARGP_NO_EXIT flag is used).

 -- Variable: const char * argp_program_bug_address
     If defined or set by the user program to a non-zero value, 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 --help option, embedded in a sentence that says something like Report bugs to ADDRESS..

 -- Variable: argp_program_version_hook
     If defined or set by the user program to a non-zero value, then a --version option is added when parsing with argp_parse (unless the ARGP_NO_HELP flag is used), which calls this function to print the version, and then exits with a status of 0 (unless the ARGP_NO_EXIT flag is used).  It should point to a function with the following type signature:

          void PRINT-VERSION (FILE *STREAM, struct argp_state *STATE)

     See Argp Parsing State, for an explanation of STATE.

     This variable takes precedent over argp_program_version, and is useful if a program has version information that cannot be easily specified as a simple string.

 -- Variable: 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 EX_USAGE from <sysexits.h>.

Specifying Argp Parsers
-----------------------

The first argument to the argp_parse function is a pointer to a struct argp, which known as an argp parser:

 -- 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:

     const struct argp_option *options
          A pointer to a vector of argp_option structures specifying which options this argp parser understands; it may be zero if there are no options at all.  See Argp Option Vectors.

     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 ARGP_ERR_UNKNOWN. See Argp Parser Functions.

     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 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  or:  instead of Usage:).

     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 ('\v', '\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.

     const struct argp_child *children
          A pointer to a vector of argp_children structures specifying additional argp parsers that should be combined with this one. See Argp Children.

     char *(*help_filter)(int KEY, const char *TEXT, void *INPUT)
          If non-zero, a pointer to a function to filter the output of help messages.  See Argp Help Filtering.

The options, parser, args_doc, and 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).

Specifying Options in an Argp Parser
------------------------------------

The options field in a struct argp points to a vector of 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 { 0 } is enough to achieve this).

 -- 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:

     const char *name
          The long name for this option, corresponding to the long option --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 OPTION_ALIAS flag set (see Argp Option Flags).

     int key
          The integer key that is provided to the argp parser's parsing function when this option is being parsed.  Also, if KEY has a value that is a printable ASCII character (i.e., isascii (KEY) is true), it also specifies a short option -CHAR, where CHAR is the ASCII character with the code KEY.

     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 --NAME=VALUE or -CHAR VALUE syntaxes) unless the OPTION_ARG_OPTIONAL flag (see Argp Option Flags) is set, in which case it may be provided.

     int flags
          Flags associated with this option (some of which are referred to above). See Argp Option Flags.

     const char *doc
          A documentation string for this option, for printing in help messages.

          If both the name and 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 : character.

     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, ..., N, -M, ..., -2, -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 (name and key fields both zero), in which case, the previous entry + 1 is the default.  Automagic options such as --help are put into group -1.

          Note that because of C structure initialization rules, this field often need not be specified, because 0 is the right value.

Flags for Argp Options
......................

The following flags may be or'd together in the flags field of a struct argp_option, and control various aspects of how that option is parsed or displayed in help messages:

OPTION_ARG_OPTIONAL
     The argument associated with this option is optional.

OPTION_HIDDEN
     This option isn't displayed in any help messages.

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 name and key from the aliased option.

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 documentation option).

     If this flag is set, then the option name field is displayed unmodified (e.g., no -- prefix is added) at the left-margin (where a 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 -, this entry is displayed after all options (and OPTION_DOC entries with a leading -) in the same group.

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 args_doc field (see Argp Parsers), in which case including the option in the generic usage list would be redundant.

     For instance, if args_doc is "FOO BAR\n-x BLAH", and the -x option's purpose is to distinguish these two cases, -x should probably be marked OPTION_NO_USAGE.

Argp Parser Functions
---------------------

The function pointed to by the parser field in a struct argp (see 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.

Argp parser functions have the following type signature:

     error_t PARSER (int KEY, char *ARG, struct argp_state *STATE)

where the arguments are as follows:

key
     For each option that is parsed, PARSER is called with a value of KEY from that option's key field in the option vector (see Argp Option Vectors).  PARSER is also called at other times with special reserved keys, such as ARGP_KEY_ARG for non-option arguments.  See Argp Special Keys.

arg
     If KEY is an option, ARG is the value given for it, or zero if no value was specified.  Only options that have a non-zero arg field can ever have a value, and those must always have a value, unless the 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 PARSER ever gets called).

     If KEY is ARGP_KEY_ARG, ARG is a non-option argument; other special keys always have a zero ARG.

state
     STATE points to a struct argp_state, containing useful information about the current parsing state for use by PARSER. See Argp Parsing State.

When PARSER is called, it should perform whatever action is appropriate for KEY, and return either 0 for success, ARGP_ERR_UNKNOWN, if the value of KEY is not handled by this parser function, or a unix error code if a real error occurred (see Error Codes).

 -- Macro: int ARGP_ERR_UNKNOWN
     Argp parser functions should return ARGP_ERR_UNKNOWN for any KEY value they do not recognize, or for non-option arguments (KEY == ARGP_KEY_ARG) that they do not which to handle.

A typical parser function uses a switch statement on KEY:

     error_t
     parse_opt (int key, char *arg, struct argp_state *state)
     {
       switch (key)
         {
         case OPTION_KEY:
           ACTION
           break;
         ...
         default:
           return ARGP_ERR_UNKNOWN;
         }
       return 0;
     }

Special Keys for Argp Parser Functions
......................................

In addition to key values corresponding to user options, the KEY argument to argp parser functions may have a number of other special values (ARG and STATE refer to parser function arguments; see Argp Parser Functions):

ARGP_KEY_ARG
     This is not an option at all, but rather a command line argument, whose value is pointed to by 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 ARGP_ERR_UNKNOWN; if an argument is handled by no one, 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 ARGP_KEY_NO_ARGS case won't be used. However, if while processing the argument, a parser function decrements the next field of its 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.

ARGP_KEY_ARGS
     If a parser function returns ARGP_ERR_UNKNOWN for ARGP_KEY_ARG, it is immediately called again with the key ARGP_KEY_ARGS, which has a similar meaning, but is slightly more convenient for consuming all remaining arguments.  ARG is 0, and the tail of the argument vector may be found at STATE->argv + STATE->next.  If success is returned for this key, and STATE->next is unchanged, then all remaining arguments are considered to have been consumed, otherwise, the amount by which STATE->next has been adjust indicates how many were used. For instance, here's an example that uses both, for different args:

          ...
          case ARGP_KEY_ARG:
            if (STATE->arg_num == 0)
              /* First argument */
              first_arg = ARG;
            else
              /* Let the next case parse it.  */
              return ARGP_KEY_UNKNOWN;
            break;
          case ARGP_KEY_ARGS:
            remaining_args = STATE->argv + STATE->next;
            num_remaining_args = STATE->argc - STATE->next;
            break;

ARGP_KEY_END
     There are no more command line arguments at all.

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 ARGP_KEY_END (where more general validity checks on previously parsed arguments can take place).

ARGP_KEY_INIT
     Passed in before any parsing is done.  Afterwards, the values of each element of the child_input field of STATE, if any, are copied to each child's state to be the initial value of the input when their parsers are called.

ARGP_KEY_SUCCESS
     Passed in when parsing has successfully been completed (even if there are still arguments remaining).

ARGP_KEY_ERROR
     Passed in if an error has occurred, and parsing terminated (in which case a call with a key of ARGP_KEY_SUCCESS is never made).

ARGP_KEY_FINI
     The final key ever seen by any parser (even after ARGP_KEY_SUCCESS and ARGP_KEY_ERROR).  Any resources allocated by 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 ARGP_KEY_ERROR case).

In all cases, ARGP_KEY_INIT is the first key seen by parser functions, and ARGP_KEY_FINI the last (unless an error was returned by the parser for ARGP_KEY_INIT).  Other keys can occur in one the following orders (OPT refers to an arbitrary option key):

OPT... ARGP_KEY_NO_ARGS ARGP_KEY_END ARGP_KEY_SUCCESS
     The arguments being parsed contained no non-option arguments at all.

( OPT | ARGP_KEY_ARG )... ARGP_KEY_END 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).

( OPT | ARGP_KEY_ARG )... ARGP_KEY_SUCCESS
     Some non-option argument was unrecognized.

     This occurs when every parser function returns ARGP_KEY_UNKNOWN for an argument, in which case parsing stops at that argument.  If a non-zero value for ARG_INDEX was passed to argp_parse, the index of this argument is returned in it, otherwise an error occurs.

If an error occurs (either detected by argp, or because a parser function returned an error value), then each parser is called with ARGP_KEY_ERROR, and no further calls are made except the final call with ARGP_KEY_FINI.

Functions For Use in Argp Parsers
.................................

Argp provides a number of functions for the user of argp parser functions (see Argp Parser Functions), mostly for producing error messages.  These take as their first argument the STATE argument to the parser function (see Argp Parsing State).

 -- Function: void argp_usage (const struct argp_state *STATE)
     Output the standard usage message for the argp parser referred to by STATE to STATE->err_stream and terminate the program with exit (argp_err_exit_status) (see Argp Global Variables).

 -- Function: void argp_error (const struct argp_state *STATE, const char *FMT, ...)
     Print the printf format string FMT and following args, preceded by the program name and :, and followed by a Try ... --help message, and terminate the program with an exit status of argp_err_exit_status (see Argp Global Variables).

 -- Function: void argp_failure (const struct argp_state *STATE, int STATUS, int ERRNUM, const char *FMT, ...)
     Similarly to the standard gnu error-reporting function error, print the printf format string FMT and following args, preceded by the program name and :, and followed by the standard unix error text for ERRNUM if it is non-zero; then if STATUS is non-zero, terminate the program with that as its exit status.

     The difference between this function and argp_error is that argp_error is for parsing errors, whereas 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.

 -- Function: void argp_state_help (const struct argp_state *STATE, FILE *STREAM, unsigned FLAGS)
     Output a help message for the argp parser referred to by STATE to STREAM.  The FLAGS argument determines what sort of help message is produced.  See Argp Help Flags.

Error output is sent to STATE->err_stream, and the program name printed is STATE->name.

The output or program termination behavior of these functions may be suppressed if the ARGP_NO_EXIT or ARGP_NO_ERRS flags, respectively, were passed to argp_parse.  See 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 doesn't terminate; for example:

     if (BAD ARGUMENT SYNTAX)
       {
          argp_usage (STATE);
          return EINVAL;
       }

If it's known that a parser function will only be used when ARGP_NO_EXIT is not set, the return may be omitted.

Argp Parsing State
..................

The third argument to argp parser functions (see Argp Parser Functions) is a pointer to a struct argp_state, which contains information about the state of the option parsing.

 -- Data Type: struct argp_state
     This structure has the following fields, which may be modified as noted:

     const struct argp *const root_argp
          The top level argp parser being parsed.  Note that this is often not the same struct argp passed into argp_parse by the invoking program (see Argp), but instead an internal argp parser that contains options implemented by argp_parse itself (such as --help).

     int argc
     char **argv
          The argument vector being parsed.  May be modified.

     int next
          The index in argv of the next argument to be parsed.  May be modified.

          One way to consume all remaining arguments in the input is to set STATE->next = STATE->argc (perhaps after recording the value of the 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 STATE->argv[STATE->next] to be the option that should be reexamined.

     unsigned flags
          The flags supplied to argp_parse.  May be modified, although some flags may only take effect when argp_parse is first invoked. See Argp Flags.

     unsigned arg_num
          While calling a parsing function with the KEY argument 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.

     int quoted
          If non-zero, the index in argv of the first argument following a special -- argument (which prevents anything following being interpreted as an option).  Only set once argument parsing has proceeded past this point.

     void *input
          An arbitrary pointer passed in from the caller of argp_parse, in the INPUT argument.

     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 STATE->child_inputs[I] as its STATE->input field, where I is the index of the child in the this parser's children field.  See Argp Children.

     void *hook
          For the parser function's use.  Initialized to 0, but otherwise ignored by argp.

     char *name
          The name used when printing messages.  This is initialized to argv[0], or program_invocation_name if that is unavailable.

     FILE *err_stream
     FILE *out_stream
          Stdio streams used when argp prints something; error messages are printed to err_stream, and all other output (such as --help output) to out_stream.  These are initialized to stderr and stdout respectively (see Standard Streams).

     void *pstate
          Private, for use by the argp implementation.

Combining Multiple Argp Parsers
-------------------------------

The children field in a 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 struct argp_child, terminated by an entry having a value of zero in the 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.

 -- Data Type: struct argp_child
     An entry in the list of subsidiary argp parsers pointed to by the children field in a struct argp.  The fields are as follows:

     const struct argp *argp
          The child argp parser, or zero to end the list.

     int flags
          Flags for this child.

     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 "".  As with header strings specified in an option entry, the value conventionally has : as the last character.  See Argp Option Vectors.

     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 group field in struct argp_option (see Argp Option Vectors), but all child-groupings follow parent options at a particular group level.  If both this field and 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).

Flags for argp_parse
--------------------

The default behavior of 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 FLAGS argument to argp_parse:

ARGP_PARSE_ARGV0
     Don't ignore the first element of the ARGV argument to argp_parse.  Normally (and always unless 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.

ARGP_NO_ERRS
     Don't print error messages for unknown options to stderr; unless this flag is set, ARGP_PARSE_ARGV0 is ignored, as argv[0] is used as the program name in the error messages.  This flag implies ARGP_NO_EXIT (on the assumption that silent exiting upon errors is bad behaviour).

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 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.  See Argp Parser Functions.

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

ARGP_NO_HELP
     Don't provide the standard long option --help, which ordinarily causes usage and option help information to be output to stdout, and exit (0) called.

ARGP_NO_EXIT
     Don't exit on errors (they may still result in error messages).

ARGP_LONG_ONLY
     Use the gnu getopt `long-only' rules for parsing arguments.  This allows long-options to be recognized with only a single - (for instances, -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.

ARGP_SILENT
     Turns off any message-printing/exiting options, specifically ARGP_NO_EXIT, ARGP_NO_ERRS, and ARGP_NO_HELP.

Customizing Argp Help Output
----------------------------

The help_filter field in a struct argp is a pointer to a function to filter the text of help messages before displaying them. They have a function signature like:

     char *HELP-FILTER (int KEY, const char *TEXT, void *INPUT)

where KEY is either a key from an option, in which case TEXT is that option's help text (see Argp Option Vectors), or one of the special keys with names beginning with ARGP_KEY_HELP_, describing which other help text TEXT is (see Argp Help Filter Keys).

The function should return either TEXT, if it should be used as-is, a replacement string, which should be allocated using malloc, and will be freed by argp, or zero, meaning `print nothing'.  The value of TEXT supplied is after any translation has been done, so if any of the replacement text also needs translation, that should be done by the filter function.  INPUT is either the input supplied to argp_parse, or zero, if argp_help was called directly by the user.

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 TEXT argument contains:

ARGP_KEY_HELP_PRE_DOC
     Help text preceding options.

ARGP_KEY_HELP_POST_DOC
     Help text following options.

ARGP_KEY_HELP_HEADER
     Option header string.

ARGP_KEY_HELP_EXTRA
     After all other documentation; TEXT is zero for this key.

ARGP_KEY_HELP_DUP_ARGS_NOTE
     The explanatory note emitted when duplicate option arguments have been suppressed.

ARGP_KEY_HELP_ARGS_DOC
     The argument doc string (the args_doc field from the argp parser; see Argp Parsers).

The argp_help Function
----------------------

Normally programs using argp need not worry too much about printing argument-usage-type help messages, because the standard --help option is handled automatically by argp, and the typical error cases can be handled using argp_usage and argp_error (see 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 argp_help interface.

 -- Function: void argp_help (const struct argp *ARGP, FILE *STREAM, unsigned FLAGS, char *NAME)
     Output a help message for the argp parser ARGP to STREAM. What sort of messages is printed is determined by FLAGS.

     Any options such as --help that are implemented automatically by argp itself will not be present in the help output; for this reason, it is better to use argp_state_help if calling from within an argp parser function.  See Argp Helper Functions.

Flags for the argp_help Function
--------------------------------

When calling argp_help (see Argp Help), or argp_state_help (see Argp Helper Functions), exactly what is output is determined by the FLAGS argument, which should consist of any of the following flags, or'd together:

ARGP_HELP_USAGE
     A unix Usage: message that explicitly lists all options.

ARGP_HELP_SHORT_USAGE
     A unix Usage: message that displays only an appropriate placeholder to indicate where the options go; useful for showing the non-option argument syntax.

ARGP_HELP_SEE
     A Try ... for more help message; ... contains the program name and --help.

ARGP_HELP_LONG
     A verbose option help message that gives each option understood along with its documentation string.

ARGP_HELP_PRE_DOC
     The part of the argp parser doc string that precedes the verbose option help.

ARGP_HELP_POST_DOC
     The part of the argp parser doc string that follows the verbose option help.

ARGP_HELP_DOC
     (ARGP_HELP_PRE_DOC | ARGP_HELP_POST_DOC)

ARGP_HELP_BUG_ADDR
     A message saying where to report bugs for this program, if the argp_program_bug_address variable contains one.

ARGP_HELP_LONG_ONLY
     Modify any output appropriately to reflect ARGP_LONG_ONLY mode.

The following flags are only understood when used with argp_state_help, and control whether the function returns after printing its output, or terminates the program:

ARGP_HELP_EXIT_ERR
     Terminate the program with exit (argp_err_exit_status).

ARGP_HELP_EXIT_OK
     Terminate the program with exit (0).

The following flags are combinations of the basic ones for printing standard messages:

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.

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.

ARGP_HELP_STD_HELP
     Prints the standard response for a --help option, and terminates the program successfully.

Argp Examples
-------------

These example programs demonstrate the basic usage of argp.

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 --help.

          [file argp-ex1.c.texi not included]

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 --help option, this example will have a --version option, and will put the given documentation string and bug address in the --help output, as per GNU standards.

The variable argp contains the argument parser specification; adding fields to this structure is the way most parameters are passed to 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, argp_program_version and 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).

          [file argp-ex2.c.texi not included]

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 argp (see Argp Parsers), and specifies parse_opt as the parser function (see Argp Parser Functions).

Note that in this example, main uses a structure to communicate with the parse_opt function, a pointer to which it passes in the input argument to argp_parse (see Argp), and is retrieved by parse_opt through the input field in its state argument (see 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.

          [file argp-ex3.c.texi not included]

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 --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 KEY value ARGP_KEY_NO_ARGS, which is only given if no non-option arguments were supplied to the program (see Argp Special Keys).

For structuring the help output, two features are used: headers, which are entries in the options vector (see Argp Option Vectors) with the first four fields being zero, and a two part documentation string (in the variable doc), which allows documentation both before and after the options (see Argp Parsers); the two parts of doc are separated by a vertical-tab character ('\v', or '\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 gettext function, for possible translation into the current locale.

          [file argp-ex4.c.texi not included]

Argp User Customization
-----------------------

The way formatting of argp --help output may be controlled to some extent by a program's users, by setting the ARGP_HELP_FMT environment variable to a comma-separated list (whitespace is ignored) of the following tokens:

dup-args
no-dup-args
     Turn 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 no-dup-args, which is less consistent, but prettier.

dup-args-note

no-dup-args-note
     Enable or disable the note informing the user of suppressed option argument duplication.  The default is dup-args-note.

short-opt-col=N
     Show the first short option in column N (default 2).

long-opt-col=N
     Show the first long option in column N (default 6).

doc-opt-col=N
     Show `documentation options' (see Argp Option Flags) in column N (default 2).

opt-doc-col=N
     Show the documentation for options starting in column N (default 29).

header-col=N
     Indent group headers (which document groups of options) to column N (default 1).

usage-indent=N
     Indent continuation lines in Usage: messages to column N (default 12).

rmargin=N
     Word wrap help output at or before column N (default 79).