OptionSet Class Reference

A custom map-like data structure. The keys are strings, and the values can be nonhomogeneously typed. More...

Detailed Description

A custom map-like data structure. The keys are strings, and the values can be nonhomogeneously typed.

#include <OptionSet.h>

Classes
struct	Metadata

Public Types
using	map_type = std::map<std::string, std::unique_ptr<OptionBase>, std::less<>>
	The type of the map that we store internally.
using	iterator = map_type::iterator
	Option map iterator.
using	const_iterator = map_type::const_iterator
	Constant option map iterator.

Public Member Functions
	OptionSet ()=default
	OptionSet (const OptionSet &)
	OptionSet (OptionSet &&) noexcept
OptionSet &	operator= (const OptionSet &)
OptionSet &	operator= (OptionSet &&) noexcept
virtual	~OptionSet ()=default
const std::string &	name () const
	A readonly reference to the option set's name.
std::string &	name ()
	A writable reference to the option set's name.
const std::string &	type () const
	A readonly reference to the option set's type.
std::string &	type ()
	A writable reference to the option set's type.
const std::string &	path () const
	A readonly reference to the option set's path.
std::string &	path ()
	A writable reference to the option set's path.
const std::string &	doc () const
	A readonly reference to the option set's docstring.
std::string &	doc ()
	A writable reference to the option set's docstring.
const std::string &	section () const
	A readonly reference to the option set's section.
std::string &	section ()
	A writable reference to the option set's section.
bool	contains (const std::string &) const
bool	user_specified (const std::string &name) const
bool	defined (const std::string &name) const
void	suppress (const std::string &name)
	Suppress an option.
std::size_t	size () const
void	clear ()
	Clear internal data structures & frees any allocated memory.
std::string	to_str () const
	Print the contents.
template<typename T>
T	get (const std::string &) const
const OptionBase &	get (const std::string &) const
	Get a const reference to the specified option value.
template<typename K, typename V>
std::map< K, V >	get_map (const std::string &, const std::string &) const
	Get two options and bind them to form a map.
template<typename T, FType f = FType::NONE>
void	add (const std::string &name, const T &default_value, std::string doc)
	Create an option with its default value and its docstring.
template<typename T, FType f = FType::NONE>
void	add (const std::string &name, std::string doc)
	Create a required option with its docstring, without a default value. User must specify a value for this option from the input file.
template<typename T, FType f = FType::NONE>
void	add_optional (const std::string &name, std::string doc)
	Create an optional option with its docstring, without a default value.
template<typename T>
void	add_private (const std::string &name, const T &default_value)
	Create a private option with its default value.
template<typename T>
void	set (const std::string &name, const T &value)
	Set an option.
template<typename T>
void	set_private (const std::string &name, const T &value)
	Set a private option.
iterator	begin ()
	Iterator pointing to the beginning of the set of options.
const_iterator	begin () const
	Iterator pointing to the beginning of the set of options.
iterator	end ()
	Iterator pointing to the end of the set of options.
const_iterator	end () const
	Iterator pointing to the end of the set of options.
void	operator+= (const OptionSet &source)
void	operator+= (OptionSet &&source)
void	add_input (const std::string &, const VariableName &, std::string)
void	add_input (const std::string &, std::string)
void	add_optional_input (const std::string &, std::string)
void	add_output (const std::string &, const VariableName &, std::string)
	Convenient methods to add output variable.
void	add_output (const std::string &, std::string)
void	add_optional_output (const std::string &, std::string)
template<typename T>
void	add_parameter (const std::string &, const TensorName< T > &, std::string)
	Convenient methods to add parameter.
template<typename T>
void	add_parameter (const std::string &, std::string)
template<typename T>
void	add_buffer (const std::string &, const TensorName< T > &, std::string)
	Convenient methods to add buffer.
template<typename T>
void	add_buffer (const std::string &, std::string)

Protected Attributes
struct neml2::OptionSet::Metadata	_metadata
map_type	_values
	Data structure to map names with values.

Member Typedef Documentation

const_iterator

using const_iterator = map_type::const_iterator

Constant option map iterator.

iterator

using iterator = map_type::iterator

Option map iterator.

map_type

using map_type = std::map<std::string, std::unique_ptr<OptionBase>, std::less<>>

The type of the map that we store internally.

Constructor & Destructor Documentation

OptionSet() [1/3]

OptionSet ( )

default

OptionSet() [2/3]

OptionSet

(

const OptionSet &

)

OptionSet() [3/3]

OptionSet ( OptionSet && )

noexcept

~OptionSet()

virtual ~OptionSet ( )

virtualdefault

Member Function Documentation

add() [1/2]

template<typename T, FType F>

void add	(	const std::string &	name,
		const T &	default_value,
		std::string	doc )

Create an option with its default value and its docstring.

Throws an exception if the option already exists.

Calling this method sets the following metadata for the option:

• required: false
• suppressed: false
• user_specified: false
• defined: true

Note that later on when a Parser parses the input file, if the user has specified a value for this option, the option value will be overwritten and the user_specified flag will be set to true. If the user has not specified a value for this option, the default value will be used.

Template Parameters

T	Type of the option value
f	Option type (e.g., parameter, buffer, input, output)

Parameters

name	The name of the option
default_value	The default value to set
doc	The docstring for the option

add() [2/2]

template<typename T, FType F>

void add	(	const std::string &	name,
		std::string	doc )

Create a required option with its docstring, without a default value. User must specify a value for this option from the input file.

Throws an exception if the option already exists.

Calling this method sets the following metadata for the option:

• required: true
• suppressed: false
• user_specified: false
• defined: false

Note that later on when a Parser parses the input file, if the user has specified a value for this option, the option value will be overwritten and both the user_specified flag and the defined flag will be set to true. The Parser should consider it an error if the user has not specified a value for this option.

Template Parameters

T	Type of the option value
f	Option type (e.g., parameter, buffer, input, output)

Parameters

name	The name of the option
doc	The docstring for the option

add_buffer() [1/2]

template<typename T>

void add_buffer	(	const std::string &	name,
		const TensorName< T > &	tensor_name,
		std::string	doc )

Convenient methods to add buffer.

add_buffer() [2/2]

template<typename T>

void add_buffer	(	const std::string &	name,
		std::string	doc )

add_input() [1/2]

void add_input	(	const std::string &	,
		const VariableName &	,
		std::string	)

Convenient methods to add input variable

add_input() [2/2]

void add_input	(	const std::string &	,
		std::string	)

add_optional()

template<typename T, FType F>

void add_optional	(	const std::string &	name,
		std::string	doc )

Create an optional option with its docstring, without a default value.

Throws an exception if the option already exists.

Calling this method sets the following metadata for the option:

• required: false
• suppressed: false
• user_specified: false
• defined: false

Note that later on when a Parser parses the input file, if the user has specified a value for this option, the option value will be overwritten and both the user_specified flag and the defined flag will be set to true. If the user has not specified a value for this option, the option is considered undefined and an exception will be thrown when attempting to retrieve the option value.

Template Parameters

T	Type of the option value
f	Option type (e.g., parameter, buffer, input, output)

Parameters

name	The name of the option
doc	The docstring for the option

add_optional_input()

void add_optional_input	(	const std::string &	,
		std::string	)

add_optional_output()

void add_optional_output	(	const std::string &	,
		std::string	)

add_output() [1/2]

void add_output	(	const std::string &	,
		const VariableName &	,
		std::string	)

Convenient methods to add output variable.

add_output() [2/2]

void add_output	(	const std::string &	,
		std::string	)

add_parameter() [1/2]

template<typename T>

void add_parameter	(	const std::string &	name,
		const TensorName< T > &	tensor_name,
		std::string	doc )

Convenient methods to add parameter.

add_parameter() [2/2]

template<typename T>

void add_parameter	(	const std::string &	name,
		std::string	doc )

add_private()

template<typename T>

void add_private	(	const std::string &	name,
		const T &	default_value )

Create a private option with its default value.

Throws an exception if the option already exists.

Calling this method sets the following metadata for the option:

• required: false
• suppressed: true
• user_specified: false
• defined: true

Template Parameters

T	Type of the option value

Parameters

name	The name of the option
default_value	The default value to set

begin() [1/2]

iterator begin

(

)

Iterator pointing to the beginning of the set of options.

begin() [2/2]

const_iterator begin

(

)

const

Iterator pointing to the beginning of the set of options.

clear()

void clear

(

)

Clear internal data structures & frees any allocated memory.

contains()

bool contains

(

const std::string &

)

const

Returns

true if an option with a specified name exists, false otherwise.

defined()

bool defined

(

const std::string &

name

)

const

Returns

true if an option is defined (i.e., value has been set either from the input file or programmatically), false otherwise.

doc() [1/2]

std::string & doc ( )

inline

A writable reference to the option set's docstring.

doc() [2/2]

const std::string & doc ( ) const

inline

A readonly reference to the option set's docstring.

end() [1/2]

iterator end

(

)

Iterator pointing to the end of the set of options.

end() [2/2]

const_iterator end

(

)

const

Iterator pointing to the end of the set of options.

get() [1/2]

const OptionBase & get

(

const std::string &

)

const

Get a const reference to the specified option value.

get() [2/2]

template<typename T>

T get

(

const std::string &

name

)

const

Returns

A copy of the specified option value. Requires, of course, that the option exists.

get_map()

template<typename K, typename V>

std::map< K, V > get_map	(	const std::string &	key_option,
		const std::string &	value_option ) const

Get two options and bind them to form a map.

The two options are expected to be of type std::vector<K> and std::vector<V>, respectively. Keys shall be unique. Otherwise, an exception is thrown.

Template Parameters

K	Key type
V	Value type

Returns

std::map<K, V>

name() [1/2]

std::string & name ( )

inline

A writable reference to the option set's name.

name() [2/2]

const std::string & name ( ) const

inline

A readonly reference to the option set's name.

operator+=() [1/2]

void operator+=

(

const OptionSet &

source

)

Addition/Assignment operator. Inserts copies of all options from source. Any options of the same name already in this are replaced.

Note

This operator does not modify the metadata of the option set.

operator+=() [2/2]

void operator+=

(

OptionSet &&

source

)

operator=() [1/2]

OptionSet & operator=

(

const OptionSet &

)

operator=() [2/2]

OptionSet & operator= ( OptionSet && )

noexcept

path() [1/2]

std::string & path ( )

inline

A writable reference to the option set's path.

path() [2/2]

const std::string & path ( ) const

inline

A readonly reference to the option set's path.

section() [1/2]

std::string & section ( )

inline

A writable reference to the option set's section.

section() [2/2]

const std::string & section ( ) const

inline

A readonly reference to the option set's section.

set()

template<typename T>

void set	(	const std::string &	name,
		const T &	value )

Set an option.

The option must already exist. Otherwise, an exception is thrown. The option value is overridden if it already exists.

Calling this method sets the following metadata for the option:

• user_specified: false
• defined: true

Template Parameters

T	Type of the option value

Parameters

name	The name of the option
value	The value to set

set_private()

template<typename T>

void set_private	(	const std::string &	name,
		const T &	value )

Set a private option.

The option must already exist. Otherwise, an exception is thrown. The option value is overridden if it already exists.

Calling this method sets the following metadata for the option:

• user_specified: false
• defined: true

Template Parameters

T	Type of the option value

Parameters

name	The name of the option
value	The value to set

size()

std::size_t size ( ) const

inline

Returns

The total number of options

suppress()

void suppress

(

const std::string &

name

)

Suppress an option.

to_str()

std::string to_str

(

)

const

Print the contents.

type() [1/2]

std::string & type ( )

inline

A writable reference to the option set's type.

type() [2/2]

const std::string & type ( ) const

inline

A readonly reference to the option set's type.

user_specified()

bool user_specified

(

const std::string &

name

)

const

Returns

true if an option is specified by the user (i.e., from the input file), false otherwise.

Member Data Documentation

_metadata

struct neml2::OptionSet::Metadata _metadata

protected

_values

map_type _values

protected

Data structure to map names with values.