ref: 742736e50d97306ad16853d18c977b502cf35b82
dir: /libnpe/_parg.h/
/*
* parg - parse argv
*
* Written in 2015-2016 by Joergen Ibsen
*
* To the extent possible under law, the author(s) have dedicated all
* copyright and related and neighboring rights to this software to the
* public domain worldwide. This software is distributed without any
* warranty. <http://creativecommons.org/publicdomain/zero/1.0/>
*/
#ifndef PARG_H_INCLUDED
#define PARG_H_INCLUDED
#ifdef __cplusplus
extern "C" {
#endif
#define PARG_VER_MAJOR 1 /**< Major version number */
#define PARG_VER_MINOR 0 /**< Minor version number */
#define PARG_VER_PATCH 2 /**< Patch version number */
#define PARG_VER_STRING "1.0.2" /**< Version number as a string */
/**
* Structure containing state between calls to parser.
*
* @see npe_parg_init
*/
struct parg_state {
const char *optarg; /**< Pointer to option argument, if any */
int optind; /**< Next index in argv to process */
int optopt; /**< Option value resulting in error, if any */
const char *nextchar; /**< Next character to process */
};
/**
* Structure for supplying long options to `npe_parg_getopt_long()`.
*
* @see npe_parg_getopt_long
*/
struct parg_option {
const char *name; /**< Name of option */
int has_arg; /**< Option argument status */
int *flag; /**< Pointer to flag variable */
int val; /**< Value of option */
};
/**
* Values for `has_arg` flag in `parg_option`.
*
* @see parg_option
*/
typedef enum {
PARG_NOARG, /**< No argument */
PARG_REQARG, /**< Required argument */
PARG_OPTARG /**< Optional argument */
} parg_arg_num;
/**
* Initialize `ps`.
*
* Must be called before using state with a parser.
*
* @see parg_state
*
* @param ps pointer to state
*/
void
npe_parg_init(struct parg_state *ps);
/**
* Parse next short option in `argv`.
*
* Elements in `argv` that contain short options start with a single dash
* followed by one or more option characters, and optionally an option
* argument for the last option character. Examples are '`-d`', '`-ofile`',
* and '`-dofile`'.
*
* Consecutive calls to this function match the command-line arguments in
* `argv` against the short option characters in `optstring`.
*
* If an option character in `optstring` is followed by a colon, '`:`', the
* option requires an argument. If it is followed by two colons, the option
* may take an optional argument.
*
* If a match is found, `optarg` points to the option argument, if any, and
* the value of the option character is returned.
*
* If a match is found, but is missing a required option argument, `optopt`
* is set to the option character. If the first character in `optstring` is
* '`:`', then '`:`' is returned, otherwise '`?`' is returned.
*
* If no option character in `optstring` matches a short option, `optopt`
* is set to the option character, and '`?`' is returned.
*
* If an element of argv does not contain options (a nonoption element),
* `optarg` points to the element, and `1` is returned.
*
* An element consisting of a single dash, '`-`', is returned as a nonoption.
*
* Parsing stops and `-1` is returned, when the end of `argv` is reached, or
* if an element contains '`--`'.
*
* Works similarly to `getopt`, if `optstring` were prefixed by '`-`'.
*
* @param ps pointer to state
* @param argc number of elements in `argv`
* @param argv array of pointers to command-line arguments
* @param optstring string containing option characters
* @return option value on match, `1` on nonoption element, `-1` on end of
* arguments, '`?`' on unmatched option, '`?`' or '`:`' on option argument
* error
*/
int
npe_parg_getopt(struct parg_state *ps, int argc, char *const argv[],
const char *optstring);
/**
* Parse next long or short option in `argv`.
*
* Elements in `argv` that contain a long option start with two dashes
* followed by a string, and optionally an equal sign and an option argument.
* Examples are '`--help`' and '`--size=5`'.
*
* If no exact match is found, an unambiguous prefix of a long option will
* match. For example, if '`foo`' and '`foobar`' are valid long options, then
* '`--fo`' is ambiguous and will not match, '`--foo`' matches exactly, and
* '`--foob`' is an unambiguous prefix and will match.
*
* If a long option match is found, and `flag` is `NULL`, `val` is returned.
*
* If a long option match is found, and `flag` is not `NULL`, `val` is stored
* in the variable `flag` points to, and `0` is returned.
*
* If a long option match is found, but is missing a required option argument,
* or has an option argument even though it takes none, `optopt` is set to
* `val` if `flag` is `NULL`, and `0` otherwise. If the first character in
* `optstring` is '`:`', then '`:`' is returned, otherwise '`?`' is returned.
*
* If `longindex` is not `NULL`, the index of the entry in `longopts` that
* matched is stored there.
*
* If no long option in `longopts` matches a long option, '`?`' is returned.
*
* Handling of nonoptions and short options is like `npe_parg_getopt()`.
*
* If no short options are required, an empty string, `""`, should be passed
* as `optstring`.
*
* Works similarly to `getopt_long`, if `optstring` were prefixed by '`-`'.
*
* @see npe_parg_getopt
*
* @param ps pointer to state
* @param argc number of elements in `argv`
* @param argv array of pointers to command-line arguments
* @param optstring string containing option characters
* @param longopts array of `parg_option` structures
* @param longindex pointer to variable to store index of matching option in
* @return option value on match, `0` for flag option, `1` on nonoption
* element, `-1` on end of arguments, '`?`' on unmatched or ambiguous option,
* '`?`' or '`:`' on option argument error
*/
int
npe_parg_getopt_long(struct parg_state *ps, int argc, char *const argv[],
const char *optstring,
const struct parg_option *longopts, int *longindex);
/**
* Reorder elements of `argv` so options appear first.
*
* If there are no long options, `longopts` may be `NULL`.
*
* The return value can be used as `argc` parameter for `npe_parg_getopt()` and
* `npe_parg_getopt_long()`.
*
* @param argc number of elements in `argv`
* @param argv array of pointers to command-line arguments
* @param optstring string containing option characters
* @param longopts array of `parg_option` structures
* @return index of first nonoption in `argv` on success, `-1` on error
*/
int
npe_parg_reorder(int argc, char *argv[],
const char *optstring,
const struct parg_option *longopts);
#ifdef __cplusplus
} /* extern "C" */
#endif
#endif /* PARG_H_INCLUDED */