parg.h

/*
 * parg - parse argv
 *
 * Copyright 2015-2023 Joergen Ibsen
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the "Software"),
 * to deal in the Software without restriction, including without limitation
 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
 * and/or sell copies of the Software, and to permit persons to whom the
 * Software is furnished to do so.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 * DEALINGS IN THE SOFTWARE.
 *
 * SPDX-License-Identifier: MIT-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 3        /**< Patch version number */
#define PARG_VER_STRING "1.0.3" /**< Version number as a string */

/**
 * Structure containing state between calls to parser.
 *
 * @see 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 `parg_getopt_long()`.
 *
 * @see 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
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
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 `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 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
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 `parg_getopt()` and
 * `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
parg_reorder(int argc, char *argv[],
             const char *optstring,
             const struct parg_option *longopts);

#ifdef __cplusplus
} /* extern "C" */
#endif

#endif /* PARG_H_INCLUDED */