validators Namespace Reference

Validation utilities for TOML configuration parsing. More...

Classes
class	ValidationError
	Exception thrown when configuration validation fails. More...
class	Validator
	Chainable validator for scalar TOML fields. More...
class	VectorValidator
	Chainable validator for vector TOML fields. More...

Functions
template<typename T >
std::string	getTypeName ()
	Helper to get readable type names for error messages.
template<typename T >
Validator< T >	field (const toml::table &config_, const std::string &key_)
	Creates a scalar field validator.
template<typename T >
VectorValidator< T >	vectorField (const toml::table &config_, const std::string &key_)
	Creates a vector field validator.
template<typename T , typename NodeType >
std::optional< T >	getOptional (const toml::node_view< NodeType > &node)
	Extracts an optional scalar value from a TOML node.
template<typename T , typename NodeType >
std::optional< std::vector< T > >	getOptionalVector (const toml::node_view< NodeType > &node)
	Extracts an optional vector from a TOML node.
const toml::table &	getRequiredTable (const toml::table &config, const std::string &key)
	Extracts a required table from a TOML configuration.
template<typename T >
std::vector< T >	scalarOrVector (const toml::table &config, const std::string &key, size_t expected_size)
	Parses a field that can be either a scalar (applied to all) or an exact-size array.
template<typename T >
std::vector< T >	scalarOrVectorOr (const toml::table &config, const std::string &key, size_t expected_size, const std::vector< T > &default_value)
	Parses an optional field that can be either a scalar or an exact-size array.

Detailed Description

Validation utilities for TOML configuration parsing.

Provides a chainable API for type-safe TOML field extraction and validation. Chain validation methods together, then extract the final value in one operation with clear error messages.

Basic Usage

1. Create a validator for option "key" within toml_table using
   • validators::field<T>(toml_table, "key"): for scalar fields
   • validators::vectorField<T>(toml_table, "key"): for vector fields
2. Append chainable validation methods from below as needed: For scalar fields:
   • greaterThan(value): Field must be > value
   • greaterThanEqual(value): Field must be >= value
   • lessThan(value): Field must be < value
   • positive(): Field must be > 0 (shorthand for greaterThan(0)) For vector fields:
   • minLength(size): Vector must have at least size elements
   • hasLength(size): Vector must have exactly size elements
   • positive(): All elements must be > 0
3. Extract the value by appending .value() - for required fields .valueOr(default) - for optional fields with default

Examples

// Parse a required positive double with key "step_size".
double step_size = validators::field<double>(toml, "step_size").positive().value();
 
// Parse an optional string with key "output_dir" with default value "./data_out"
std::string output_dir = validators::field<std::string>(toml, "output_dir").valueOr("./data_out");
 
// Parse a required vector of positive doubles with key "frequencies", defaulting to {1.0, 2.0}
std::vector<double> frequencies = validators::vectorField<double>(toml, "frequencies").minLength(1).positive().valueOr(std::vector<double>{1.0, 2.0});

Supported Types

Scalar fields: int, size_t, double, std::string, bool, etc. Vector fields: std::vector<T> where T is any supported scalar type

Function Documentation

field()

template<typename T >

Validator< T > validators::field	(	const toml::table &	config_,
		const std::string &	key_
	)

Creates a scalar field validator.

Helper function to start a validation chain for scalar fields.

Template Parameters

T	Type of field to validate

Parameters

config_	TOML table containing the field
key_	Name of the field to validate

Returns

A Validator for chaining validation rules

getOptional()

template<typename T , typename NodeType >

std::optional< T > validators::getOptional

(

const toml::node_view< NodeType > &

node

)

Extracts an optional scalar value from a TOML node.

Helper for extracting optional scalar values when the validator API doesn't fit well (e.g., nested structures or conditional parsing). If the node doesn't exist or contains a type mismatch, returns nullopt.

Template Parameters

T	Type of the scalar value
NodeType	Type of the TOML node

Parameters

node	TOML node that may contain a value

Returns

Value if node exists and has matching type, nullopt otherwise

getOptionalVector()

template<typename T , typename NodeType >

std::optional< std::vector< T > > validators::getOptionalVector

(

const toml::node_view< NodeType > &

node

)

Extracts an optional vector from a TOML node.

Helper for extracting vectors when the validator API doesn't fit well (e.g., nested structures or conditional parsing). If the node is not an array or contains type mismatches, returns nullopt.

Template Parameters

T	Element type of the vector
NodeType	Type of the TOML node

Parameters

node	TOML node that may contain an array

Returns

Vector if node is a valid array with matching types, nullopt otherwise

getRequiredTable()

const toml::table & validators::getRequiredTable ( const toml::table &  config, const std::string &  key  )

inline

Extracts a required table from a TOML configuration.

Validates that the specified key exists and contains a table.

Parameters

config	Parent TOML table
key	Name of the table field

Returns

Reference to the table

Exceptions

ValidationError

if table is missing or wrong type

getTypeName()

template<typename T >

std::string validators::getTypeName

(

)

Helper to get readable type names for error messages.

scalarOrVector()

template<typename T >

std::vector< T > validators::scalarOrVector	(	const toml::table &	config,
		const std::string &	key,
		size_t	expected_size
	)

Parses a field that can be either a scalar (applied to all) or an exact-size array.

For per-oscillator settings, this allows users to specify either:

• A single scalar value: transition_frequency = 4.1 (applied to all oscillators)
• An array of exact size: transition_frequency = [4.1, 4.2, 4.3] (one per oscillator)

Template Parameters

T	Element type (int, double, etc.)

Parameters

config	TOML table containing the field
key	Name of the field
expected_size	Expected array size (e.g., num_oscillators)

Returns

Vector of expected_size elements

Exceptions

ValidationError

if field is missing, wrong type, or array has wrong size

scalarOrVectorOr()

template<typename T >

std::vector< T > validators::scalarOrVectorOr	(	const toml::table &	config,
		const std::string &	key,
		size_t	expected_size,
		const std::vector< T > &	default_value
	)

Parses an optional field that can be either a scalar or an exact-size array.

Same as scalarOrVector but returns default_value if field is missing.

Template Parameters

T	Element type (int, double, etc.)

Parameters

config	TOML table containing the field
key	Name of the field
expected_size	Expected array size (e.g., num_oscillators)
default_value	Default vector to return if field is missing

Returns

Vector of expected_size elements

Exceptions

ValidationError

if field has wrong type or array has wrong size

vectorField()

template<typename T >

VectorValidator< T > validators::vectorField	(	const toml::table &	config_,
		const std::string &	key_
	)

Creates a vector field validator.

Helper function to start a validation chain for array/vector fields.

Template Parameters

T	Element type of the vector

Parameters

config_	TOML table containing the field
key_	Name of the field to validate

Returns

A VectorValidator for chaining validation rules