bp_cmd Data Types

Developer reference for every type defined in src/lib/bp_args/bp_cmd.h — the unified command definition, parsing, and validation API.

bp_arg_type_t — Argument Type Enum

Specifies whether a flag/option takes an argument value.

typedef enum {
    BP_ARG_NONE = 0,
    BP_ARG_REQUIRED = 1,
    BP_ARG_OPTIONAL = 2
} bp_arg_type_t;
ValueMeaning
BP_ARG_NONEBoolean flag, no argument consumed
BP_ARG_REQUIREDFlag requires an argument value
BP_ARG_OPTIONALArgument value is optional

bp_val_type_t — Constraint Value Type Tag

Selects which union member is active inside a bp_val_constraint_t.

typedef enum {
    BP_VAL_NONE = 0,
    BP_VAL_UINT32,
    BP_VAL_INT32,
    BP_VAL_FLOAT,
    BP_VAL_CHOICE,
} bp_val_type_t;
ValueUnion memberDescription
BP_VAL_NONE—No constraint (skip validation)
BP_VAL_UINT32.uUnsigned 32-bit integer range
BP_VAL_INT32.iSigned 32-bit integer range
BP_VAL_FLOAT.fFloating-point range
BP_VAL_CHOICE.choiceNamed choice from a fixed set

bp_val_choice_t — Named Choice Entry

Maps a name string (and optional short alias) to an integer value. Used for command-line parsing and interactive numbered menus.

typedef struct {
    const char *name;
    const char *alias;
    uint32_t    label;
    uint32_t    value;
} bp_val_choice_t;
FieldTypeDescription
nameconst char *Full name for CLI match: "even", "odd", "none"
aliasconst char *Short alias: "e", "o", "n" (NULL = none)
labeluint32_tT_ translation key for interactive menu display
valueuint32_tActual stored value written to *out

bp_val_constraint_t — Value Constraint

Drives range checking, interactive prompting, and default values. Attach via pointer to a bp_command_opt_t or bp_command_positional_t. NULL pointer means no validation.

typedef struct {
    bp_val_type_t type;
    union {
        struct { uint32_t min, max, def; } u;
        struct { int32_t  min, max, def; } i;
        struct { float    min, max, def; } f;
        struct {
            const bp_val_choice_t *choices;
            uint32_t count;
            uint32_t def;
        } choice;
    };
    uint32_t prompt;
    uint32_t hint;
} bp_val_constraint_t;
FieldTypeDescription
typebp_val_type_tWhich union member is active
u.min, u.max, u.defuint32_tRange and default for BP_VAL_UINT32
i.min, i.max, i.defint32_tRange and default for BP_VAL_INT32
f.min, f.max, f.deffloatRange and default for BP_VAL_FLOAT
choice.choicesconst bp_val_choice_t *Array of named choices for BP_VAL_CHOICE
choice.countuint32_tNumber of choices
choice.defuint32_tDefault value (matches a choice .value)
promptuint32_tT_ translation key for interactive prompt text (0 = none)
hintuint32_tT_ translation key for hint text below prompt (0 = none)

bp_command_opt_t — Flag/Option Descriptor

Defines a single CLI flag for parsing, help display, and hinting. Arrays must be terminated with { 0 }.

typedef struct {
    const char *long_name;
    char        short_name;
    bp_arg_type_t arg_type;
    const char *arg_hint;
    uint32_t    description;
    const bp_val_constraint_t *constraint;
} bp_command_opt_t;
FieldTypeDescription
long_nameconst char *Long option name (without --), NULL if none
short_namecharShort option character, 0 if none
arg_typebp_arg_type_tBP_ARG_NONE / REQUIRED / OPTIONAL
arg_hintconst char *Value placeholder for help (bare word, auto-wrapped with <>/[]), NULL if flag-only
descriptionuint32_tT_ translation key for help text
constraintconst bp_val_constraint_t *Optional value constraint, NULL = no validation

bp_command_positional_t — Positional Argument Descriptor

Defines a non-flag argument. Order in the array matches position index (1-based in the API). Arrays must be terminated with { 0 }.

typedef struct {
    const char *name;
    const char *hint;
    uint32_t    description;
    bool        required;
    const bp_val_constraint_t *constraint;
} bp_command_positional_t;
FieldTypeDescription
nameconst char *Argument name for display: "bank", "voltage"
hintconst char *Value placeholder for hints (bare word, auto-wrapped), NULL = use name
descriptionuint32_tT_ translation key for help text
requiredbooltrue if argument is required
constraintconst bp_val_constraint_t *Optional value constraint, NULL = no validation

bp_command_action_t — Action/Subcommand Verb

Maps a verb string to an enum value with help text.

typedef struct {
    uint32_t    action;
    const char *verb;
    uint32_t    description;
} bp_command_action_t;
FieldTypeDescription
actionuint32_tAction enum value (start at 1; 0 = no action)
verbconst char *Verb string: "probe", "dump", etc.
descriptionuint32_tT_ translation key for help text

bp_action_delegate_t — Dynamic Verb Source

Used when a command’s verbs come from a runtime data structure (e.g. the modes[] array) instead of a static actions array.

typedef struct {
    const char *(*verb_at)(uint32_t index);
    bool (*match)(const char *tok, size_t len, uint32_t *action_out);
    const struct bp_command_def *(*def_for_verb)(uint32_t action);
} bp_action_delegate_t;
FieldTypeDescription
verb_atfunction pointerReturn verb string at index, NULL = end of list
matchfunction pointerCase-insensitive match of user token → action enum value
def_for_verbfunction pointerReturn sub-definition for resolved verb, NULL = none

bp_command_def_t — Complete Command Definition

One per command. Drives parsing, help, hints, and tab-completion. All pointers reference static const data — zero allocation.

typedef struct bp_command_def {
    const char *name;
    uint32_t    description;
    const bp_command_action_t *actions;
    uint32_t action_count;
    const bp_action_delegate_t *action_delegate;
    const bp_command_opt_t *opts;
    const bp_command_positional_t *positionals;
    uint32_t positional_count;
    const char *const *usage;
    uint32_t usage_count;
} bp_command_def_t;
FieldTypeDescription
nameconst char *Command name: "flash", "eeprom"
descriptionuint32_tT_ translation key for top-level help
actionsconst bp_command_action_t *Subcommand verbs, NULL if none
action_countuint32_tNumber of actions
action_delegateconst bp_action_delegate_t *Dynamic verb source, NULL = use actions array
optsconst bp_command_opt_t *Flags/options, { 0 }-terminated
positionalsconst bp_command_positional_t *Positional args, { 0 }-terminated, NULL if none
positional_countuint32_tNumber of positional args
usageconst char *const *Usage example strings
usage_countuint32_tNumber of usage lines

bp_cmd_status_t — Return Codes

Result status from constraint-aware argument fetch functions (bp_cmd_flag, bp_cmd_positional, bp_cmd_prompt).

typedef enum {
    BP_CMD_OK = 0,
    BP_CMD_MISSING,
    BP_CMD_INVALID,
    BP_CMD_EXIT,
} bp_cmd_status_t;
ValueMeaning
BP_CMD_OKValue obtained and valid
BP_CMD_MISSINGNot supplied on command line (default written if constraint exists)
BP_CMD_INVALIDSupplied but failed validation (error already printed)
BP_CMD_EXITUser exited interactive prompt

Sentinel Convention

Both bp_command_opt_t and bp_command_positional_t arrays must be terminated with a { 0 } sentinel entry. The parser walks the array until it hits a zero-initialized element.

static const bp_command_opt_t my_opts[] = {
    { "verbose", 'v', BP_ARG_NONE, NULL, T_HELP_VERBOSE },
    { "count",   'c', BP_ARG_REQUIRED, "n", T_HELP_COUNT, &count_range },
    { 0 },  // ← sentinel — always required
};

Lifetime Rules

All definition data must be static const (file-scope) or const with extern linkage. The bp_command_def_t and every array it points to must live for the entire program lifetime. The parser stores no copies — it reads pointers directly.

  • Constraints: static const bp_val_constraint_t next to the opt/positional tables
  • Option arrays: static const bp_command_opt_t[] in the .c file
  • Command def: const bp_command_def_t (non-static) if exported via header

Usage Examples

Global Command — dummy.c

From src/commands/global/dummy.c — a global command with actions, a boolean flag, a constrained integer flag, and a string flag:

static const bp_command_opt_t dummy_opts[] = {
    { "button",  'b', BP_ARG_NONE,     NULL,    T_HELP_DUMMY_B_FLAG },
    { "integer", 'i', BP_ARG_REQUIRED, "value", T_HELP_DUMMY_I_FLAG, &integer_range },
    { "file",    'f', BP_ARG_REQUIRED, "file",  T_HELP_DUMMY_FILE_FLAG },
    { 0 },
};

const bp_command_def_t dummy_def = {
    .name = "dummy",
    .description = 0x00,
    .actions = dummy_action_defs,
    .action_count = count_of(dummy_action_defs),
    .opts = dummy_opts,
    .usage = usage,
    .usage_count = count_of(usage),
};

Mode Setup — dummy1.c

From src/mode/dummy1.c — a mode setup definition with a uint32 range constraint and a named-choice constraint:

static const bp_val_constraint_t dummy1_speed_range = {
    .type = BP_VAL_UINT32,
    .u = { .min = 1, .max = 1000, .def = 100 },
    .prompt = 0,
    .hint = 0,
};

static const bp_val_choice_t dummy1_output_choices[] = {
    { "push-pull",  "pp", 0, 0 },
    { "open-drain", "od", 0, 1 },
};
static const bp_val_constraint_t dummy1_output_choice = {
    .type = BP_VAL_CHOICE,
    .choice = { .choices = dummy1_output_choices, .count = 2, .def = 0 },
    .prompt = 0,
};

static const bp_command_opt_t dummy1_setup_opts[] = {
    { "speed",  's', BP_ARG_REQUIRED, "1-1000",               0, &dummy1_speed_range },
    { "output", 'o', BP_ARG_REQUIRED, "push-pull/open-drain", 0, &dummy1_output_choice },
    { 0 },
};

const bp_command_def_t dummy1_setup_def = {
    .name = "dummy1",
    .description = 0,
    .opts = dummy1_setup_opts,
};