Node:Argp Special Keys, Next:Argp Parsing State, Up: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
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
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
ARGP_KEY_NO_ARGS
ARGP_KEY_END
, where more general validity checks on
previously parsed arguments take place.
ARGP_KEY_INIT
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
ARGP_KEY_ERROR
ARGP_KEY_SUCCESS
is never made.
ARGP_KEY_FINI
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:
ARGP_KEY_NO_ARGS
ARGP_KEY_END
ARGP_KEY_SUCCESS
ARGP_KEY_ARG
)... ARGP_KEY_END
ARGP_KEY_SUCCESS
ARGP_KEY_ARG
)... ARGP_KEY_SUCCESS
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
.