mdl_cli.c File Reference

Implementation of the mdl command-line parser. More...

#include "mdl_cli.h"
#include <stdlib.h>
#include <string.h>
#include "mdl_cli_internal.h"
#include "ra8_attributes.h"

Include dependency graph for mdl_cli.c:

Go to the source code of this file.

Enumerations
enum	mdl_cli_run_parse_t : uint8_t { k_cli_dec_base = 10 }
	Radix used when materializing the validated response-size option. More...
enum	mdl_cli_cap_t : uint64_t { k_max_response_bytes_def = 64ULL * 1024ULL * 1024ULL }
	Default per-response size cap: bound a hostile/broken stream. More...
enum	mdl_cli_arg_bit_t : uint64_t {   k_arg_cfg = 1ULL << 0U ,   k_arg_series = 1ULL << 1U ,   k_arg_page = 1ULL << 2U ,   k_arg_out = 1ULL << 3U ,   k_arg_attr = 1ULL << 4U ,   k_arg_chapters = 1ULL << 5U ,   k_arg_from = 1ULL << 6U ,   k_arg_max = 1ULL << 7U ,   k_arg_seed = 1ULL << 8U ,   k_arg_timeout = 1ULL << 9U ,   k_arg_format = 1ULL << 10U ,   k_arg_pack = 1ULL << 11U ,   k_arg_contact = 1ULL << 12U ,   k_arg_max_bytes = 1ULL << 13U ,   k_arg_remove = 1ULL << 14U ,   k_arg_search = 1ULL << 15U ,   k_arg_pick = 1ULL << 16U ,   k_arg_proxy = 1ULL << 17U ,   k_arg_socks5 = 1ULL << 18U ,   k_arg_cookie = 1ULL << 19U ,   k_arg_verify_dir = 1ULL << 20U ,   k_arg_init = 1ULL << 21U ,   k_arg_browse = 1ULL << 22U ,   k_arg_separate = 1ULL << 23U ,   k_arg_update = 1ULL << 24U ,   k_arg_list = 1ULL << 25U ,   k_arg_update_all = 1ULL << 26U ,   k_arg_polite = 1ULL << 27U ,   k_arg_ignore_robots = 1ULL << 28U ,   k_arg_allow_private = 1ULL << 29U ,   k_arg_cross_host = 1ULL << 30U ,   k_arg_allow_incomplete = 1ULL << 31U ,   k_arg_progress = 1ULL << 32U ,   k_arg_refetch = 1ULL << 33U ,   k_arg_verify = 1ULL << 34U ,   k_arg_help = 1ULL << 35U ,   k_arg_version = 1ULL << 36U ,   k_arg_ca_file = 1ULL << 37U ,   k_arg_cache_dir = 1ULL << 38U }
	Bit positions for every CLI spelling, used by mode allowlists. More...

Functions
static bool	internal_is_option_value (const char *flag, const char *value)
	Decide whether one token is a value for the matched option.
static bool	internal_take_opt (char **argv, int argc, int *i, const char *flag, const char **dst, bool *bad)
	Consume one value-bearing option at the current argument.
static bool	internal_take_flag (const char *arg, const char *flag, bool *dst, bool *bad)
	Consume one bare Boolean option.
static bool	internal_parse_bool_flags (const char *arg, mdl_args_t *a)
	Consume any recognised boolean flag at arg.
static bool	internal_parse_verify_opt (int argc, char **argv, int *i, mdl_args_t *a)
	Consume the optional --verify DIR argument pair.
static bool	internal_parse_value_opt (int argc, char **argv, int *i, mdl_args_t *a)
	Consume one recognized option that requires a value.
static void	internal_parse_positional_or_bad (const char *arg, mdl_args_t *a)
	Record a positional URL or reject an unexpected token.
void	mdl_cli_parse (int argc, char **argv, mdl_args_t *a)
	Parse argv into a; numeric fields stay as strings for main.
static uint64_t	internal_value_bit (const void *value, uint64_t bit)
	Convert pointer presence to an option-mask bit.
static uint64_t	internal_flag_bit (bool value, uint64_t bit)
	Convert a Boolean option to an option-mask bit.
static uint64_t	internal_args_mask (const mdl_args_t *a)
	Convert populated CLI fields into one presence mask.
const char *	mdl_cli_mode_name (mdl_cli_mode_t mode)
	Stable human-readable command mode name.
static ra8_err_t	internal_cli_invalid (ra8_io_stream_t *diagnostic, const char *message)
	Emit one CLI validation diagnostic and return canonical rejection.
static void	internal_record_mode (bool condition, mdl_cli_mode_t candidate, mdl_cli_mode_t *mode, size_t *count)
	Record one selected primary CLI mode.
static bool	internal_cli_ends_ci (const char *text, const char *suffix)
	Test an ASCII suffix without case sensitivity.
static bool	internal_cli_artifact_url (const char *url)
	Recognise an artifact suffix in a URL path.
static mdl_cli_mode_t	internal_resolve_mode (const mdl_args_t *a, size_t *count)
	Resolve primary-mode fields and count their selections.
static const char *	internal_option_name (uint64_t bit)
static bool	internal_cli_allowed_args (const mdl_args_t *a, mdl_cli_mode_t selected, uint64_t *allowed)
	Compute the option mask allowed by one selected mode.
static ra8_err_t	internal_validate_allowed_args (const mdl_args_t *a, ra8_io_stream_t *diagnostic, mdl_cli_mode_t selected)
	Reject option bits that are incompatible with the selected mode.
static ra8_err_t	internal_validate_mode_fields (const mdl_args_t *a, ra8_io_stream_t *diagnostic, mdl_cli_mode_t selected)
	Validate required and mutually exclusive fields for one mode.
static ra8_err_t	internal_validate_network_args (const mdl_args_t *a, ra8_io_stream_t *diagnostic)
	Validate mutually exclusive and required network-policy arguments.
ra8_err_t	mdl_cli_validate (const mdl_args_t *a, ra8_io_stream_t *diagnostic, mdl_cli_mode_t *mode)
	Validate mode selection, required arguments, and per-mode options.
mdl_run_opts_t	mdl_cli_run_opts (const mdl_args_t *a)
	Fold parsed args into the cross-cutting run options.

Detailed Description

Implementation of the mdl command-line parser.

Parses bounded option state and emits validation diagnostics through the injected CLI stream without performing application work.

Copyright

Copyright (c) 2026 Brighton Sikarskie SPDX-License-Identifier: MIT

Definition in file mdl_cli.c.

Enumeration Type Documentation

mdl_cli_arg_bit_t

enum mdl_cli_arg_bit_t : uint64_t

Bit positions for every CLI spelling, used by mode allowlists.

Enumerator
k_arg_cfg	--config.
k_arg_series	--series.
k_arg_page	Positional URL.
k_arg_out	--out.
k_arg_attr	--attr.
k_arg_chapters	--chapters.
k_arg_from	--from.
k_arg_max	--max.
k_arg_seed	--seed.
k_arg_timeout	--timeout.
k_arg_format	--format.
k_arg_pack	--pack.
k_arg_contact	--contact.
k_arg_max_bytes	--max-bytes.
k_arg_remove	--remove.
k_arg_search	--search.
k_arg_pick	--pick.
k_arg_proxy	--proxy.
k_arg_socks5	--socks5.
k_arg_cookie	--cookie-file.
k_arg_verify_dir	Optional verify dir.
k_arg_init	--init-site.
k_arg_browse	--browse.
k_arg_separate	--separate.
k_arg_update	--update.
k_arg_list	--list.
k_arg_update_all	--update-all.
k_arg_polite	--polite.
k_arg_ignore_robots	--ignore-robots.
k_arg_allow_private	--allow-private.
k_arg_cross_host	--cross-host.
k_arg_allow_incomplete	--allow-incomplete.
k_arg_progress	--progress.
k_arg_refetch	--refetch.
k_arg_verify	--verify.
k_arg_help	--help.
k_arg_version	--version.
k_arg_ca_file	--ca-file.
k_arg_cache_dir	--cache-dir.

Definition at line 290 of file mdl_cli.c.

mdl_cli_cap_t

enum mdl_cli_cap_t : uint64_t

Default per-response size cap: bound a hostile/broken stream.

Enumerator
k_max_response_bytes_def	64 MiB per response.

Definition at line 23 of file mdl_cli.c.

mdl_cli_run_parse_t

enum mdl_cli_run_parse_t : uint8_t

Radix used when materializing the validated response-size option.

Enumerator
k_cli_dec_base	Decimal conversion radix.

Definition at line 18 of file mdl_cli.c.

Function Documentation

internal_args_mask()

uint64_t internal_args_mask ( const mdl_args_t * a )

static

Convert populated CLI fields into one presence mask.

Maps every pointer and Boolean option to its named allowlist bit.

Parameters

[in]

a

Parsed CLI arguments.

Returns

Bitwise union of all present options.

Return values

0	No tracked option is populated.

Precondition

a is non-NULL.

Pointer fields in a are NULL or borrowed NUL-terminated arguments.

Postcondition

a is unchanged.

Every set result bit corresponds to one populated field in a.

Note

Thread-safe: reads only caller storage.

Since

0.1.0

Definition at line 383 of file mdl_cli.c.

References mdl_args_t::allow_incomplete, mdl_args_t::allow_private, mdl_args_t::attr, mdl_args_t::browse, mdl_args_t::ca_file, mdl_args_t::cache_dir, mdl_args_t::cfg, mdl_args_t::chapters, mdl_args_t::contact, mdl_args_t::cookie_file, mdl_args_t::cross_host, mdl_args_t::format, mdl_args_t::from, mdl_args_t::help, mdl_args_t::ignore_robots, mdl_args_t::init_site_url, internal_flag_bit(), internal_value_bit(), k_arg_allow_incomplete, k_arg_allow_private, k_arg_attr, k_arg_browse, k_arg_ca_file, k_arg_cache_dir, k_arg_cfg, k_arg_chapters, k_arg_contact, k_arg_cookie, k_arg_cross_host, k_arg_format, k_arg_from, k_arg_help, k_arg_ignore_robots, k_arg_init, k_arg_list, k_arg_max, k_arg_max_bytes, k_arg_out, k_arg_pack, k_arg_page, k_arg_pick, k_arg_polite, k_arg_progress, k_arg_proxy, k_arg_refetch, k_arg_remove, k_arg_search, k_arg_seed, k_arg_separate, k_arg_series, k_arg_socks5, k_arg_timeout, k_arg_update, k_arg_update_all, k_arg_verify, k_arg_verify_dir, k_arg_version, mdl_args_t::list, mdl_args_t::max, mdl_args_t::max_bytes, mdl_args_t::out, mdl_args_t::pack, mdl_args_t::page_url, mdl_args_t::pick, mdl_args_t::polite, mdl_args_t::progress, mdl_args_t::proxy, RA8_INTERNAL, mdl_args_t::refetch, mdl_args_t::remove_series, mdl_args_t::seed, mdl_args_t::separate, mdl_args_t::series, mdl_args_t::socks5, mdl_args_t::timeout, mdl_args_t::update, mdl_args_t::update_all, mdl_args_t::verify, mdl_args_t::verify_dir, and mdl_args_t::version.

Referenced by internal_validate_allowed_args().

internal_cli_allowed_args()

bool internal_cli_allowed_args ( const mdl_args_t * a, mdl_cli_mode_t selected, uint64_t * allowed )

static

Compute the option mask allowed by one selected mode.

Resolves mode-specific variants such as series configuration versus direct URL use and returns the exact compatible option-bit mask.

Parameters

[in]	a	Parsed argument state used to resolve mode variants.
[in]	selected	Primary mode selected by exclusivity validation.
[out]	allowed	Receives the exact option-bit mask for selected.

Returns

Whether selected has a valid option-mask definition.

Return values

true	allowed was initialized with the selected mode's mask.
false	The mode or its required variant was invalid.

Precondition

a and allowed are non-NULL.

selected is a single mdl_cli_mode_t value.

Postcondition

Success initializes allowed exactly once.

Failure does not grant any unvalidated option.

Note

Pure mask construction; no argument pointer ownership is transferred.

Since

0.1.0

Definition at line 660 of file mdl_cli.c.

References k_arg_allow_incomplete, k_arg_allow_private, k_arg_attr, k_arg_browse, k_arg_ca_file, k_arg_cache_dir, k_arg_cfg, k_arg_chapters, k_arg_contact, k_arg_cookie, k_arg_cross_host, k_arg_format, k_arg_from, k_arg_help, k_arg_ignore_robots, k_arg_init, k_arg_list, k_arg_max, k_arg_max_bytes, k_arg_out, k_arg_pack, k_arg_page, k_arg_pick, k_arg_polite, k_arg_progress, k_arg_proxy, k_arg_refetch, k_arg_remove, k_arg_search, k_arg_seed, k_arg_separate, k_arg_series, k_arg_socks5, k_arg_timeout, k_arg_update, k_arg_update_all, k_arg_verify, k_arg_verify_dir, k_arg_version, k_mdl_cli_mode_artifact, k_mdl_cli_mode_browse, k_mdl_cli_mode_help, k_mdl_cli_mode_init_site, k_mdl_cli_mode_list, k_mdl_cli_mode_pack, k_mdl_cli_mode_page, k_mdl_cli_mode_remove, k_mdl_cli_mode_search, k_mdl_cli_mode_series, k_mdl_cli_mode_update_all, k_mdl_cli_mode_verify, k_mdl_cli_mode_version, and mdl_args_t::pick.

Referenced by internal_validate_allowed_args().

internal_cli_artifact_url()

bool internal_cli_artifact_url ( const char * url )

static

Recognise an artifact suffix in a URL path.

Removes query/fragment text, bounds the path locally, and checks the configured archive/book suffix allowlist case-insensitively.

Parameters

[in]

url

Candidate URL, or NULL.

Returns

Whether the URL path names a known artifact suffix.

Return values

true	One allowlisted suffix matched.
false	The URL is NULL, empty/overlong, or has no known suffix.

Precondition

A non-NULL url is NUL-terminated.

url remains valid for the call duration.

Postcondition

url is unchanged.

No filesystem or network state is accessed.

Note

Thread-safe: uses only automatic and immutable storage.

Since

0.1.0

Definition at line 533 of file mdl_cli.c.

References internal_cli_ends_ci(), memcpy(), and RA8_INTERNAL.

Referenced by internal_resolve_mode().

internal_cli_ends_ci()

bool internal_cli_ends_ci ( const char * text, const char * suffix )

static

Test an ASCII suffix without case sensitivity.

Compares only the candidate suffix bytes and performs no filesystem access or locale-dependent conversion.

Parameters

[in]	text	NUL-terminated candidate string.
[in]	suffix	NUL-terminated suffix.

Returns

Whether text ends with suffix under ASCII folding.

Return values

true	Every suffix byte matches.
false	The suffix is longer or at least one byte differs.

Precondition

text and suffix are non-NULL.

Both inputs are NUL-terminated.

Postcondition

Both inputs are unchanged.

No filesystem or locale state is accessed.

Note

Thread-safe: reads only caller storage.

Since

0.1.0

Definition at line 495 of file mdl_cli.c.

References RA8_INTERNAL, and strlen().

Referenced by internal_cli_artifact_url().

internal_cli_invalid()

ra8_err_t internal_cli_invalid ( ra8_io_stream_t * diagnostic, const char * message )

static

Emit one CLI validation diagnostic and return canonical rejection.

Centralises the failure convention while preserving stream errors.

Parameters

[in,out]	diagnostic	Bound diagnostic stream.
[in]	message	Human-readable error text.

Returns

Invalid-argument after a complete write, or the stream failure.

Return values

k_ra8_err_invalid_arg	The complete diagnostic was accepted.
other	The stream rejected a fragment.

Precondition

diagnostic and message are non-NULL.

message is NUL-terminated.

Postcondition

One newline-terminated diagnostic is attempted on diagnostic.

No parsed argument state is modified.

Note

Thread-safe across distinct streams.

Since

0.1.0

Definition at line 449 of file mdl_cli.c.

References priv_mdl_cli_reject_parts(), and RA8_INTERNAL.

Referenced by internal_validate_allowed_args(), internal_validate_mode_fields(), internal_validate_network_args(), and mdl_cli_validate().

internal_flag_bit()

uint64_t internal_flag_bit ( bool value, uint64_t bit )

static

Convert a Boolean option to an option-mask bit.

Returns the supplied single-bit value only when value is true.

Parameters

[in]	value	Boolean option value.
[in]	bit	Presence bit assigned to that option.

Returns

bit when selected, otherwise zero.

Return values

0	value is false.

Precondition

value is a canonical C Boolean.

bit is zero or one valid option bit.

Postcondition

No caller or global state is modified.

The result contains no bit other than bit.

Note

Thread-safe: pure value conversion.

Since

0.1.0

Definition at line 365 of file mdl_cli.c.

References RA8_INTERNAL.

Referenced by internal_args_mask().

internal_is_option_value()

bool internal_is_option_value ( const char * flag, const char * value )

static

Decide whether one token is a value for the matched option.

Ordinary values cannot begin with -; --from additionally accepts a leading minus followed by a digit or decimal point.

Parameters

[in]	flag	Matched option spelling.
[in]	value	Candidate following token, or NULL.

Returns

Whether value belongs to flag.

Return values

true	The token is an ordinary or signed chapter value.
false	The token is missing or begins another option.

Precondition

flag is non-NULL and NUL-terminated.

value, when non-NULL, points to a NUL-terminated argument token.

Postcondition

No state is modified.

The result depends only on value and flag.

Note

Reentrant and thread-safe.

Since

0.1.0

Definition at line 43 of file mdl_cli.c.

References RA8_INTERNAL, and strcmp().

Referenced by internal_take_opt().

internal_option_name()

const char * internal_option_name ( uint64_t bit )

static

< Presence bit to identify.

< User-facing option name.

Definition at line 590 of file mdl_cli.c.

References k_arg_allow_incomplete, k_arg_allow_private, k_arg_attr, k_arg_browse, k_arg_ca_file, k_arg_cache_dir, k_arg_cfg, k_arg_chapters, k_arg_contact, k_arg_cookie, k_arg_cross_host, k_arg_format, k_arg_from, k_arg_help, k_arg_ignore_robots, k_arg_init, k_arg_list, k_arg_max, k_arg_max_bytes, k_arg_out, k_arg_pack, k_arg_page, k_arg_pick, k_arg_polite, k_arg_progress, k_arg_proxy, k_arg_refetch, k_arg_remove, k_arg_search, k_arg_seed, k_arg_separate, k_arg_series, k_arg_socks5, k_arg_timeout, k_arg_update, k_arg_update_all, k_arg_verify, k_arg_verify_dir, k_arg_version, and RA8_INTERNAL.

Referenced by internal_validate_allowed_args().

internal_parse_bool_flags()

bool internal_parse_bool_flags ( const char * arg, mdl_args_t * a )

static

Consume any recognised boolean flag at arg.

Matches recognized flag spellings and updates their bounded fields. Unrecognized input leaves the argument record unchanged.

Parameters

[in]	arg	Current command-line argument.
[in,out]	a	Argument record updated for a recognized flag.

Returns

True when arg names a recognized boolean flag.

Return values

true	The documented predicate holds or the requested operation completed.
false	The predicate does not hold or validation rejected the operation.

Precondition

Every required pointer is non-null and remains valid for the call.

Lengths and capacities describe complete referenced objects without overflow.

Postcondition

Documented outputs and the return value describe the same outcome.

A rejected or failed operation is never reported as successful.

Note

Thread safety follows ownership of the supplied context; no synchronization is added.

Since

Version 0.1.0

Definition at line 145 of file mdl_cli.c.

References mdl_args_t::allow_incomplete, mdl_args_t::allow_private, mdl_args_t::bad, mdl_args_t::browse, mdl_args_t::cross_host, mdl_args_t::help, mdl_args_t::ignore_robots, internal_take_flag(), mdl_args_t::list, mdl_args_t::polite, mdl_args_t::progress, RA8_INTERNAL, mdl_args_t::refetch, mdl_args_t::separate, mdl_args_t::update, mdl_args_t::update_all, and mdl_args_t::version.

Referenced by mdl_cli_parse().

internal_parse_positional_or_bad()

void internal_parse_positional_or_bad ( const char * arg, mdl_args_t * a )

static

Record a positional URL or reject an unexpected token.

Stores the first non-option token as the page URL; any additional, NULL, or option-shaped token sets the parser's bad-input flag.

Parameters

[in]	arg	Borrowed command token being classified.
[in,out]	a	Parsed argument state to update.

Precondition

a is non-NULL.

arg, when non-NULL, is NUL-terminated.

Postcondition

At most one positional URL is stored.

Rejected input sets a bad without taking token ownership.

Note

The pointer stored in a remains owned by the command vector.

Since

0.1.0

Definition at line 266 of file mdl_cli.c.

References mdl_args_t::bad, mdl_args_t::page_url, and RA8_INTERNAL.

Referenced by mdl_cli_parse().

internal_parse_value_opt()

bool internal_parse_value_opt ( int argc, char ** argv, int * i, mdl_args_t * a )

static

Consume one recognized option that requires a value.

Searches the fixed option table, records the following token through its destination field, and marks truncated option pairs invalid.

Parameters

[in]	argc	Number of readable entries in argv.
[in]	argv	Borrowed command token vector.
[in,out]	i	Index of the token being considered.
[in,out]	a	Parsed argument state receiving the borrowed value pointer.

Returns

Whether the current token names a value-bearing option.

Return values

true	The option was recognized, including a recorded missing value.
false	The token is not in the fixed value-option table.

Precondition

argv, i, and a are non-NULL.

0 <= *i < argc and argv has argc readable entries.

Postcondition

A recognized option advances i only when a value token exists.

No command-token pointer ownership is transferred.

Note

Table size and argument traversal are compile-time bounded.

Since

0.1.0

< Exact option spelling.

< Parsed-argument field receiving its value.

Definition at line 216 of file mdl_cli.c.

References mdl_args_t::attr, mdl_args_t::bad, mdl_args_t::ca_file, mdl_args_t::cache_dir, mdl_args_t::cfg, mdl_args_t::chapters, mdl_args_t::contact, mdl_args_t::cookie_file, mdl_args_t::format, mdl_args_t::from, mdl_args_t::init_site_url, internal_take_opt(), mdl_args_t::max, mdl_args_t::max_bytes, mdl_args_t::out, mdl_args_t::pack, mdl_args_t::pick, mdl_args_t::proxy, RA8_INTERNAL, mdl_args_t::remove_series, mdl_args_t::seed, mdl_args_t::series, mdl_args_t::socks5, and mdl_args_t::timeout.

Referenced by mdl_cli_parse().

internal_parse_verify_opt()

bool internal_parse_verify_opt ( int argc, char ** argv, int * i, mdl_args_t * a )

static

Consume the optional --verify DIR argument pair.

Recognizes only --verify, requires one following token, records the directory, and advances the shared argument index exactly once.

Parameters

[in]	argc	Number of readable entries in argv.
[in]	argv	Borrowed command token vector.
[in,out]	i	Index of the token being considered.
[in,out]	a	Parsed argument state receiving the directory or bad flag.

Returns

Whether the current token was --verify and was consumed.

Return values

true	The option was recognized; missing value is recorded in a.
false	The current token was not --verify and state is unchanged.

Precondition

argv, i, and a are non-NULL.

0 <= *i < argc and argv has argc readable entries.

Postcondition

A true result advances i to the value token when it exists.

No command-token pointer ownership is transferred.

Note

Parsing is bounded by argc and performs no allocation.

Since

0.1.0

Definition at line 182 of file mdl_cli.c.

References mdl_args_t::bad, RA8_INTERNAL, strcmp(), mdl_args_t::verify, and mdl_args_t::verify_dir.

Referenced by mdl_cli_parse().

internal_record_mode()

void internal_record_mode ( bool condition, mdl_cli_mode_t candidate, mdl_cli_mode_t * mode, size_t * count )

static

Record one selected primary CLI mode.

Updates the candidate and selection count only when condition is true, enabling explicit conjunction-based mode resolution.

Parameters

[in]	condition	Whether the candidate mode was selected.
[in]	candidate	Mode associated with the condition.
[in,out]	mode	Last selected mode.
[in,out]	count	Number of selected primary modes.

Precondition

mode and count are non-NULL.

count can be incremented without size_t overflow.

Postcondition

On true, mode equals candidate and count grows by one.

On false, both outputs are unchanged.

Note

Not thread-safe: mutates caller-owned resolution state.

Since

0.1.0

Definition at line 471 of file mdl_cli.c.

Referenced by internal_resolve_mode().

internal_resolve_mode()

mdl_cli_mode_t internal_resolve_mode ( const mdl_args_t * a, size_t * count )

static

Resolve primary-mode fields and count their selections.

Classifies positional URLs as artifacts or pages and records every other mutually-exclusive primary-mode option.

Parameters

[in]	a	Parsed CLI arguments.
[in,out]	count	Selection counter, normally initialised to zero.

Returns

The last selected mode, or k_mdl_cli_mode_invalid.

Return values

k_mdl_cli_mode_invalid

No primary mode was selected.

Precondition

a and count are non-NULL.

count can grow by the number of primary modes without overflow.

Postcondition

count grows once per selected primary mode.

a is unchanged.

Note

Thread-safe: mutates only count.

Since

0.1.0

Definition at line 570 of file mdl_cli.c.

References mdl_args_t::browse, mdl_args_t::help, mdl_args_t::init_site_url, internal_cli_artifact_url(), internal_record_mode(), k_mdl_cli_mode_artifact, k_mdl_cli_mode_browse, k_mdl_cli_mode_help, k_mdl_cli_mode_init_site, k_mdl_cli_mode_invalid, k_mdl_cli_mode_list, k_mdl_cli_mode_pack, k_mdl_cli_mode_page, k_mdl_cli_mode_remove, k_mdl_cli_mode_search, k_mdl_cli_mode_series, k_mdl_cli_mode_update_all, k_mdl_cli_mode_verify, k_mdl_cli_mode_version, mdl_args_t::list, mdl_args_t::pack, mdl_args_t::page_url, RA8_INTERNAL, mdl_args_t::remove_series, mdl_args_t::series, mdl_args_t::update_all, mdl_args_t::verify, and mdl_args_t::version.

Referenced by mdl_cli_validate().

internal_take_flag()

bool internal_take_flag ( const char * arg, const char * flag, bool * dst, bool * bad )

static

Consume one bare Boolean option.

Matches arg against flag and treats a repeated flag as a parse error while leaving the option selected.

Parameters

[in]	arg	Current argument, or NULL.
[in]	flag	Option spelling to match.
[in,out]	dst	Boolean field selected by the option.
[in,out]	bad	Accumulated parse-error flag.

Returns

Whether arg matched flag.

Return values

true	The flag matched and dst is true.
false	The flag did not match and outputs are unchanged.

Precondition

flag, dst, and bad are non-NULL.

A non-NULL arg is NUL-terminated.

Postcondition

On a first match, dst is true without setting bad.

On a repeated match, both dst and bad are true.

Note

Not thread-safe: mutates caller-owned parse state.

Since

0.1.0

Definition at line 118 of file mdl_cli.c.

References RA8_INTERNAL, and strcmp().

Referenced by internal_parse_bool_flags().

internal_take_opt()

bool internal_take_opt ( char ** argv, int argc, int * i, const char * flag, const char ** dst, bool * bad )

static

Consume one value-bearing option at the current argument.

Matches flag exactly, records its following value, and marks duplicate or missing values through bad. The signed numeric grammar documented for --from is accepted without treating a different option as its value.

Parameters

[in]	argv	Argument vector.
[in]	argc	Argument count.
[in,out]	i	Current argument index.
[in]	flag	Option spelling to match.
[in,out]	dst	Destination for the borrowed value pointer.
[in,out]	bad	Accumulated parse-error flag.

Returns

Whether the current argument matched flag.

Return values

true	The option matched, whether or not its value was valid.
false	The current argument did not match and outputs are unchanged.

Precondition

All pointer arguments are non-NULL.

0 <= *i < argc and argv[*i] is readable.

Postcondition

On a valid match, i advances once and dst receives the value.

A duplicate or missing value sets bad true.

Note

Not thread-safe: mutates caller-owned parse state.

Since

0.1.0

Definition at line 83 of file mdl_cli.c.

References internal_is_option_value(), and strcmp().

Referenced by internal_parse_value_opt().

internal_validate_allowed_args()

ra8_err_t internal_validate_allowed_args ( const mdl_args_t * a, ra8_io_stream_t * diagnostic, mdl_cli_mode_t selected )

static

Reject option bits that are incompatible with the selected mode.

Obtains the allowed mask, identifies the first disallowed supplied bit deterministically, and emits its stable option name.

Parameters

[in]	a	Fully parsed argument state.
[in,out]	diagnostic	Bound rejection stream.
[in]	selected	Primary mode selected by exclusivity validation.

Returns

Canonical validation or stream status.

Return values

k_ra8_ok	The supplied option mask is allowed.
k_ra8_err_invalid_arg	One incompatible option was reported.
other	The diagnostic stream rejected output.

Precondition

a and diagnostic are non-NULL.

selected is a single mdl_cli_mode_t value.

Postcondition

No parsed argument field is modified.

Failure reports at most the lowest-numbered invalid option.

Note

Validation is bounded by the fixed-width option mask.

Since

0.1.0

Definition at line 734 of file mdl_cli.c.

References internal_args_mask(), internal_cli_allowed_args(), internal_cli_invalid(), internal_option_name(), k_ra8_ok, mdl_cli_mode_name(), priv_mdl_cli_reject_parts(), and RA8_INTERNAL.

Referenced by mdl_cli_validate().

internal_validate_mode_fields()

ra8_err_t internal_validate_mode_fields ( const mdl_args_t * a, ra8_io_stream_t * diagnostic, mdl_cli_mode_t selected )

static

Validate required and mutually exclusive fields for one mode.

Enforces the page, series, discovery, update-all, and verify operand shapes after primary-mode exclusivity has been established.

Parameters

[in]	a	Fully parsed argument state.
[in,out]	diagnostic	Bound rejection stream.
[in]	selected	Primary mode being validated.

Returns

Canonical validation or stream status.

Return values

k_ra8_ok	Every required operand shape is valid.
k_ra8_err_invalid_arg	One invalid field conjunction was reported.
other	The diagnostic stream rejected output.

Precondition

a and diagnostic are non-NULL.

selected is a single mdl_cli_mode_t value.

Postcondition

No parsed argument field or borrowed token is modified.

The result reflects all mode-field conjunctions, not option spelling.

Note

Compatible-option validation is performed separately.

Since

0.1.0

Definition at line 772 of file mdl_cli.c.

References mdl_args_t::cfg, mdl_args_t::format, internal_cli_invalid(), k_mdl_cli_mode_artifact, k_mdl_cli_mode_browse, k_mdl_cli_mode_pack, k_mdl_cli_mode_search, k_mdl_cli_mode_series, k_mdl_cli_mode_update_all, k_mdl_cli_mode_verify, k_ra8_ok, mdl_args_t::out, mdl_args_t::page_url, RA8_INTERNAL, strlen(), strncmp(), and mdl_args_t::verify_dir.

Referenced by mdl_cli_validate().

internal_validate_network_args()

ra8_err_t internal_validate_network_args ( const mdl_args_t * a, ra8_io_stream_t * diagnostic )

static

Validate mutually exclusive and required network-policy arguments.

Rejects simultaneous proxy transports, partial mTLS credentials, insecure URLs without opt-in, and malformed contact identities.

Parameters

[in]	a	Fully parsed argument state.
[in,out]	diagnostic	Bound rejection stream.

Returns

Canonical validation or stream status.

Return values

k_ra8_ok	Every supplied network-policy field is compatible.
k_ra8_err_invalid_arg	One unsafe conjunction was reported.
other	The diagnostic stream rejected output.

Precondition

a and diagnostic are non-NULL.

Every non-NULL string field in a is NUL-terminated.

Postcondition

No parsed argument field or borrowed token is modified.

Failure is reported before a network interface is initialized.

Note

Performs syntax and conjunction checks only; no network I/O occurs.

Since

0.1.0

Definition at line 817 of file mdl_cli.c.

References mdl_args_t::allow_private, mdl_args_t::attr, internal_cli_invalid(), k_ra8_ok, mdl_args_t::proxy, RA8_INTERNAL, mdl_args_t::socks5, and strcmp().

Referenced by mdl_cli_validate().

internal_value_bit()

uint64_t internal_value_bit ( const void * value, uint64_t bit )

static

Convert pointer presence to an option-mask bit.

Returns the supplied single-bit value only for a non-NULL pointer.

Parameters

[in]	value	Borrowed pointer-valued option.
[in]	bit	Presence bit assigned to that option.

Returns

bit when present, otherwise zero.

Return values

0	value is NULL.

Precondition

bit is zero or one valid option bit.

value is borrowed and never dereferenced.

Postcondition

No caller or global state is modified.

The result contains no bit other than bit.

Note

Thread-safe: pure value conversion.

Since

0.1.0

Definition at line 346 of file mdl_cli.c.

References RA8_INTERNAL.

Referenced by internal_args_mask().

mdl_cli_mode_name()

const char * mdl_cli_mode_name

(

mdl_cli_mode_t

mode

)

Stable human-readable command mode name.

Provides the spelling used in diagnostics without exposing a mutable name table to callers. Unknown values map to "invalid".

Parameters

[in]

mode

Mode value.

Returns

Pointer to a process-lifetime static mode name.

Return values

non-NULL

A stable name, or "invalid" for an unknown value.

Precondition

mode is any value representable by mdl_cli_mode_t.

The caller treats the returned bytes as read-only.

Postcondition

The returned string is NUL-terminated.

No caller-visible state is modified.

Note

Thread-safe: reads immutable static storage only.

Since

0.1.0

Definition at line 415 of file mdl_cli.c.

Referenced by internal_validate_allowed_args().

mdl_cli_parse()

void mdl_cli_parse	(	int	argc,
		char **	argv,
		mdl_args_t *	a )

Parse argv into a; numeric fields stay as strings for main.

Parameters

[in]	argc	Argument count.
[in]	argv	Argument vector.
[out]	a	Parsed options; a->bad is set on any unknown argument.

Returns

Nothing.

Precondition

argv holds argc entries; a is non-NULL.

a was zero-initialised (defaults applied) before the call.

Postcondition

Every recognised option is recorded in a.

a->bad reflects whether an argument was unrecognised.

Note

Not thread-safe: writes caller storage.

Since

0.1.0

Uses caller-owned fixed-capacity argument state without allocation. Mode selection and numeric publication remain explicit validation phases.

Definition at line 278 of file mdl_cli.c.

References internal_parse_bool_flags(), internal_parse_positional_or_bad(), internal_parse_value_opt(), and internal_parse_verify_opt().

Referenced by internal_main_init().

mdl_cli_run_opts()

mdl_run_opts_t mdl_cli_run_opts

(

const mdl_args_t *

a

)

Fold parsed args into the cross-cutting run options.

Parameters

[in]

a

Parsed command-line options.

Returns

The assembled run options (network policy + identity/politeness).

Return values

mdl_run_opts_t

A value with the policy and knobs set from a.

Precondition

a is non-NULL.

a was populated by mdl_cli_parse.

Postcondition

The returned policy has the size cap defaulted when --max-bytes was absent.

Note

Thread-safe: depends only on its argument.

Since

0.1.0

Uses caller-owned fixed-capacity argument state without allocation. Mode selection and numeric publication remain explicit validation phases.

Postcondition

Documented outputs and the return value describe the same outcome.

Definition at line 862 of file mdl_cli.c.

References mdl_args_t::allow_incomplete, mdl_args_t::allow_private, mdl_args_t::contact, mdl_args_t::cross_host, mdl_args_t::ignore_robots, k_cli_dec_base, k_max_response_bytes_def, mdl_args_t::max_bytes, mdl_args_t::polite, mdl_args_t::progress, mdl_args_t::proxy, mdl_args_t::refetch, and mdl_args_t::socks5.

Referenced by main().

mdl_cli_validate()

ra8_err_t mdl_cli_validate ( const mdl_args_t * a, ra8_io_stream_t * diagnostic, mdl_cli_mode_t * mode )

nodiscard

Validate mode selection, required arguments, and per-mode options.

Enforces exactly one primary command, rejects duplicate/unknown options recorded by mdl_cli_parse, and uses a per-mode allowlist so an accepted option always has an effect. Proxy escape hatches and debug image attributes receive their mode-independent consistency checks here.

Parameters

[in]	a	Parsed, pre-default argument set.
[in,out]	diagnostic	Bound stream receiving any rejection diagnostic.
[out]	mode	Receives the one selected command mode on success.

Returns

Canonical validation or stream status.

Return values

k_ra8_ok	Validation succeeded and mode names the command.
k_ra8_err_invalid_arg	The invocation is invalid and its complete diagnostic was written.
k_ra8_err_null_ptr	A required pointer was null.
other	The injected stream rejected a diagnostic write.

Precondition

a, diagnostic, and mode are non-NULL and mdl_cli_parse has run.

Defaults that were absent on the command line have not been injected.

Postcondition

On success, mode is not k_mdl_cli_mode_invalid.

On failure, mode is k_mdl_cli_mode_invalid.

Note

Thread-safe across distinct output objects and streams.

Since

0.1.0

Definition at line 832 of file mdl_cli.c.

References mdl_args_t::bad, internal_cli_invalid(), internal_resolve_mode(), internal_validate_allowed_args(), internal_validate_mode_fields(), internal_validate_network_args(), k_mdl_cli_mode_invalid, k_ra8_err_null_ptr, and k_ra8_ok.

Referenced by main().