argument Struct Reference

Detailed Description

Declarative schema object for one CLI argument.

Initialize this type through ARGUMENT. C designated initializers let you specify only the fields you need.

Invariant

At least one of argument::opt or argument::lopt is set.

Data Fields
Storage
bool *	set
	Tracks whether the user supplied this argument.
void *	dest
	Destination pointer passed as dest to parser callbacks.
Callbacks
struct arg_callback(*	parse_callback )(const char *str, void *dest)
	Function invoked during args_parse.
struct arg_callback(*	validate_callback )(void)
	Function invoked during args_validate.
void(*	action_callback )(void)
	Function invoked during args_actions.
Schema
enum arg_requirement	arg_req
	Specifies whether this argument is required, optional, or hidden.
enum arg_parameter	param_req
	Specifies whether this argument takes a parameter and if it's required.
enum arg_callback_phase	validate_phase
	Controls when argument::validate_callback runs.
enum arg_callback_phase	action_phase
	Controls when argument::action_callback runs.
Ordering
struct argument *	validate_order
	Ordering for validation.
struct argument *	action_order
	Ordering for action execution.
struct argument *	help_order
	Ordering for help display.
Help Presentation
const char *	help
	Help description for this argument.
const char *	param
	Parameter name for help display (e.g., "N" for a number).
const char *	lopt
	Long option name (e.g. "output" -> --output).
char	opt
	Short option character (e.g. 'o' -> -o).

Field Documentation

set

bool* argument::set

Tracks whether the user supplied this argument.

If NULL, it is allocated implicitly when needed by schema features.

parse_callback

struct arg_callback(* argument::parse_callback) (const char *str, void *dest)

Function invoked during args_parse.

Use ARG_PARSER helpers for numeric parsing, or provide custom logic. Callbacks aren't limited to parsing e.g. –help exiting immediately.

Warning

str is NULL when argument::param_req is arg_parameter::ARG_PARAM_NONE.

dest ( argument::dest ) is NULL if you didn't initialize it.

Example:

static double mydouble;
ARG_PARSE_D(mydoubles, double, , val < 5.0,
            "Must be >= 5.0\n");
ARGUMENT(myarg) = {
    ...
    .dest = &mydouble,
    .parse_callback = parse_mydoubles,
    ...
};

You can also write custom parsers:

enum Color { COLOR_INVALID = -1, RED, GREEN, BLUE };
static enum Color color = COLOR_INVALID;
static struct arg_callback parse_color(const char *str, void *dest) {
    // Using 'color' directly is also possible in this example
    enum Color col = COLOR_INVALID;
    if (strcmp(str, "red") == 0)
        col = RED;
    else if (strcmp(str, "green") == 0)
        col = GREEN;
    else if (strcmp(str, "blue") == 0)
        col = BLUE;
    else
        return ARG_INVALID("Invalid color\n");
    *(enum Color *)dest = col;
    return ARG_VALID();
}
ARGUMENT(color) = {
    ...
    .dest = &color,
    .parse_callback = parse_color,
    ...
};

Parameters

str	User-provided value string.
dest	Alias of argument::dest, potentially NULL.

Return values

ARG_VALID	Callback accepted input.
ARG_INVALID	Callback rejected input.

validate_callback

struct arg_callback(* argument::validate_callback) (void)

Function invoked during args_validate.

Use for project-specific constraints after the parse stage.

Example:

enum Color { RED, GREEN, BLUE };
static enum Color color;
static bool other_option;
static struct arg_callback validate_color(void) {
    if (color == RED && other_option)
        return ARG_INVALID("Red color cannot be used.\n");
    return ARG_VALID();
}
ARGUMENT(color) = {
    ...
    .dest = &color,
    .validate_callback = validate_color,
    ...
};

Return values

ARG_VALID	Validation succeeded.
ARG_INVALID	Validation failed.

action_callback

void(* argument::action_callback) (void)

Function invoked during args_actions.

Intended for side effects such as applying runtime configuration.

Example:

static bool verbose;
static void print_verbose(void) {
    printf("Verbose mode is on\n");
}
ARGUMENT(verbose) = {
    ...
    .set = &verbose,
    .action_callback = print_verbose,
    .action_phase = ARG_CALLBACK_IF_SET,
    ...
};

arg_req

enum arg_requirement argument::arg_req

Specifies whether this argument is required, optional, or hidden.

See also

arg_requirement

param_req

enum arg_parameter argument::param_req

Specifies whether this argument takes a parameter and if it's required.

See also

arg_parameter

validate_phase

enum arg_callback_phase argument::validate_phase

Controls when argument::validate_callback runs.

See also

arg_callback_phase

action_phase

enum arg_callback_phase argument::action_phase

Controls when argument::action_callback runs.

See also

arg_callback_phase

validate_order

struct argument* argument::validate_order

Ordering for validation.

Use ARG_ORDER_FIRST or ARG_ORDER_AFTER, NULL means append at the end.

action_order

struct argument* argument::action_order

Ordering for action execution.

Use ARG_ORDER_FIRST or ARG_ORDER_AFTER, NULL means append at the end.

help_order

struct argument* argument::help_order

Ordering for help display.

Use ARG_ORDER_FIRST or ARG_ORDER_AFTER, NULL means append at the end.

help

const char* argument::help

Help description for this argument.

Multiline strings are supported (e.g. "Line1\nLine2").

See also

ARGS_STR_PREPAD

ARGS_PARAM_OFFSET

ARGS_HELP_OFFSET

param

const char* argument::param

Parameter name for help display (e.g., "N" for a number).

Invariant

Required when argument::param_req is not arg_parameter::ARG_PARAM_NONE.