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

Argp is an interface for parsing unix-style argument vectors. See Program Arguments.

Argp provides features unavailable in the more commonly used getopt interface.  These features include automatically producing output in response to the --help and --version options, as described in the GNU coding standards.  Using argp makes it less likely that programmers will neglect to implement these additional options 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 that user programs might employ in conjunction with their own option parsers, resulting in less work for the user programs.  Some programs may use only argument parsers exported by libraries, thereby achieving consistent and efficient option-parsing for abstractions implemented by the libraries.

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.  In many cases, calling 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 argpcontaining 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 ARGP.  A typical usage is to pass a pointer to a structure which is used for specifying parameters to the parser and passing back the results.

     Unless the ARGP_NO_EXIT or ARGP_NO_HELP flags are included in FLAGS, calling argp_parse may result in the program exiting.  This behavior is true if an error is detected, or when an unknown option is encountered.  See Program Termination.

     If ARG_INDEX is non-null, the index of the first unparsed option in ARGV is returned as a value.

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

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

These variables make it easy for user programs to implement the --version option and provide a bug-reporting address in the --help output.  These are implemented in argp by default.

 -- 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, which will print the --version string followed by a newline and exit.  The exception to this is if 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 will be printed at the end of the standard output for the --help option, embedded in a sentence that says Report bugs to ADDRESS..

 -- Variable: argp_program_version_hook
     If defined or set by the user program to a non-zero value, a --version option is added when parsing with arg_parse, which prints the program version and exits with a status of zero.  This is not the case if the ARGP_NO_HELP flag is used.  If the ARGP_NO_EXIT flag is set, the exit behavior of the program is suppressed or modified, as when the argp parser is going to be used by other programs.

     It should point to a function with this type of signature:

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

     See Argp Parsing State, for an explanation of STATE.

     This variable takes precedence over argp_program_version, and is useful if a program has version information not easily expressed in a simple string.

 -- Variable: error_t argp_err_exit_status
     This is the exit status used when argp exits 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 is 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 called by this parser.  This 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 explaining what the program does.  Documentation printed after the options describe behavior in more detail.

     const struct argp_child *children
          A pointer to a vector of argp_children structures.  This pointer specifies which additional argp parsers 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 that filters the output of help messages.  See Argp Help Filtering.

     const char *argp_domain
          If non-zero, the strings used in the argp library are translated using the domain described by this string.  If zero, the current default domain is used.

Of the above group, options, parser, args_doc, and the doc fields are usually all that are needed.  If an argp parser is defined as an initialized C variable, only the fields used need be specified in the initializer.  The rest will default to zero due to the way C structure initialization works.  This design is exploited in most argp structures; the most-used fields are grouped near the beginning, the unused fields 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 the argp parser supports.  Multiple entries may be used for a single option provided it has multiple names.  This 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, as well as how to parse and document that option.  It has the following fields:

     const char *name
          The long name for this option, corresponding to the long option --NAME; this field may 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 provided by the current option to the option parser.  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 tabbed left from the normal option column, making it useful as a group header.  This will be the first thing printed in its group.  In this usage, it's conventional to end the string with a : character.

     int group
          Group identity for this option.

          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.  If it's a group header with name and key fields both zero, 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 correct value.

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

The following flags may be or'd together in the flags field of a struct argp_option.  These flags 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 option being aliased.

OPTION_DOC
     This option isn't actually an option and should be ignored by the actual option parser.  It is an arbitrary section of documentation that should be displayed in much the same manner as the options.  This is 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 this documentation string is left in it's usual place.  For purposes of sorting, any leading whitespace and punctuation is ignored, unless the first non-whitespace character is -.  This entry is displayed after all options, after OPTION_DOC entries with a leading -, in the same group.

OPTION_NO_USAGE
     This option shouldn't be included in `long' usage messages, but should still be included in other help messages.  This is intended for options that are completely documented in an argp's args_doc field.  See Argp Parsers.  Including this option in the generic usage list would be redundant, and should be avoided.

     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 parsed.  It is also used as a hook, allowing a parser to perform tasks 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 its given value.  This defaults to zero if no value is specified.  Only options that have a non-zero arg field can ever have a value.  These must always have a value unless the OPTION_ARG_OPTIONAL flag is 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 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 are not equipped 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.  In the following example 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 in play due to argp parsers being combined, it's impossible to know which one will handle a specific argument.  Each is called until one returns 0 or an error other than ARGP_ERR_UNKNOWN; if an argument is not handled, 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, all remaining arguments are considered to have been consumed.  Otherwise, the amount by which STATE->next has been adjusted indicates how many were used. 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
     This indicates that there are no more command line arguments.  Parser functions are called in a different order, children first.  This allows each parser to clean up its state for the parent.

ARGP_KEY_NO_ARGS
     Because it's common 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.  This is called just before ARGP_KEY_END, where more general validity checks on previously parsed arguments take place.

ARGP_KEY_INIT
     This is 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 arguments remain.

ARGP_KEY_ERROR
     Passed in if an error has occurred and parsing is terminated.  In this 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.  At times, certain resources allocated 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 did not contain any non-option arguments.

( 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 went unrecognized.

     This occurs when every parser function returns ARGP_KEY_UNKNOWN for an argument, in which case parsing stops at that argument if ARG_INDEX is a null pointer.  Otherwise an error occurs.

In all cases, if a non-null value for ARG_INDEX gets passed to argp_parse, the index of the first unparsed command-line argument is passed back in that value.

If an error occurs and is either detected by argp or because a parser function returned an error value, each parser is called with ARGP_KEY_ERROR.  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 available to the user of argp (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)
     Outputs 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, ...)
     Prints the printf format string FMT and following args, preceded by the program name and :, and followed by a Try ... --help message, and terminates 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, ...)
     Similar to the standard gnu error-reporting function error, this prints the program name and :, the printf format string FMT, and the appropriate following args.  If it is non-zero, the standard unix error text for ERRNUM is printed.  If STATUS is non-zero, it terminates the program with that value as its exit status.

     The difference between argp_failure 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)
     Outputs 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 are 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, and for the case where the program doesn't terminate, calls to any of these functions should be followed by code that returns the appropriate error code:

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

If 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.  It is an internal argp parser that contains options implemented by argp_parse itself, such as --help.

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

     int next
          The index in argv of the next argument to be parsed.  This 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.  The current option can be re-parsed immediately by decrementing this field, then modifying STATE->argv[STATE->next] to reflect the option that should be reexamined.

     unsigned flags
          The flags supplied to argp_parse.  These 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 represents the number of the current arg, starting at 0.  It is incremented after each ARGP_KEY_ARG call returns.  At all other times, this is the number of ARGP_KEY_ARG arguments that have been processed.

     int quoted
          If non-zero, the index in argv of the first argument following a special -- argument.  This prevents anything that follows from being interpreted as an option.  It is only set after 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
          These are values that will be passed to child parsers.  This vector will be the same length as the number of children in the current parser.  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 argv[0] is unavailable.

     FILE *err_stream
     FILE *out_stream
          The stdio streams used when argp prints.  Error messages are printed to err_stream, 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 enables other argp parsers to be combined with the referencing one for the parsing of a single set of arguments.  This field should point to a vector of struct argp_child, which is terminated by an entry having a value of zero in the argp field.

Where conflicts between combined parsers arise, as when two specify an option with the same name, the parser conflicts are resolved in favor of the parent argp parser(s), or the earlier of the 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 of the list.

     int flags
          Flags for this child.

     const char *header
          If non-zero, this is an optional header to be printed within 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 conventional value of the last character is :.  See Argp Option Vectors.

     int group
          This is where the child options are grouped 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.  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, they are merged with parent options at the parent option group level.

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.  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.  This is based on the assumption that silent exiting upon errors is bad behavior.

ARGP_NO_ARGS
     Don't parse any non-option args.  Normally these are parsed by calling the parse functions with a key of ARGP_KEY_ARG, the actual argument being the value.  This flag needn't normally be set, as the default behavior is to stop parsing as soon as an argument fails to be parsed.  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).

ARGP_NO_EXIT
     Don't exit on errors, although 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 - (i.e., -help).  This results in a less useful interface, and its use is discouraged as it conflicts with the way most GNU programs work as well as the GNU coding standards.

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 that filters 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.  Alternately, one of the special keys with names beginning with ARGP_KEY_HELP_ might be used, describing which other help text TEXT will contain. See Argp Help Filter Keys.

The function should return either TEXT if it remains as-is, or a replacement string allocated using malloc.  This will be either be freed by argp or zero, which prints nothing.  The value of TEXT is supplied after any translation has been done, so if any of the replacement text needs translation, it will be done by the filter function.  INPUT is either the input supplied to argp_parse or it is 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.  They specify which help text the TEXT argument contains:

ARGP_KEY_HELP_PRE_DOC
     The help text preceding options.

ARGP_KEY_HELP_POST_DOC
     The help text following options.

ARGP_KEY_HELP_HEADER
     The option header string.

ARGP_KEY_HELP_EXTRA
     This is used after all other documentation; TEXT is zero for this key.

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

ARGP_KEY_HELP_ARGS_DOC
     The argument doc string; formally the args_doc field from the argp parser.  See Argp Parsers.

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

Normally programs using argp need not be written with particular printing argument-usage-type help messages in mind as the standard --help option is handled automatically by argp.  Typical error cases can be handled using argp_usage and argp_error.  See Argp Helper Functions.  However, if it's desirable to print a 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)
     This outputs a help message for the argp parser ARGP to STREAM.  The type of messages printed will be 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 best 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) the exact output is determined by the FLAGS argument.  This 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 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 available along with its documentation string.

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

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

ARGP_HELP_DOC
     (ARGP_HELP_PRE_DOC | ARGP_HELP_POST_DOC)

ARGP_HELP_BUG_ADDR
     A message that prints where to report bugs for this program, if the argp_program_bug_address variable contains this information.

ARGP_HELP_LONG_ONLY
     This will modify any output to reflect the ARGP_LONG_ONLY mode.

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

ARGP_HELP_EXIT_ERR
     This will terminate the program with exit (argp_err_exit_status).

ARGP_HELP_EXIT_OK
     This will terminate the program with exit (0).

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

ARGP_HELP_STD_ERR
     Assuming that an error message for a parsing error has printed, this prints a message on how to get help, and terminates the program with an error.

ARGP_HELP_STD_USAGE
     This prints a standard usage message and terminates the program with an error.  This is used when no other specific error messages are appropriate or available.

ARGP_HELP_STD_HELP
     This 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 perhaps the smallest program possible that uses argp.  It won't do much except give an error messages and exit when there are any arguments, and prints 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, it uses argp to be compliant with the GNU standard command line format.

In addition to giving no arguments and implementing a --help option, this example has a --version option, which 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 normally used, but they are not in this small program.  There are also two global variables that argp can use defined here, argp_program_version and argp_program_bug_address.  They are considered global variables because they will almost always be constant for a given program, even if they use 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, adding user options and arguments.

We now use the first four fields in argp (see Argp Parsers) and specify 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.  It 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 presents more structure in the --help output.  It also illustrates how you can `steal' the remainder of the input arguments past a certain point for programs that accept a list of items.  It also illustrates the 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 help output, two features are used: headers and a two part option string.  The headers are entries in the options vector.  See Argp Option Vectors.  The first four fields are zero.  The two part documentation string are 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 a short string stating what the program does, and after any options it 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.  In addition, documentation strings are passed to the gettext function, for possible translation into the current locale.

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

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

The 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 of tokens.  Whitespace is ignored:

dup-args
no-dup-args
     These turn duplicate-argument-mode on or off.  In duplicate argument mode, if an option that accepts an argument has multiple names, the argument is shown for each name.  Otherwise, it is only shown for the first long option.  A note is subsequently printed so the user knows that it applies to other names as well.  The default is no-dup-args, which is less consistent, but prettier.

dup-args-note

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

short-opt-col=N
     This prints the first short option in column N.  The default is 2.

long-opt-col=N
     This prints the first long option in column N.  The default is 6.

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

opt-doc-col=N
     This prints the documentation for options starting in column N.  The default is 29.

header-col=N
     This will indent the group headers that document groups of options to column N.  The default is 1.

usage-indent=N
     This will indent continuation lines in Usage: messages to column N.  The default is 12.

rmargin=N
     This will word wrap help output at or before column N.  The default is 79.