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_cli_parse (struct bj_cli *parser, int argc, char *argv[], struct bj_error **error)
bj_bool	bj_cli_validate (const struct bj_cli *parser, struct bj_error **error)
void	bj_cli_print_help (const struct bj_cli *parser)
size_t	bj_cli_get_help_string (const struct bj_cli *parser, char *buffer, size_t buffer_size)
bj_bool	bj_cli_store_cstring (const struct bj_cli *parser, const struct bj_cli_argument *arg, const char *value, void *dest, struct bj_error **error)
bj_bool	bj_cli_store_double (const struct bj_cli *parser, const struct bj_cli_argument *arg, const char *value, void *dest, struct bj_error **error)
bj_bool	bj_cli_store_int (const struct bj_cli *parser, const struct bj_cli_argument *arg, const char *value, void *dest, struct bj_error **error)
bj_bool	bj_cli_store_uint (const struct bj_cli *parser, const struct bj_cli_argument *arg, const char *value, void *dest, struct bj_error **error)
bj_bool	bj_cli_store_bool (const struct bj_cli *parser, const struct bj_cli_argument *arg, const char *value, void *dest, struct bj_error **error)
bj_bool	bj_cli_print_help_action (const struct bj_cli *parser, const struct bj_cli_argument *arg, const char *value, void *dest, struct bj_error **error)

Detailed Description

Command-line argument parsing utilities.

This module provides a robust, lightweight command-line argument parser supporting short/long options, flags, positional arguments, chained flags, and automatic help generation.

Features

• Short options (e.g., -f) and long options (e.g., --file)
• Positional arguments with required/optional flags
• Value arguments with type validation (int, uint, double, bool, string)
• Flag arguments (boolean switches)
• Chained short options (e.g., -abc == -a -b -c)
• Multiple value syntaxes:
  • -finput.txt and -f input.txt for short options
  • --file=input.txt and --file input.txt for long options
• Automatic help generation
• Zero-heap-allocation design (except on error)
• FSM-based parser for stability and low memory footprint

Usage involves defining a bj_cli instance and calling bj_cli_parse.

Each argument is described by a bj_cli_argument, defining parsing and storage behavior.

By default, the parser does not allocate heap memory.

---

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_cli_parse.

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_cli_parse(&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_cli_store_cstring},
        {.help = "input file", .dest = &input, .action = bj_cli_store_cstring},
        {.shortname = 'v', .name = "verbose", .help = "verbose mode", .dest = &verbose},
        {.help = "output file", .dest = &output, .action = bj_cli_store_cstring},
    },
};

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.

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_cli_store_cstring
• bj_cli_store_double
• bj_cli_store_int
• bj_cli_store_uint
• bj_cli_store_bool
• bj_cli_print_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

Function Documentation

bj_cli_get_help_string()

size_t bj_cli_get_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_cli_print_help

bj_cli_parse()

bj_bool bj_cli_parse	(	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_cli_validate, bj_cli_print_help

bj_cli_print_help()

void bj_cli_print_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_cli_get_help_string

bj_cli_print_help_action()

bj_bool bj_cli_print_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.

bj_cli_store_bool()

bj_bool bj_cli_store_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

bj_cli_store_cstring()

bj_bool bj_cli_store_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.

bj_cli_store_double()

bj_bool bj_cli_store_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

bj_cli_store_int()

bj_bool bj_cli_store_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

bj_cli_store_uint()

bj_bool bj_cli_store_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_cli_validate()

bj_bool bj_cli_validate	(	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