args.h: Core API

Overview

Argument creation and registration macros.

Use ARGUMENT to declare and register new arguments. Each argument is an instance of argument, which has fields for storage, callbacks, schema rules, and ordering controls that you can initialize.

Requirement And Visibility
enum	arg_requirement { ARG_OPTIONAL , ARG_REQUIRED , ARG_HIDDEN , ARG_SOMETIME }
	Requirement policy for argument::arg_req. More...

Parameter Modes
enum	arg_parameter { ARG_PARAM_NONE , ARG_PARAM_REQUIRED , ARG_PARAM_OPTIONAL }
	Parameter requirement for argument::param_req. More...

Callback Stages
bool	args_parse (int argc, char *argv[])
	Parses command line arguments and runs parse-phase relations.
bool	args_validate (void)
	Validates argument schema rules and user-provided combinations.
void	args_actions (void)
	Executes action callbacks for arguments matching action phase rules.

Creating New Arguments
#define	ARGUMENT(name)
	Creates and registers a new argument object.

Data Structures
struct	argument
	Declarative schema object for one CLI argument. More...

Macro Definition Documentation

ARGUMENT

#define ARGUMENT

(

name

)

Creates and registers a new argument object.

Use this macro at file scope. It declares argument _arg_<name>, wires constructor-based registration, then leaves a second declaration target for designated initialization.

Parameters

name	Unique argument identifier used in generated symbol names.

Precondition

The identifier is unique within the link unit.

Postcondition

The argument is linked into internal processing lists before main.

See also

ARG

ARG_DECLARE

ARG_EXTERN

Enumeration Type Documentation

arg_requirement

enum arg_requirement

Requirement policy for argument::arg_req.

Enumerator
ARG_OPTIONAL	User does not need to provide the argument.
ARG_REQUIRED	Argument must be present unless conflicted out.
ARG_HIDDEN	Optional and omitted from generated help output.
ARG_SOMETIME	Conditionally required, enforce via relations/callbacks.

arg_parameter

enum arg_parameter

Parameter requirement for argument::param_req.

Remarks

Semantics intentionally match common getopt usage.

Enumerator
ARG_PARAM_NONE	Argument is a flag, does not take a parameter.
ARG_PARAM_REQUIRED	argument::parse_callback receives non-NULL str.
ARG_PARAM_OPTIONAL	argument::parse_callback may receive NULL str.

Function Documentation

args_parse()

bool args_parse	(	int	argc,
		char *	argv[] )

Parses command line arguments and runs parse-phase relations.

For each user-provided option, the parser resolves the matching argument and calls argument::parse_callback when available. Parse-time dependency/conflict relations are enforced immediately. Duplicate-argument detection applies only when argument::set is non-NULL, though keep in mind it is implicitly allocated for most features.

Execution order

For each user-provided argument:

1. If argument takes a parameter and is already set, error for repeated argument
2. Run argument::parse_callback if it exists
3. Check dependency/conflict relations if arg_relation_phase is arg_relation_phase::ARG_RELATION_PARSE
4. Set argument::set to true (implicit allocation if needed)

Precondition

Every argument was declared via ARGUMENT and linked in.

Postcondition

All successfully processed arguments with non-NULL argument::set have *set == true.

Return values

true	Parse succeeded for all encountered options.
false	At least one user-facing parse error occurred.

See also

args_validate

args_validate()

bool args_validate

(

void

)

Validates argument schema rules and user-provided combinations.

This stage enforces required-argument rules, non-parse relation phases, and executes argument::validate_callback according to argument::validate_phase.

Validation checks

For each registered argument:

1. If arg_requirement::ARG_REQUIRED, check it was provided (unless conflicted out)
2. Check dependency/conflict relations if arg_relation_phase is not arg_relation_phase::ARG_RELATION_PARSE
3. Run argument::validate_callback if it exists using argument::validate_phase

Precondition

args_parse was called.

Postcondition

All validation callbacks due in this pass have executed.

Return values

true	All checks passed.
false	One or more constraints failed.

args_actions()

void args_actions

(

void

)

Executes action callbacks for arguments matching action phase rules.

Precondition

args_validate returned true.

Postcondition

All eligible argument::action_callback functions have run.