• Setup
• Teardown
• Parsing Arguments
• Specifying Flags and Options
• Retrieving Values
• Positional Arguments
• Command Setup
• Command Inspection
• Parent Parsers
• Parsing Modes

This library is written in portable C99. The header exports an ArgParser type and a collection of ap_* prefixed functions.

Setup

ArgParser* ap_new_parser()

Initializes a new ArgParser instance. Returns NULL if memory allocation fails.

void ap_set_helptext(ArgParser* parser, char* helptext)

Supplies a helptext string for the parser; this activates an automatic --help flag, also a -h shortcut if not explicitly registered by another option.

(The parser stores and manages its own internal copy of the helptext string, so helptext can be freed immediately after this call if it was dynamically constructed.)

char* ap_get_helptext(ArgParser* parser)

Returns a pointer to the parser's helptext string.

void ap_set_version(ArgParser* parser, char* version)

Supplies a version string for the parser; this activates an automatic --version flag, also a -v shortcut if not explicitly registered by another option.

(The parser stores and manages its own internal copy of the version string, so version can be freed immediately after this call if it was dynamically constructed.)

char* ap_get_version(ArgParser* parser)

Returns a pointer to the parser's version string.

Teardown

void ap_free(ArgParser* parser)

Frees the memory occupied by an ArgParser instance.

(This function should only be called on the root parser instance — it will automatically free the memory occupied by any command parsers registered on the root parser.)

Parsing Arguments

bool ap_parse(ArgParser* parser, int argc, char** argv)

Parses an array of string arguments. Exits with an error message and a non-zero status code if the arguments are invalid.

The arguments are assumed to be argc and argv as supplied to main(), i.e. the first element in argv is assumed to be the binary name and will be ignored.

Returns true on success, or false if an attempt to allocate memory failed. (You can safely call ap_free() on the parser even if the return value is false.)

Specifying Flags and Options

void ap_add_flag(ArgParser* parser, char* name)

Registers a new flag. The name parameter accepts an unlimited number of space-separated aliases and single-character shortcuts.

void ap_add_str_opt(ArgParser* parser, char* name, char* fallback)

Registers a new string-valued option. The name parameter accepts an unlimited number of space-separated aliases and single-character shortcuts. The fallback parameter specifies the option's default value.

void ap_add_int_opt(ArgParser* parser, char* name, int fallback)

Registers a new integer-valued option. The name parameter accepts an unlimited number of space-separated aliases and single-character shortcuts. The fallback parameter specifies the option's default value.

void ap_add_dbl_opt(ArgParser* parser, char* name, double fallback)

Registers a new double-valued option. The name parameter accepts an unlimited number of space-separated aliases and single-character shortcuts. The fallback parameter specifies the option's default value.

void ap_add_greedy_str_opt(ArgParser* parser, char* name)

Registers a new greedy string-valued option. A greedy option parses all subsequent arguments as option values, including arguments beginning with - or --.

The name parameter accepts an unlimited number of space-separated aliases and single-character shortcuts.

Retrieving Values

Any of an option's registered aliases or shortcuts can be used for the name parameter in the functions below.

bool ap_found(ArgParser* parser, char* name)

Returns true if the specified flag or option was found.

int ap_count(ArgParser* parser, char* name)

Returns the number of times the specified flag or option was found.

char* ap_get_str_value(ArgParser* parser, char* name)

Returns the value of the specified string-valued option. If multiple values were parsed for the option, this returns the final value.

The returned pointer points to the appropriate value in the array of strings supplied to the ap_parse() function or to the fallback string specified when registering the option.

char* ap_get_str_value_at_index(ArgParser* parser, char* name, int index)

For a string-valued option with multiple values, returns the value at the specified index.

The returned pointer points to the appropriate value in the array of strings supplied to the ap_parse() function.

The number of values is given by ap_count().

char** ap_get_str_values(ArgParser* parser, char* name)

Returns the specified option's list of values as a freshly-allocated array of string pointers. Each pointer in the array points to the appropriate value in the array of strings supplied to the ap_parse() function. The size of the array is given by ap_count().

The returned array's memory is not affected by calls to ap_free(). The array should be freed after use by the caller using free().

Returns NULL if memory cannot be allocated for the array.

int ap_get_int_value(ArgParser* parser, char* name)

Returns the value of the specified integer-valued option. If multiple values were parsed for the option, this returns the final value.

int ap_get_int_value_at_index(ArgParser* parser, char* name, int index)

For an integer-valued option with multiple values, returns the value at the specified index. The number of values is given by ap_count().

int* ap_get_int_values(ArgParser* parser, char* name)

Returns the specified option's list of values as a freshly-allocated array of integers. The size of the array is given by ap_count().

The returned array's memory is not affected by calls to ap_free(). The array should be freed after use by the caller using free().

Returns NULL if memory cannot be allocated for the array.

double ap_get_dbl_value(ArgParser* parser, char* name)

Returns the value of the specified double-valued option. If multiple values were parsed for the option, this returns the final value.

double ap_get_dbl_value_at_index(ArgParser* parser, char* name, int index)

For a double-valued option with multiple values, returns the value at the specified index. The number of values is given by ap_count().

double* ap_get_dbl_values(ArgParser* parser, char* name)

Returns the specified option's list of values as a freshly-allocated array of doubles. The size of the array is given by ap_count().

The returned array's memory is not affected by calls to ap_free(). The array should be freed after use by the caller using free().

Returns NULL if memory cannot be allocated for the array.

Positional Arguments

bool ap_has_args(ArgParser* parser)

Returns true if at least one positional argument has been found.

int ap_count_args(ArgParser* parser)

Returns the number of positional arguments.

char* ap_get_arg_at_index(ArgParser* parser, int index)

Returns the positional argument at the specified index. The pointer points to the appropriate string value in the array of strings originally supplied to the ap_parse() function.

char** ap_get_args(ArgParser* parser)

Returns the positional arguments as a freshly-allocated array of string pointers. Each pointer in the array points to the appropriate string value in the array of strings originally supplied to the ap_parse() function. The size of the array is given by ap_count_args().

The memory occupied by the returned array is not affected by calls to ap_free(). The array should be freed after use by the caller using free().

Returns NULL if memory cannot be allocated for the array.

int* ap_get_args_as_ints(ArgParser* parser)

Attempts to parse and return the positional arguments as a freshly-allocated array of integers. The size of the array is given by ap_count_args().

Exits with an error message if the arguments cannot be parsed as integers.

The memory occupied by the returned array is not affected by calls to ap_free(). The array should be freed after use by the caller using free().

Returns NULL if memory cannot be allocated for the array.

double* ap_get_args_as_doubles(ArgParser* parser)

Attempts to parse and return the positional arguments as a freshly-allocated array of doubles. The size of the array is given by ap_count_args().

Exits with an error message if the arguments cannot be parsed as doubles.

The memory occupied by the returned array is not affected by calls to ap_free(). The array should be freed after use by the caller using free().

Returns NULL if memory cannot be allocated for the array.

Command Setup

typedef int (*ap_callback_t)(char* cmd_name, ArgParser* cmd_parser)

A callback function for a command should accept two arguments — the command's name and the command's ArgParser instance. It should return an integer status code.

ArgParser* ap_new_cmd(ArgParser* parent_parser, char* name)

Registers a new command. Returns the new ArgParser instance for the command.

The name parameter accepts an unlimited number of space-separated aliases for the command.

Returns NULL if sufficient memory cannot be allocated for the new ArgParser instance.

void ap_set_cmd_callback(ArgParser* cmd_parser, ap_callback_t cmd_callback)

Registers a callback function on a command parser. If the command is found, this function will be called and passed the command's name and ArgParser instance.

void ap_enable_help_command(ArgParser* parent_parser, bool enable)

This boolean switch toggles support for an automatic help command that prints subcommand helptext. The value defaults to false but gets toggled automatically to true whenever a command is registered. You can use this function to disable the feature if required.

Command Inspection

bool ap_found_cmd(ArgParser* parent_parser)

Returns true if parent_parser has found a command.

char* ap_get_cmd_name(ArgParser* parent_parser)

If parent_parser has found a command, returns its name, otherwise NULL.

ArgParser* ap_get_cmd_parser(ArgParser* parent_parser)

If parent_parser has found a command, returns its ArgParser instance, otherwise NULL.

int ap_get_cmd_exit_code(ArgParser* parent_parser)

If parent_parser has found a command, and if that command has a callback function, returns the exit code returned by the callback, otherwise 0.

Parent Parsers

ArgParser* ap_get_parent(ArgParser* parser)

If parser has a parent — i.e. if parser is a command parser — returns its parent, otherwise NULL.

Parsing Modes

void ap_all_args_as_pos_args(ArgParser* parser)

If set, all arguments will be treated as positional arguments, even arguments beginning with - or --.

void ap_first_pos_arg_ends_option_parsing(ArgParser* parser)

If set, the first positional argument ends option-parsing — i.e. all subsequent arguments will be teated as positional arguments, even arguments beginning with - or --.