ok

Holds a named list of key=value options and nested InputBlocks.

Parses and stores structured input in the format:

BlockName1 {
  option1 = value1;
  option2 = value2;
  InnerBlock {
    option1 = v3;
  }
}

Can be constructed from a literal option list, a string, or a file stream. Block and option name comparison is case-insensitive.

Note: Implementations are inline in the header for single-file header-only use.

#include <InputBlock.hpp>

Public Member Functions
	InputBlock ()
	Default constructor; name will be blank.

	InputBlock (std::string_view name, std::initializer_list< Option > options={})
	Constructs from a literal list of Option structs.

	InputBlock (std::string_view name, const std::string &string_input)
	Constructs by parsing `string_input` in Block{option=value;} format.

	InputBlock (std::string_view name, const std::istream &file)
	Constructs by reading and parsing a plain-text file stream.

void	add (InputBlock block, bool merge=false)
	Appends or merges a child InputBlock.

void	merge (InputBlock block)
	Merges `block` into an existing block of the same name, or appends it.

void	add (Option option)
	Appends a single Option to the option list.

void	add (const std::vector< Option > &options)
	Appends a list of Options to the option list.

void	add (const std::string &string, bool merge=false)
	Parses `string` and adds its options and blocks.

void	merge (const std::string &string)
	Parses `string` and merges any duplicate block names.

std::string_view	name () const
	Returns the name of this block.

const std::vector< Option > &	options () const
	Returns const reference to the list of options.

const std::vector< InputBlock > &	blocks () const
	Returns const reference to the list of child blocks.

template<typename T >
T	get (std::string_view key, T default_value) const
	Returns the value of `key`, or `default_value` if not found.

template<typename T = std::string>
std::optional< T >	get (std::string_view key) const
	Returns an optional value for `key`; empty if not found or unset.

bool	has_option (std::string_view key) const
	Returns true if `key` is present in this block's option list, even if unset.

bool	option_is_set (std::string_view key) const
	Returns true if `key` is present and has a non-default, non-empty value.

template<typename T >
T	get (std::initializer_list< std::string > blocks, std::string_view key, T default_value) const
	Returns value of `key` in a sequence of nested blocks, or `default_value`.

template<typename T >
std::optional< T >	get (std::initializer_list< std::string > blocks, std::string_view key) const
	Returns optional value of `key` in a sequence of nested blocks; empty if not found.

std::optional< InputBlock >	getBlock (std::string_view name) const
	Returns an optional copy of the child block named `name`; empty if not found.

std::optional< InputBlock >	getBlock (std::initializer_list< std::string > blocks, std::string_view name) const
	Returns an optional copy of a block found by traversing `blocks` then looking for `name`.

InputBlock	get_block (std::string_view name) const
	Returns a copy of the child block named `name`, or an empty block if not found.

bool	has_block (std::string_view name) const
	Returns true if a child block named `name` exists in this block.

bool	has_block (std::initializer_list< std::string > blocks, std::string_view name) const
	Returns true if a block named `name` exists within the given nested `blocks`.

std::optional< Option >	getOption (std::string_view key) const
	Returns the raw Option struct for `key`; rarely needed directly.

void	print (std::ostream &os=std::cout, int indent_depth=0) const
	Prints the block contents to `os` in Block{option=value;} format.

bool	check (std::initializer_list< std::string > blocks, const std::vector< std::pair< std::string, std::string > > &list, bool print=false) const
	Validates options and sub-blocks against an allowed list.

bool	check (const std::vector< std::pair< std::string, std::string > > &list, bool print=false) const
	Validates options in the current block against `list`. See check() overload for details.

Friends
bool	operator== (InputBlock block, std::string_view name)
	Equality/inequality compare by block name (case-insensitive).

bool	operator== (std::string_view name, InputBlock block)

bool	operator!= (InputBlock block, std::string_view name)

bool	operator!= (std::string_view name, InputBlock block)

Constructor & Destructor Documentation

◆ InputBlock() [1/4]

IO::InputBlock::InputBlock ( )

inline

Default constructor; name will be blank.

◆ InputBlock() [2/4]

IO::InputBlock::InputBlock	(	std::string_view	name,
		std::initializer_list< Option >	options = `{}`
	)

inline

Constructs from a literal list of Option structs.

◆ InputBlock() [3/4]

IO::InputBlock::InputBlock	(	std::string_view	name,
		const std::string &	string_input
	)

inline

Constructs by parsing string_input in Block{option=value;} format.

◆ InputBlock() [4/4]

IO::InputBlock::InputBlock	(	std::string_view	name,
		const std::istream &	file
	)

inline

Constructs by reading and parsing a plain-text file stream.

Member Function Documentation

◆ add() [1/4]

void IO::InputBlock::add	(	InputBlock	block,
		bool	merge = `false`
	)

inline

Appends or merges a child InputBlock.

If merge is false (default), always appends block. If merge is true and a block with the same name already exists, the options from block are merged into the existing block instead.

◆ merge() [1/2]

void IO::InputBlock::merge ( InputBlock block )

inline

Merges block into an existing block of the same name, or appends it.

◆ add() [2/4]

void IO::InputBlock::add ( Option option )

inline

Appends a single Option to the option list.

◆ add() [3/4]

void IO::InputBlock::add ( const std::vector< Option > & options )

inline

Appends a list of Options to the option list.

◆ add() [4/4]

void IO::InputBlock::add	(	const std::string &	string,
		bool	merge = `false`
	)

inline

Parses string and adds its options and blocks.

Comments, whitespace, and quote marks are stripped before parsing. If merge is true, duplicate block names are consolidated rather than appended.

◆ merge() [2/2]

void IO::InputBlock::merge ( const std::string & string )

inline

Parses string and merges any duplicate block names.

◆ name()

std::string_view IO::InputBlock::name ( ) const

inline

Returns the name of this block.

◆ options()

const std::vector< Option > & IO::InputBlock::options ( ) const

inline

Returns const reference to the list of options.

◆ blocks()

const std::vector< InputBlock > & IO::InputBlock::blocks ( ) const

inline

Returns const reference to the list of child blocks.

◆ get() [1/4]

template<typename T >

T IO::InputBlock::get	(	std::string_view	key,
		T	default_value
	)		const

Returns the value of key, or default_value if not found.

If the same key appears more than once, the later occurrence takes precedence. For bool, accepts "true"/"yes"/"y" (case-insensitive). For std::vector<T> or std::array<T,N>, parses a comma-separated list.

Note: Cannot be used with T = const char*; use std::string instead.

◆ get() [2/4]

template<typename T >

std::optional< T > IO::InputBlock::get ( std::string_view key ) const

Returns an optional value for key; empty if not found or unset.

If the same key appears more than once, the later occurrence takes precedence. A value of "default" or empty string is treated as unset (returns nullopt). Supports T = std::vector<T> or std::array<T,N> for comma-separated list values.

◆ has_option()

bool IO::InputBlock::has_option ( std::string_view key ) const

inline

Returns true if key is present in this block's option list, even if unset.

◆ option_is_set()

bool IO::InputBlock::option_is_set ( std::string_view key ) const

inline

Returns true if key is present and has a non-default, non-empty value.

◆ get() [3/4]

template<typename T >

T IO::InputBlock::get	(	std::initializer_list< std::string >	blocks,
		std::string_view	key,
		T	default_value
	)		const

Returns value of key in a sequence of nested blocks, or default_value.

◆ get() [4/4]

template<typename T >

std::optional< T > IO::InputBlock::get	(	std::initializer_list< std::string >	blocks,
		std::string_view	key
	)		const

Returns optional value of key in a sequence of nested blocks; empty if not found.

◆ getBlock() [1/2]

std::optional< InputBlock > IO::InputBlock::getBlock ( std::string_view name ) const

inline

Returns an optional copy of the child block named name; empty if not found.

◆ getBlock() [2/2]

std::optional< InputBlock > IO::InputBlock::getBlock	(	std::initializer_list< std::string >	blocks,
		std::string_view	name
	)		const

inline

Returns an optional copy of a block found by traversing blocks then looking for name.

◆ get_block()

InputBlock IO::InputBlock::get_block ( std::string_view name ) const

inline

Returns a copy of the child block named name, or an empty block if not found.

◆ has_block() [1/2]

bool IO::InputBlock::has_block ( std::string_view name ) const

inline

Returns true if a child block named name exists in this block.

◆ has_block() [2/2]

bool IO::InputBlock::has_block	(	std::initializer_list< std::string >	blocks,
		std::string_view	name
	)		const

inline

Returns true if a block named name exists within the given nested blocks.

◆ getOption()

std::optional< Option > IO::InputBlock::getOption ( std::string_view key ) const

inline

Returns the raw Option struct for key; rarely needed directly.

◆ print()

void IO::InputBlock::print	(	std::ostream &	os = `std::cout`,
		int	indent_depth = `0`
	)		const

inline

Prints the block contents to os in Block{option=value;} format.

◆ check() [1/2]

bool IO::InputBlock::check	(	std::initializer_list< std::string >	blocks,
		const std::vector< std::pair< std::string, std::string > > &	list,
		bool	print = `false`
	)		const

inline

Validates options and sub-blocks against an allowed list.

Check one of the sub-blocks.

Checks each option and sub-block in the nested path blocks against list. If any are not found, a warning is printed along with the nearest spelling suggestion, and false is returned. If print is true, the full list of allowed options and descriptions is always printed.

The list entries are pairs of {option_name, description}. Blocks are identified by a trailing {} in the name, e.g., "SubBlock{}". Descriptions support self-documenting input files.

◆ check() [2/2]

bool IO::InputBlock::check	(	const std::vector< std::pair< std::string, std::string > > &	list,
		bool	print = `false`
	)		const

inline

Validates options in the current block against list. See check() overload for details.

Friends And Related Symbol Documentation

◆ operator==

bool operator==	(	InputBlock	block,
		std::string_view	name
	)

friend

Equality/inequality compare by block name (case-insensitive).

The documentation for this class was generated from the following file:

IO/InputBlock.hpp

ok

Public Member Functions

Friends

Constructor & Destructor Documentation

◆ InputBlock() [1/4]

◆ InputBlock() [2/4]

◆ InputBlock() [3/4]

◆ InputBlock() [4/4]

Member Function Documentation

◆ add() [1/4]

◆ merge() [1/2]

◆ add() [2/4]

◆ add() [3/4]

◆ add() [4/4]

◆ merge() [2/2]

◆ name()

◆ options()

◆ blocks()

◆ get() [1/4]

◆ get() [2/4]

◆ has_option()

◆ option_is_set()

◆ get() [3/4]

◆ get() [4/4]

◆ getBlock() [1/2]

◆ getBlock() [2/2]

◆ get_block()

◆ has_block() [1/2]

◆ has_block() [2/2]

◆ getOption()

◆ print()

◆ check() [1/2]

◆ check() [2/2]

Friends And Related Symbol Documentation

◆ operator==