FlagParse.h

Parser for command-line flags with GNU-style format.

License: GPL-3.0-or-later.

Features

Support for long and short options.
Support for adding -- to list of long options (for custom parsing semantics).
It support terminated arguments - argument list ends not only when size is reached (or when argument starts from -) but only when terminator reached.
It support optional arguments.
Flag grouping (to pretty-print them for help).
Help formatter.
Custom help and version hooks (parsing for that flags are built-in).

Limitations

Short options can be only 1 character.
Arguments are always returned as strings.

Some of these functions takes pointers. They expect this pointers either to be statically allocated or be dynamically allocated and then leaked. This memory will live trough full app lifetime, so this leakage has no problems. But if you use valgrind you should probably not use reachable in --errors-for-leak-kinds (because flag context live as global variable).

Flags format

This parses uses something that roughly mimics “GNU” style of flags. This means that -- precedes long versions of flags and - short versions. Also, should versions can be grouped together and each character will then be parsed as a separate flag. = is supported for both long and short flag versions so things like --flag=argument or -f=argument can be used. Even things like -abc=argument will be correctly parsed to 3 flags - a, b and c, with last one having 1 argument - argument. Support for -- is implemented and it stops searching for flags. Positional arguments are supported too.

cbuild_flag_new_opts_t

struct cbuild_flag_new_opts_t {
char short_option;
union {
uint8_t __flags;
struct {
uint8_t optional : 1;
uint8_t repeat : 1;
uint8_t : 6;
};
};
int8_t num_arguments; // No one need more than 127 arguments (at least then fixed count becomes meaningless).
// uint8_t __padding[1];
const char* group;
const char* terminator;
const char* desc;
const char* argument_desc;
};

Options for a new flag

char short_option Character for short options. If '\0' (0) then disabled.
uint8_t:1 optional Arguments to this flag are optional. This augments num_arguments field by allowing another option of passing no arguments (in addition to one provided by num_arguments).
uint8_t:1 repeat If ‘false’ repeated flag invocation result in error. If ‘true’ each invocation of flag just append argument to shared list (if flag has argument limit it is treated as a per-invocation limit).
int8_t num_arguments Number of arguments required. -1 means >0.
const char* group Name of arguments group. Used only for help message. Can be NULL.
const char* terminator Terminator argument. Can be NULL (unset, non-terminated argument list).
const char* desc Description. Can be NULL, then nothing will be printed.
const char* argument_desc Description for argumentt. Can be NULL, then default ‘ARGUMENT’ will be used. Used only if num_arguments != 0.

cbuild_flag_new_opt

CBUILDDEF void cbuild_flag_new_opt(const char* option, struct cbuild_flag_new_opts_t opts);

cbuild_flag_new

#define cbuild_flag_new(option, ...)

const char* option Long flag name. Will be used as its internal “ID’.
...cbuild_flag_new_opts_t … Fields of configuration structure in initializer-list form.

cbuild_flag_options_t

enum cbuild_flag_options_t {
CBUILD_FLAG_PASS_SEPARATOR,
CBUILD_FLAG_HELP_HOOK,
CBUILD_FLAG_VERSION_HOOK,
};

Options for a flag parser

CBUILD_FLAG_PASS_SEPARATOR Pass -- inside of pargs. No arguments.
CBUILD_FLAG_HELP_HOOK Set hook for --help. Argument - cbuild_flag_print_func_t
CBUILD_FLAG_VERSION_HOOK Set hook for --version. Argument - cbuild_flag_print_func_t

cbuild_flag_print_func_t

typedef void (*cbuild_flag_print_func_t)(const char* app_name);

Function used for print-type hooks. Takes argv[0] as input.

cbuild_flag_set_option

CBUILDDEF void cbuild_flag_set_option(enum cbuild_flag_options_t option, ...);

Set some option for a flag parser.

Options can take some flags, they are passed via variadic arguments.

cbuild_arglist_t

typedef struct cbuild_arglist_t {
char** data;
size_t size;
size_t capacity;
} cbuild_arglist_t;

List of arguments

cbuild_arglist_get

#define cbuild_arglist_get(arglist, idx)

Get element from argument list using its index.

const cbuild_arglist_t* arglist Argument list.
size_t idx Element index.

char** Pointer to an element or NULL on overflow.

cbuild_flag_parse

CBUILDDEF void cbuild_flag_parse(int argc, char** argv);

Parse flags.

This function prints error and aborts on invalid flags and when parsed argument count differs from required (uses exit(1)).

cbuild_flag_print_help

CBUILDDEF void cbuild_flag_print_help(void);

Print help for all flags via __CBUILD_PRINT

cbuild_flag_get_pargs

CBUILDDEF cbuild_arglist_t* cbuild_flag_get_pargs(void);

Get list of positional arguments.

cbuild_arglist_t* List of positional arguments (pointer to a global state).

cbuild_flag_get_flag

CBUILDDEF cbuild_arglist_t* cbuild_flag_get_flag(const char* opt);

Get arguments for a specific flag.

cbuild_arglist_t* List of arguments for that flag (pointer to a global state) or NULL if flag was not provided.

cbuild_flag_app_name

CBUILDDEF const char* cbuild_flag_app_name(void);

Get current app name (argv[0]).