Strict bounded numeric-option parsing for mdl. More...

#include <errno.h>
#include <math.h>
#include <stdint.h>
#include <stdlib.h>
#include "mdl_cli.h"
#include "mdl_cli_internal.h"
#include "ra8_attributes.h"

Include dependency graph for mdl_cli_nums.c:

Data Structures
struct	mdl_cli_raw_nums_t
	Native-width numeric candidates retained until range validation. More...

Enumerations
enum	mdl_cli_parse_t : uint8_t { k_cli_dec_base = 10 }
	Radix used by strict unsigned decimal parsing. More...
enum	mdl_cli_timeout_t : uint32_t { k_req_timeout_def = 25000U }
	Default request time budget when --timeout is absent. More...

Functions
static bool	internal_cli_parse_ul (const char s, unsigned long out)
	Parse one complete unsigned-long decimal value.
static bool	internal_cli_parse_u64 (const char s, uint64_t out)
	Parse one complete unsigned 64-bit decimal value.
static bool	internal_cli_parse_chapter (const char s, double out)
	Parse one complete finite decimal chapter number for --from.
static ra8_err_t	internal_cli_reject_integer (ra8_io_stream_t diagnostic, const char name, const char *value)
	Reject one option whose value is not an unsigned decimal integer.
static ra8_err_t	internal_cli_reject_limit (ra8_io_stream_t diagnostic, const char prefix, uint64_t value, const char *suffix)
	Write a rejection line containing one unsigned limit value.
static ra8_err_t	internal_cli_opt_ul (ra8_io_stream_t diagnostic, const char name, const char text, unsigned long dflt, unsigned long out)
	Parse one optional unsigned-long option or emit its rejection.
static ra8_err_t	internal_cli_opt_u64 (ra8_io_stream_t diagnostic, const char name, const char text, uint64_t dflt, uint64_t out)
	Parse one optional uint64 option or emit its rejection.
static ra8_err_t	internal_cli_parse_num_values (const mdl_args_t a, ra8_io_stream_t diagnostic, mdl_nums_t out, mdl_cli_raw_nums_t raw)
	Parse all numeric spellings into a failure-atomic candidate.
static ra8_err_t	internal_cli_parse_chapter_pick (const mdl_args_t a, ra8_io_stream_t diagnostic, mdl_nums_t out, mdl_cli_raw_nums_t raw)
	Parse chapter and pick values into the candidate numeric record.
static ra8_err_t	internal_cli_validate_num_ranges (const mdl_args_t a, ra8_io_stream_t diagnostic, const mdl_cli_raw_nums_t *raw)
	Enforce numeric option ranges after complete spelling conversion.
ra8_err_t	mdl_cli_parse_nums (const mdl_args_t a, ra8_io_stream_t diagnostic, mdl_nums_t *n)
	Strictly parse and validate every numeric CLI field.

Detailed Description

Strict bounded numeric-option parsing for mdl.

Converts the validated command's numeric strings into fixed-width run values and rejects signs, garbage, overflow, and invalid ranges.

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

Definition in file mdl_cli_nums.c.

Enumeration Type Documentation

◆ mdl_cli_parse_t

enum mdl_cli_parse_t : uint8_t

Radix used by strict unsigned decimal parsing.

Enumerator
k_cli_dec_base	Decimal conversion radix.

Definition at line 19 of file mdl_cli_nums.c.

◆ mdl_cli_timeout_t

enum mdl_cli_timeout_t : uint32_t

Default request time budget when --timeout is absent.

Enumerator
k_req_timeout_def	Twenty-five seconds in milliseconds.

Definition at line 24 of file mdl_cli_nums.c.

Function Documentation

◆ internal_cli_opt_u64()

ra8_err_t internal_cli_opt_u64	(	ra8_io_stream_t *	diagnostic,
		const char *	name,
		const char *	text,
		uint64_t	dflt,
		uint64_t *	out )

static

Parse one optional uint64 option or emit its rejection.

Parameters

[in,out]	diagnostic	Bound diagnostic stream.
[in]	name	Option name used in diagnostics.
[in]	text	Optional NUL-terminated option value.
[in]	dflt	Value used when `text` is null.
[out]	out	Receives the default or parsed value on success.

Returns: Canonical parse or stream status.

Return values

k_ra8_ok	`out` was initialized.
k_ra8_err_invalid_arg	The invalid spelling was reported.
other	The diagnostic stream rejected output.

Precondition: diagnostic, name, and out are non-NULL.; Non-null text is NUL-terminated.

Postcondition: Success initializes out exactly once.; Failure leaves out unchanged.

Note: No pointer ownership is transferred.

Since: 0.1.0

Converts complete decimal spellings into a local candidate. Caller-visible options change only after every range check succeeds.

Definition at line 273 of file mdl_cli_nums.c.

References internal_cli_parse_u64(), internal_cli_reject_integer(), k_ra8_ok, and RA8_INTERNAL.

Referenced by internal_cli_parse_num_values().

◆ internal_cli_opt_ul()

ra8_err_t internal_cli_opt_ul	(	ra8_io_stream_t *	diagnostic,
		const char *	name,
		const char *	text,
		unsigned long	dflt,
		unsigned long *	out )

static

Parse one optional unsigned-long option or emit its rejection.

Parameters

[in,out]	diagnostic	Bound diagnostic stream.
[in]	name	Option name used in diagnostics.
[in]	text	Optional NUL-terminated option value.
[in]	dflt	Value used when `text` is null.
[out]	out	Receives the default or parsed value on success.

Returns: Canonical parse or stream status.

Return values

k_ra8_ok	`out` was initialized.
k_ra8_err_invalid_arg	The invalid spelling was reported.
other	The diagnostic stream rejected output.

Precondition: diagnostic, name, and out are non-NULL.; Non-null text is NUL-terminated.

Postcondition: Success initializes out exactly once.; Failure leaves out unchanged.

Note: No pointer ownership is transferred.

Since: 0.1.0

Converts complete decimal spellings into a local candidate. Caller-visible options change only after every range check succeeds.

Definition at line 234 of file mdl_cli_nums.c.

References internal_cli_parse_ul(), internal_cli_reject_integer(), k_ra8_ok, and RA8_INTERNAL.

Referenced by internal_cli_parse_chapter_pick(), and internal_cli_parse_num_values().

◆ internal_cli_parse_chapter()

bool internal_cli_parse_chapter	(	const char *	s,
		double *	out )

static

Parse one complete finite decimal chapter number for --from.

Uses the C numeric grammar exposed by strtod, then rejects overflow, missing conversion, trailing bytes, NaN, and infinity.

Parameters

[in]	s	NUL-terminated option value.
[out]	out	Receives the finite chapter number.

Returns: Whether the complete value was accepted.

Return values

true	`out` received one finite number.
false	An argument or numeric spelling was invalid.

Precondition: s and out are non-NULL for success.; The caller does not consume out after false.

Postcondition: On true, isfinite(*out) is true.; No global state other than the temporary errno value is retained.

Note: Not thread-safe with code that concurrently depends on errno.

Since: 0.1.0

Definition at line 133 of file mdl_cli_nums.c.

References RA8_INTERNAL.

Referenced by internal_cli_parse_chapter_pick().

◆ internal_cli_parse_chapter_pick()

ra8_err_t internal_cli_parse_chapter_pick	(	const mdl_args_t *	a,
		ra8_io_stream_t *	diagnostic,
		mdl_nums_t *	out,
		mdl_cli_raw_nums_t *	raw )

static

Parse chapter and pick values into the candidate numeric record.

Parameters

[in]	a	Parsed argument strings.
[in,out]	diagnostic	Bound rejection stream.
[in,out]	out	Candidate numeric record.
[out]	raw	Native-width numeric candidates receiving the pick value.

Returns: Canonical parse or stream status.

Return values

k_ra8_ok	Both values were accepted.
k_ra8_err_invalid_arg	One invalid spelling was reported.
other	The diagnostic stream rejected output.

Precondition: All pointers are non-NULL.; out contains the scalar values parsed earlier.

Postcondition: Success initializes chapter-presence, chapter-number, and raw->pick.; Failure leaves public output unpublished.

Note: Thread-safe across distinct arguments and streams.

Since: 0.1.0

Converts complete decimal spellings into a local candidate. Caller-visible options change only after every range check succeeds.

Definition at line 356 of file mdl_cli_nums.c.

References mdl_args_t::from, mdl_nums_t::from_num, mdl_nums_t::from_present, internal_cli_opt_ul(), internal_cli_parse_chapter(), mdl_args_t::pick, mdl_cli_raw_nums_t::pick, priv_mdl_cli_reject_parts(), and RA8_INTERNAL.

Referenced by mdl_cli_parse_nums().

◆ internal_cli_parse_num_values()

ra8_err_t internal_cli_parse_num_values	(	const mdl_args_t *	a,
		ra8_io_stream_t *	diagnostic,
		mdl_nums_t *	out,
		mdl_cli_raw_nums_t *	raw )

static

Parse all numeric spellings into a failure-atomic candidate.

Parameters

[in]	a	Parsed argument strings.
[in,out]	diagnostic	Bound rejection stream.
[out]	out	Candidate populated only while parsing succeeds.
[out]	raw	Native-width values retained for range validation.

Returns: Canonical parse or stream status.

Return values

k_ra8_ok	Every spelling was accepted.
k_ra8_err_invalid_arg	One invalid spelling was reported.
other	The diagnostic stream rejected output.

Precondition: All pointers are non-NULL.; a came from mdl_cli_parse.

Postcondition: Success initializes every field in out and raw.; Failure leaves publication to the caller disabled.

Note: Thread-safe across distinct arguments and streams.

Since: 0.1.0

Converts complete decimal spellings into a local candidate. Caller-visible options change only after every range check succeeds.

Definition at line 311 of file mdl_cli_nums.c.

References mdl_args_t::chapters, mdl_cli_raw_nums_t::chapters, internal_cli_opt_u64(), internal_cli_opt_ul(), k_ra8_ok, k_req_timeout_def, mdl_args_t::max, mdl_args_t::max_bytes, mdl_cli_raw_nums_t::max_bytes, mdl_cli_raw_nums_t::max_imgs, RA8_INTERNAL, mdl_args_t::seed, mdl_nums_t::seed, mdl_args_t::timeout, and mdl_cli_raw_nums_t::timeout.

Referenced by mdl_cli_parse_nums().

◆ internal_cli_parse_u64()

bool internal_cli_parse_u64	(	const char *	s,
		uint64_t *	out )

static

Parse one complete unsigned 64-bit decimal value.

Applies the same strict spelling rules as internal_cli_parse_ul while preserving the full uint64_t option range.

Parameters

[in]	s	Candidate NUL-terminated decimal text.
[out]	out	Receives the converted value on success.

Returns: Whether the complete spelling was accepted.

Return values

true	`out` was initialized with the exact value.
false	The spelling or range was invalid.

Precondition: out is non-NULL.; s, when non-NULL, is NUL-terminated.

Postcondition: Success initializes out exactly once.; Failure does not publish a converted value.

Note: Temporarily modifies errno; callers must not depend on its prior value.

Since: 0.1.0

Definition at line 93 of file mdl_cli_nums.c.

References k_cli_dec_base, and RA8_INTERNAL.

Referenced by internal_cli_opt_u64().

◆ internal_cli_parse_ul()

bool internal_cli_parse_ul	(	const char *	s,
		unsigned long *	out )

static

Parse one complete unsigned-long decimal value.

Rejects NULL, empty, signed, whitespace-prefixed, overflowing, and trailing-garbage spellings before publishing the converted value.

Parameters

[in]	s	Candidate NUL-terminated decimal text.
[out]	out	Receives the converted value on success.

Returns: Whether the complete spelling was accepted.

Return values

true	`out` was initialized with the exact value.
false	The spelling or range was invalid.

Precondition: out is non-NULL.; s, when non-NULL, is NUL-terminated.

Postcondition: Success initializes out exactly once.; Failure does not publish a converted value.

Note: Temporarily modifies errno; callers must not depend on its prior value.

Since: 0.1.0

Definition at line 53 of file mdl_cli_nums.c.

References k_cli_dec_base, and RA8_INTERNAL.

Referenced by internal_cli_opt_ul().

◆ internal_cli_reject_integer()

ra8_err_t internal_cli_reject_integer	(	ra8_io_stream_t *	diagnostic,
		const char *	name,
		const char *	value )

static

Reject one option whose value is not an unsigned decimal integer.

Parameters

[in,out]	diagnostic	Bound diagnostic stream.
[in]	name	Option name without leading dashes.
[in]	value	Rejected NUL-terminated spelling.

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: All pointers are non-NULL and strings are NUL-terminated.; diagnostic is exclusively owned for the call.

Postcondition: The rejected value is reproduced without formatting interpretation.; No parsed numeric output is modified.

Note: Thread-safe across distinct streams.

Since: 0.1.0

Converts complete decimal spellings into a local candidate. Caller-visible options change only after every range check succeeds.

Definition at line 167 of file mdl_cli_nums.c.

References priv_mdl_cli_reject_parts().

Referenced by internal_cli_opt_u64(), and internal_cli_opt_ul().

◆ internal_cli_reject_limit()

ra8_err_t internal_cli_reject_limit	(	ra8_io_stream_t *	diagnostic,
		const char *	prefix,
		uint64_t	value,
		const char *	suffix )

static

Write a rejection line containing one unsigned limit value.

Parameters

[in,out]	diagnostic	Bound diagnostic stream.
[in]	prefix	Text before the decimal value.
[in]	value	Limit rendered as canonical unsigned decimal.
[in]	suffix	Text after the decimal value, including the newline.

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 text or digits.

Precondition: All pointers are non-NULL and strings are NUL-terminated.; diagnostic is exclusively owned for the call.

Postcondition: Success-path rejection emits prefix, value, then suffix.; No numeric parser output is modified.

Note: Thread-safe across distinct streams.

Since: 0.1.0

Converts complete decimal spellings into a local candidate. Caller-visible options change only after every range check succeeds.

Definition at line 196 of file mdl_cli_nums.c.

References k_ra8_ok, priv_mdl_cli_put_parts(), priv_mdl_cli_reject_parts(), RA8_INTERNAL, and ra8_io_stream_put_u64().

Referenced by internal_cli_validate_num_ranges().

◆ internal_cli_validate_num_ranges()

ra8_err_t internal_cli_validate_num_ranges	(	const mdl_args_t *	a,
		ra8_io_stream_t *	diagnostic,
		const mdl_cli_raw_nums_t *	raw )

static

Enforce numeric option ranges after complete spelling conversion.

Parameters

[in]	a	Parsed argument strings used for presence-sensitive ranges.
[in,out]	diagnostic	Bound rejection stream.
[in]	raw	Parsed native-width candidates before narrowing.

Returns: Canonical validation or stream status.

Return values

k_ra8_ok	Every converted value lies in its public range.
k_ra8_err_invalid_arg	One invalid range was reported.
other	The diagnostic stream rejected output.

Precondition: All pointers are non-NULL and values were parsed completely.; diagnostic is exclusively owned for the call.

Postcondition: Success authorizes all later narrowing conversions.; Failure leaves public output unpublished.

Note: Thread-safe across distinct arguments and streams.

Since: 0.1.0

Converts complete decimal spellings into a local candidate. Caller-visible options change only after every range check succeeds.

Definition at line 391 of file mdl_cli_nums.c.

References mdl_cli_raw_nums_t::chapters, internal_cli_reject_limit(), k_ra8_ok, mdl_args_t::max_bytes, mdl_cli_raw_nums_t::max_bytes, mdl_cli_raw_nums_t::max_imgs, mdl_args_t::pick, mdl_cli_raw_nums_t::pick, priv_mdl_cli_reject_parts(), RA8_INTERNAL, and mdl_cli_raw_nums_t::timeout.

Referenced by mdl_cli_parse_nums().

◆ mdl_cli_parse_nums()

ra8_err_t mdl_cli_parse_nums	(	const mdl_args_t *	a,
		ra8_io_stream_t *	diagnostic,
		mdl_nums_t *	n )

nodiscard

Strictly parse and validate every numeric CLI field.

Converts the string-form numeric options (--timeout, --chapters, --max, --seed, --from, and --max-bytes for presence-validation) into typed scalars, rejecting any non-numeric or trailing-garbage value with a usage message on the injected diagnostic stream rather than substituting 0. Decimal chapter values such as 108.5 are accepted for --from; NaN and infinity are not. --chapters of 0 is rejected.

Parameters

[in]	a	Parsed command-line options (never NULL).
[in,out]	diagnostic	Bound stream receiving any rejection diagnostic.
[out]	n	Receives the validated scalars (never NULL).

Returns: Canonical validation or stream status.

Return values

k_ra8_ok	All fields are valid and `n` is fully populated.
k_ra8_err_invalid_arg	A field 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 n are non-NULL; a was populated by mdl_cli_parse.; The caller maps k_ra8_err_invalid_arg to the usage exit code.

Postcondition: On success, n->chapters >= 1 and every scalar reflects the args.; On failure, n is left byte-for-byte unchanged.

Note: Thread-safe across distinct output objects and streams.

Since: 0.1.0

Definition at line 421 of file mdl_cli_nums.c.

References mdl_cli_raw_nums_t::chapters, mdl_nums_t::chapters, internal_cli_parse_chapter_pick(), internal_cli_parse_num_values(), internal_cli_validate_num_ranges(), k_ra8_err_null_ptr, k_ra8_ok, mdl_cli_raw_nums_t::max_imgs, mdl_nums_t::max_imgs, mdl_cli_raw_nums_t::pick, mdl_nums_t::pick, mdl_cli_raw_nums_t::timeout, and mdl_nums_t::timeout.

Referenced by main().

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ mdl_cli_parse_t

◆ mdl_cli_timeout_t

Function Documentation

◆ internal_cli_opt_u64()

◆ internal_cli_opt_ul()

◆ internal_cli_parse_chapter()

◆ internal_cli_parse_chapter_pick()

◆ internal_cli_parse_num_values()

◆ internal_cli_parse_u64()

◆ internal_cli_parse_ul()

◆ internal_cli_reject_integer()

◆ internal_cli_reject_limit()

◆ internal_cli_validate_num_ranges()

◆ mdl_cli_parse_nums()