Argument Parsing

Data Structures
struct	bj_cli_argument
struct	bj_cli

Typedefs
typedef bj_bool(*	bj_cli_action_fn) (const struct bj_cli *parser, const struct bj_cli_argument *arg, const char *value, void *dest, struct bj_error **error)

Functions
bj_bool	bj_parse_cli (struct bj_cli *parser, int argc, char *argv[], struct bj_error **error)
bj_bool	bj_validate_cli (const struct bj_cli *parser, struct bj_error **error)
void	bj_print_cli_help (const struct bj_cli *parser)
size_t	bj_get_cli_help_string (const struct bj_cli *parser, char *buffer, size_t buffer_size)
bj_bool	bj_store_cli_cstring (const struct bj_cli *parser, const struct bj_cli_argument *arg, const char *value, void *dest, struct bj_error **error)
bj_bool	bj_store_cli_double (const struct bj_cli *parser, const struct bj_cli_argument *arg, const char *value, void *dest, struct bj_error **error)
bj_bool	bj_store_cli_int (const struct bj_cli *parser, const struct bj_cli_argument *arg, const char *value, void *dest, struct bj_error **error)
bj_bool	bj_store_cli_uint (const struct bj_cli *parser, const struct bj_cli_argument *arg, const char *value, void *dest, struct bj_error **error)
bj_bool	bj_store_cli_bool (const struct bj_cli *parser, const struct bj_cli_argument *arg, const char *value, void *dest, struct bj_error **error)
bj_bool	bj_print_cli_help_action (const struct bj_cli *parser, const struct bj_cli_argument *arg, const char *value, void *dest, struct bj_error **error)

Detailed Description

Parse argc/argv into named options and positional values.

Every C program that runs from a shell starts with int main(int argc, char* argv[]). Banjo's CLI subsystem helps you turn that pair into something useful: the user runs myprog --port 8080 -v input.txt, and you get a structured view (port = 8080, verbose = true, input file = "input.txt") without having to walk argv by hand or write a parser.

You describe your program's accepted arguments (one bj_cli_argument per option or positional), pass them and argc/argv to bj_parse_cli, and you're done. --help is generated for you from the descriptions.

What it understands

• Short options (one dash, one letter): -f, -v, -o.
• Long options (two dashes, a word): --file, --verbose, --output.
• Values attached to options: -finput.txt and -f input.txt both work; --file=input.txt and --file input.txt both work.
• Type conversion done for you: declare an option as int / unsigned / double / bool / string, and the parser converts the value and stores it where you tell it to.
• Flag options that don't take a value, just toggle a bool.
• Chained short options: -abc is -a -b -c, the GNU convention.
• Positional arguments: anything without a leading dash, either required or optional.
• Auto-generated --help: the parser prints a usage summary built from your argument descriptions.

Properties

• Zero heap allocation in the success path. The parser writes parsed values straight into the storage locations you pointed it at; nothing is malloc'd.
• Small implementation: it's a finite-state machine, small enough to embed in tools where binary size matters.

---

Data Structure Documentation

bj_cli_argument

struct bj_cli_argument

Descriptor for a single command line argument.

Defines how an argument is parsed and stored by bj_parse_cli.

Most arguments will set .dest and either .name (long option) or .shortname (short option).

int verbose = 0;
 
struct bj_cli parser = {
    .arguments_len = 1,
    .arguments     = (struct bj_cli_argument[]) {
        {.shortname = 'v', .name = "verbose", .help = "verbose mode", .dest = &verbose},
    },
};
 
struct bj_error* error = NULL;
bj_parse_cli(&parser, argc, argv, &error);
 
if (verbose) {
    bj_info("Verbose Mode");
}

Named arguments

Named arguments have .name (e.g., --file) or .shortname (e.g., -f). They can appear anywhere in the command line, multiple times, and are optional unless .required is set.

If the argument expects a value, .action and .dest must be set. The .action callback validates, converts, and stores the value.

Flags

Flags are named arguments with no value expected. To create a flag, set .dest but leave .action as 0.

The integer pointed by .dest is set to 1 when the flag is present.

Positional arguments

Positional arguments have no .name or .shortname. They are identified by their order relative to other positional arguments.

They can be declared anywhere in the argument list, mixed with named args.

Example:

struct bj_cli parser = {
    .arguments_len = 4,
    .arguments     = (struct bj_cli_argument[]) {
        {.shortname = 'f', .name = "format", .help = "output format",
         .dest = &format, .action = bj_store_cli_cstring},
        {.help = "input file", .dest = &input, .action = bj_store_cli_cstring},
        {.shortname = 'v', .name = "verbose", .help = "verbose mode", .dest = &verbose},
        {.help = "output file", .dest = &output, .action = bj_store_cli_cstring},
    },
};

Examples

banjo-info.c, and cli.c.

Definition at line 151 of file cli.h.

Collaboration diagram for bj_cli_argument:

Data Fields
bj_cli_action_fn	action	Callback to parse/store argument value. If 0, .dest is set as int flag.
void *	dest	Pointer to store parsed value. If 0, program exits after argument is found (e.g., --help).
const char *	help	Help message shown in usage output. Can be 0 if no help needed.
const char *	metavar	Placeholder for argument value in help output. Must not be 0 for flag arguments.
const char *	name	Long option name (e.g., "file" for --file). Can be 0 if positional or only shortname used.
int	required	Set to 1 if positional argument is mandatory.
char	shortname	Short option name (e.g., 'o' for -o). Can be 0 if positional or only long name used.

bj_cli

struct bj_cli

Parser context and argument list descriptor.

Contains global parser settings, program info, and list of argument descriptors.

Examples

banjo-info.c, and cli.c.

Definition at line 173 of file cli.h.

Collaboration diagram for bj_cli:

Data Fields
struct bj_cli_argument *	arguments	Pointer to array of argument descriptors.
size_t	arguments_len	Number of arguments in the parser.
const char *	description	Description text displayed before argument list.
const char *	epilog	Text displayed after argument list.
const char *	prog	Program name; if 0, argv[0] is used.

Typedef Documentation

bj_cli_action_fn

typedef bj_bool(* bj_cli_action_fn) (const struct bj_cli *parser, const struct bj_cli_argument *arg, const char *value, void *dest, struct bj_error **error)

Callback function prototype for argument value processing.

Set in each bj_cli_argument to parse, validate and store the argument's string value extracted from argv.

Predefined callbacks include:

• bj_store_cli_cstring
• bj_store_cli_double
• bj_store_cli_int
• bj_store_cli_uint
• bj_store_cli_bool
• bj_print_cli_help_action

Parameters

parser	Pointer to the bj_cli instance
arg	Pointer to the argument descriptor
value	Argument string value from argv
dest	Pointer to storage location
error	Error output location (may be NULL to ignore errors)

Returns

BJ_TRUE on success, BJ_FALSE on error

Definition at line 80 of file cli.h.

Function Documentation

bj_get_cli_help_string()

size_t bj_get_cli_help_string	(	const struct bj_cli *	parser,
		char *	buffer,
		size_t	buffer_size )

Get help message as a string for custom output.

Generates formatted help text into the provided buffer.

This function can be called with buffer set to NULL and buffer_size set to 0, in which case it returns the required buffer size without writing anything.

Parameters

parser	Pointer to the argument parser configuration.
buffer	Buffer to write help text to (may be NULL).
buffer_size	Size of buffer in bytes.

Returns

Number of bytes written (excluding null terminator), or required size if buffer is NULL.

See also

bj_print_cli_help

bj_parse_cli()

bj_bool bj_parse_cli	(	struct bj_cli *	parser,
		int	argc,
		char *	argv[],
		struct bj_error **	error )

Parse command-line arguments according to parser configuration.

Parses the provided argument vector (argv) according to the argument descriptors in parser, storing results in the destinations specified by each argument.

This function validates the parser configuration, processes all arguments, and reports any errors through the error system.

Parameters

parser	Pointer to the argument parser configuration.
argc	Argument count (typically from main).
argv	Argument vector (typically from main).
error	Error output location (may be NULL to ignore errors).

Returns

BJ_TRUE on success, BJ_FALSE if parsing failed or configuration invalid.

Error Codes

• BJ_ERROR_INVALID_DATA: Parser configuration error (duplicate names, etc.)
• BJ_ERROR_INCORRECT_VALUE: Invalid argument value provided
• BJ_ERROR: General parsing error (missing required args, unknown options, etc.)

Zero-Heap Design

This function does not allocate heap memory during normal operation. Memory allocation only occurs if an error is reported (for error object).

See also

bj_validate_cli, bj_print_cli_help

Examples

banjo-info.c, and cli.c.

Referenced by main().

bj_print_cli_help()

void bj_print_cli_help

(

const struct bj_cli *

parser

)

Print help message using Banjo's logging system.

Generates and prints formatted help text showing program description, usage syntax, and all argument descriptions using bj_info().

Parameters

parser

Pointer to the argument parser configuration.

See also

bj_get_cli_help_string

Examples

banjo-info.c, and cli.c.

Referenced by main().

bj_print_cli_help_action()

bj_bool bj_print_cli_help_action	(	const struct bj_cli *	parser,
		const struct bj_cli_argument *	arg,
		const char *	value,
		void *	dest,
		struct bj_error **	error )

Print help argument action.

Special action function to trigger printing help and exiting. Use this as the .action for a --help argument.

Parameters

parser	Parser instance.
arg	Argument descriptor.
value	Argument string (usually NULL).
dest	Destination (if 0, program exits after printing help).
error	Error output location.

Returns

BJ_TRUE always.

Examples

banjo-info.c, and cli.c.

Referenced by main().

bj_store_cli_bool()

bj_bool bj_store_cli_bool	(	const struct bj_cli *	parser,
		const struct bj_cli_argument *	arg,
		const char *	value,
		void *	dest,
		struct bj_error **	error )

Store boolean argument value.

Accepts true, false, 1, 0, yes, no (case-insensitive).

Parameters

parser	Parser instance.
arg	Argument descriptor.
value	String representation of bool value.
dest	Destination pointer (int*).
error	Error output location.

Returns

BJ_TRUE on success, BJ_FALSE on error.

Error Codes

• BJ_ERROR_INCORRECT_VALUE: Invalid boolean value

Examples

cli.c.

Referenced by main().

bj_store_cli_cstring()

bj_bool bj_store_cli_cstring	(	const struct bj_cli *	parser,
		const struct bj_cli_argument *	arg,
		const char *	value,
		void *	dest,
		struct bj_error **	error )

Store string argument value.

Stores value as a null-terminated string pointer. The pointer is stored directly (no copy is made).

Parameters

parser	Parser instance.
arg	Argument descriptor.
value	C-string value.
dest	Destination pointer (const char**).
error	Error output location.

Returns

BJ_TRUE on success, BJ_FALSE on error.

Examples

cli.c.

Referenced by main().

bj_store_cli_double()

bj_bool bj_store_cli_double	(	const struct bj_cli *	parser,
		const struct bj_cli_argument *	arg,
		const char *	value,
		void *	dest,
		struct bj_error **	error )

Store double argument value.

Parses and stores a double floating point value.

Parameters

parser	Parser instance.
arg	Argument descriptor.
value	String representation of float value.
dest	Destination pointer (double*).
error	Error output location.

Returns

BJ_TRUE on success, BJ_FALSE on error.

Error Codes

• BJ_ERROR_INCORRECT_VALUE: Invalid or out-of-range value

Examples

cli.c.

Referenced by main().

bj_store_cli_int()

bj_bool bj_store_cli_int	(	const struct bj_cli *	parser,
		const struct bj_cli_argument *	arg,
		const char *	value,
		void *	dest,
		struct bj_error **	error )

Store int argument value.

Parses and stores a signed integer value.

Parameters

parser	Parser instance.
arg	Argument descriptor.
value	String representation of int value.
dest	Destination pointer (int*).
error	Error output location.

Returns

BJ_TRUE on success, BJ_FALSE on error.

Error Codes

• BJ_ERROR_INCORRECT_VALUE: Invalid or out-of-range value

Examples

cli.c.

Referenced by main().

bj_store_cli_uint()

bj_bool bj_store_cli_uint	(	const struct bj_cli *	parser,
		const struct bj_cli_argument *	arg,
		const char *	value,
		void *	dest,
		struct bj_error **	error )

Store unsigned int argument value.

Parses and stores an unsigned integer value.

Parameters

parser	Parser instance.
arg	Argument descriptor.
value	String representation of unsigned int value.
dest	Destination pointer (unsigned int*).
error	Error output location.

Returns

BJ_TRUE on success, BJ_FALSE on error.

Error Codes

• BJ_ERROR_INCORRECT_VALUE: Invalid or out-of-range value

bj_validate_cli()

bj_bool bj_validate_cli	(	const struct bj_cli *	parser,
		struct bj_error **	error )

Check for configuration errors in the parser.

Ensures no conflicts or inconsistencies in argument definitions. Reports configuration errors such as:

• Duplicate argument names or shortnames
• Invalid characters in names
• Conflicting dest pointers
• Invalid metavar usage

Parameters

parser	Pointer to the argument parser configuration.
error	Error output location (may be NULL to ignore errors).

Returns

BJ_TRUE if configuration is valid, BJ_FALSE if errors found.

Error Codes

• BJ_ERROR_INVALID_DATA: Parser configuration has errors