Args

An argument-parsing library for C.

Version 2.8.0

API Reference



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

Setup

ArgParser* ap_new()

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 the program's command line arguments.

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 if the arguments were parsed successfully, or false if parsing failed due to a memory allocation error.

Specifying Flags and Options

void ap_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_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_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_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.

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_str_value(ArgParser* parser, char* name)

Returns the value of the specified string-valued option. The 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_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 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_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_int_value(ArgParser* parser, char* name)

Returns the value of the specified integer-valued option.

int ap_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_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_dbl_value(ArgParser* parser, char* name)

Returns the value of the specified double-valued option.

double ap_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_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_arg(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_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_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_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.

Commands

typedef void (*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 void.

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

Registers a new command. Returns the 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 parser instance.

void ap_callback(ArgParser* parser, ap_callback_t function)

Registers an optional 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.

bool ap_has_cmd(ArgParser* parser)

Returns true if the parser has found a command.

char* ap_cmd_name(ArgParser* parser)

Returns the command name if the parser has found a command, otherwise NULL.

ArgParser* ap_cmd_parser(ArgParser* parser)

Returns the command's parser instance if the parser has found a command, otherwise NULL.

void ap_enable_help_command(ArgParser* parser, bool enable)

This boolean switch toggles support for an automatic help command which 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.