args.h: Relationships

Overview

Dependencies, conflicts, and subset propagation.

Relations model command schemas declaratively:

• dependency: argument requires others to be set
• conflict: argument requires others to be unset, overriding ARG_REQUIRED
• subset: setting an argument that lists subset arguments triggers them

Relation Evaluation Phases
enum	arg_relation_phase { ARG_RELATION_PARSE , ARG_RELATION_VALIDATE_ALWAYS , ARG_RELATION_VALIDATE_SET , ARG_RELATION_VALIDATE_UNSET }
	Relation evaluation phase used by ARG_DEPENDS and ARG_CONFLICTS. More...

Referencing Arguments
#define	ARG(name)
	Returns the address of argument object name.
#define	ARG_DECLARE(name)
	Forward declares an argument for same-file forward references.
#define	ARG_EXTERN(name)
	Extern declaration for an argument defined in another file.

Relation Declarations
#define	ARG_DEPENDS(relation_phase, ...)
	Declares dependency relations for an argument.
#define	ARG_CONFLICTS(relation_phase, ...)
	Declares conflict relations for an argument.
#define	ARG_SUBSETS(...)
	Declares subset arguments triggered by a parent argument.
#define	ARG_SUBSTRINGS(...)
	Supplies index-aligned custom strings for subset processing.
#define	ARG_SUBPASS
	Special marker meaning "forward parent string to subset parser".

Cross-File Execution Ordering
Deterministic ordering controls for help/validate/action lists.
#define	ARG_ORDER_FIRST
	Place argument first in the selected ordered list.
#define	ARG_ORDER_AFTER(arg)
	Place argument immediately after another argument.

Macro Definition Documentation

ARG

#define ARG

(

name

)

Returns the address of argument object name.

Parameters

name	Argument identifier used in ARGUMENT.

ARG_DECLARE

#define ARG_DECLARE

(

name

)

Forward declares an argument for same-file forward references.

Example:

ARG_DECLARE(foo);
ARGUMENT(bar) = {
    ...
    ARG_DEPENDS(ARG_RELATION_PARSE, ARG(foo)),
    ...
};
ARGUMENT(foo) = { ... };

Parameters

name	Argument identifier used in ARGUMENT.

ARG_EXTERN

#define ARG_EXTERN

(

name

)

Extern declaration for an argument defined in another file.

Example:

foo.c

ARGUMENT(foo) = { ... };

bar.c

ARG_EXTERN(foo);
ARGUMENT(bar) = {
    ...
    ARG_DEPENDS(ARG_RELATION_PARSE, ARG(foo)),
    ...
};

Parameters

name	Argument identifier used in ARGUMENT.

ARG_DEPENDS

#define ARG_DEPENDS	(		relation_phase,
			... )

Declares dependency relations for an argument.

When setting this argument, all dependencies must already be set. Use inside an ARGUMENT definition.

Example:

ARGUMENT(foo) = { ... };
ARGUMENT(bar) = { ... };
ARGUMENT(baz) = {
    ...
    ARG_DEPENDS(ARG_RELATION_PARSE, ARG(foo), ARG(bar)),
    ...
};

Parameters

relation_phase	When to check dependencies, see arg_relation_phase.
...	A list of ARG macros with ARGUMENT names.

ARG_CONFLICTS

#define ARG_CONFLICTS	(		relation_phase,
			... )

Declares conflict relations for an argument.

If a conflict argument is set, this one must not be set, overriding ARG_REQUIRED. Use inside an ARGUMENT definition.

Example:

ARGUMENT(foo) = { ... };
ARGUMENT(bar) = { ... };
ARGUMENT(baz) = {
    ...
    ARG_CONFLICTS(ARG_RELATION_PARSE, ARG(foo), ARG(bar)),
    ...
};

Parameters

relation_phase	When to check conflicts, see arg_relation_phase.
...	A list of ARG macros with ARGUMENT names.

ARG_SUBSETS

#define ARG_SUBSETS

(

...

)

Declares subset arguments triggered by a parent argument.

When this argument is set, all subsets are also processed. Parent string is passed to subset parsers unless customized with ARG_SUBSTRINGS. Use inside an ARGUMENT definition.

Example:

ARGUMENT(foo) = { ... };
ARGUMENT(bar) = { ... };
ARGUMENT(baz) = {
    ...
    ARG_SUBSETS(ARG(foo), ARG(bar)),
    ARG_SUBSTRINGS("out.txt", ARG_SUBPASS),
    ...
};

Parameters

...	A list of ARG macros with ARGUMENT names.

ARG_SUBSTRINGS

#define ARG_SUBSTRINGS

(

...

)

Supplies index-aligned custom strings for subset processing.

Use ARG_SUBPASS to pass parent string, omit entirely if not needed.

Parameters

...	A list of strings or ARG_SUBPASS.

ARG_SUBPASS

#define ARG_SUBPASS

Special marker meaning "forward parent string to subset parser".

Use in ARG_SUBSTRINGS to indicate that the parent argument's string should be passed to the subset parser instead of a custom string.

ARG_ORDER_FIRST

#define ARG_ORDER_FIRST

Place argument first in the selected ordered list.

Value for argument::validate_order, argument::action_order, or argument::help_order.

ARG_ORDER_AFTER

#define ARG_ORDER_AFTER

(

arg

)

Place argument immediately after another argument.

Value for argument::validate_order, argument::action_order, or argument::help_order. Use ARG_DECLARE or ARG_EXTERN to forward-declare the referenced argument.

Example:

ARG_DECLARE(foo);
ARGUMENT(bar) = {
    ...
    .validate_order = ARG_ORDER_AFTER(ARG(foo)),
    ...
};

Parameters

arg	Argument supplied using the ARG macro.

Enumeration Type Documentation

arg_relation_phase

enum arg_relation_phase

Relation evaluation phase used by ARG_DEPENDS and ARG_CONFLICTS.

Enumerator
ARG_RELATION_PARSE	Parse-time checks, effectively no-op when unset.
ARG_RELATION_VALIDATE_ALWAYS	Validate-time checks regardless of argument state.
ARG_RELATION_VALIDATE_SET	Validate-time checks only when the argument is set.
ARG_RELATION_VALIDATE_UNSET	Validate-time checks only when the argument is not set.