Class holding a set of key-value properties. More...

#include <falaise/config/property_set.h>

Public Member Functions
	property_set ()=default
	Default constructor. More...

	property_set (datatools::properties const &ps)
	Construct from an existing datatools::properties. More...

bool	is_empty () const
	Returns true if no key-value pairs are held. More...

std::vector< std::string >	get_names () const
	Returns a vector of all keys in the property_set. More...

bool	has_key (std::string const &key) const
	Returns true if the property_set stores a pair with the supplied key. More...

bool	is_key_to_property (std::string const &key) const
	Returns true if the key's value is a property/atom. More...

bool	is_key_to_sequence (std::string const &key) const
	Returns true if the keys's value is sequence. More...

bool	is_key_to_property_set (std::string const &key) const
	Returns true if the key's value is a property_set. More...

std::string	to_string () const
	Returns a string representation of the property_set. More...

template<typename T >
T	get (std::string const &key) const
	Return the value of type T held at supplied key. More...

template<typename T >
T	get (std::string const &key, T const &default_value) const

	operator datatools::properties () const
	Convert back to datatools::properties. More...

template<typename T >
void	put (std::string const &key, T const &value)
	Insert key-value pair in property_set. More...

template<typename T >
void	put_or_replace (std::string const &key, T const &value)
	Insert key-value pair in property_set, replacing value if key exists. More...

bool	erase (std::string const &key)
	Erase the name-value pair stored at key. More...

template<>
property_set	get (std::string const &key) const

template<>
property_set	get (std::string const &key, property_set const &default_value) const

template<>
void	put (std::string const &key, property_set const &value)

template<>
void	put_or_replace (std::string const &key, property_set const &value)

template<>
void	put_impl_ (std::string const &key, falaise::config::path const &value)
	Private specialization of put_impl_ for path. More...

template<>
void	put_impl_ (std::string const &key, falaise::config::quantity const &value)
	Private specialization of put_impl_ for quantity. More...

template<>
void	get_impl_ (std::string const &key, falaise::config::path &result) const

template<>
void	get_impl_ (std::string const &key, falaise::config::quantity &result) const

Detailed Description

Class holding a set of key-value properties.

Provides a convenient adaptor interface over datatools::properties, targeted at developers of modules for Falaise needing key-value storage and validation of input parameters. It may be used directly as

falaise::property_set ps{};
// Store an integer at key "a"
ps.put("a",2);
// Get the integer
int x = ps.get<int>("a");
// Replace the integer with a double
ps.put("a",3.14);
// Get a string, setting a default value in case key "b" doesn't exist
std::string s = ps.get<std::string>("b", "hello");
std::cout << s << std::endl; // prints "hello"

or it can be constructed from an existing instance of datatools::properties

void example(datatools::properties const& x) {
  falaise::property_set ps{x};
  // ... use ps ...
}

or from a datatools::properties file

void example(std::string const& file) {
  falaise::property_set ps{};
  falaise::make_property_set(file, ps);
  // ... use ps ...
}

Storage and retrieval of parameters is typesafe in the sense that:

You can only put values that are of type
- int
- double
- bool
- std::string
- falaise::config::path
- falaise::config::quantity_t
  - Plus any type listed in System of Units
- falaise::config::property_set
- std::vector<int>
- std::vector<double>
- std::vector<bool>
- std::vector<std::string>
You can only get values of the above types, and a wrong_type_error will be thrown if you try to retrieve a value with a different type, e.g
ps.put("a", 2);
double x = ps.get<double>("a"); // throws wrong_type_error

Support for path and quantity_t is provided to support validation of input configuration scripts. These types model the path and dimension decorators for properties parameters:

# this is a true filesystem path
foo : string as path = "${HOME}/something"
# this is a true physical quantity with dimension "length"
bar : real as length = 3.14 m

When extracting parameters, you can ensure that that you have a true path or physical quantity of the right dimension:

void configure_me(property_set const& ps) {
  // throws wrong_type_error if value at "foo" is not a path
  auto foo = ps.get<falaise::config::path>("foo");
  // throws wrong_type_error if value at bar is not a physical quantity with 'length' dimension
  auto bar = ps.get<falaise::config::length_t>("bar");
  ...
}

Support for put and get of property_set values is provided to support datatools::properties constructs of the form:

plain : string = "A plain property"
table.foo : string = "A string property in a 'table'"
table.bar : int = 42

The foo and bar properties an be extracted either by their full keys:

auto foo = ps.get<std::string>("table.foo");

auto bar = ps.get<int>("table.bar);

or by getting the table key as a property_set, then its properties which will be stored using their subkey names:

auto table = ps.get<falaise::config::property_set>("table");
auto foo = ps.get<std::string>("foo");
auto bar = ps.get<int>("bar);

This can be extended to further levels of nesting if required. However, note that datatools::properties configuration of the form:

table : string = "Not a valid table"
table.x : int = 11
table.y : int = 22

are not considered get-able as property_sets. This is due to the ambiguity of the table key which property_set regards as an atomic property of type std::string. Here, the table.x and table.y` keys can be extracted only via their fully qualified keys. It is therefore strongly recommended that you structure your configuration in the "pure table" form above for clarity and ease of use.

The default value form of get can be used to implement optional configuration, for example

void configure_me(property_set const& ps) {
  // throws missing_key_error if ps doesn't have "foo"
  auto requiredParam = ps.get<int>("foo");
  // sets optionalParam to the value held at "answer", or 42 if ps doesn't have an "answer" key
  auto optionalParam = ps.get<int>("answer",42);
  ...
}

Combined, these various ways of using property_set allow simple and reliable usage for configuration and configuration validation in Falaise modules.

See also: path; quantity; datatools::properties; datatools::units

Constructor & Destructor Documentation

◆ property_set() [1/2]

falaise::config::property_set::property_set ( )

default

Default constructor.

◆ property_set() [2/2]

falaise::config::property_set::property_set ( datatools::properties const & ps )

Construct from an existing datatools::properties.

Parameters

[in] ps properties

Member Function Documentation

◆ erase()

bool falaise::config::property_set::erase ( std::string const & key )

Erase the name-value pair stored at key.

Parameters

[in] key key for pair to erase

Returns: true if the exists and was erased, false if the key does not exist

◆ get() [1/4]

template<typename T >

T falaise::config::property_set::get ( std::string const & key ) const

Return the value of type T held at supplied key.

Template Parameters

T	type of value to be returned

Parameters

[in] key key for value to find

Returns: value held at key

Exceptions

missing_key_error	if key is not found
wrong_type_error	if value at key is not of type T

◆ get() [2/4]

template<typename T >

T falaise::config::property_set::get	(	std::string const &	key,
		T const &	default_value
	)		const

Return the value of type T associated with key, or a default if the key is not present

Template Parameters

T	type of value to be returned

Parameters

[in]	key	key for value to find
[in]	default_value	value to return if key is not found

Exceptions

wrong_type_error if key is found and associated value is not type T

◆ get() [3/4]

template<>

property_set falaise::config::property_set::get ( std::string const & key ) const

inline

◆ get() [4/4]

template<>

property_set falaise::config::property_set::get	(	std::string const &	key,
		property_set const &	default_value
	)		const

inline

◆ get_impl_() [1/2]

template<>

void falaise::config::property_set::get_impl_	(	std::string const &	key,
		falaise::config::path &	result
	)		const

inline

◆ get_impl_() [2/2]

template<>

void falaise::config::property_set::get_impl_	(	std::string const &	key,
		falaise::config::quantity &	result
	)		const

inline

◆ get_names()

std::vector<std::string> falaise::config::property_set::get_names ( ) const

Returns a vector of all keys in the property_set.

◆ has_key()

bool falaise::config::property_set::has_key ( std::string const & key ) const

Returns true if the property_set stores a pair with the supplied key.

A nested key, e.g. foo.bar, may be supplied.

Parameters

[in] key name of key to check for existence

◆ is_empty()

bool falaise::config::property_set::is_empty ( ) const

Returns true if no key-value pairs are held.

◆ is_key_to_property()

bool falaise::config::property_set::is_key_to_property ( std::string const & key ) const

Returns true if the key's value is a property/atom.

A nested key, e.g. foo.bar, may be supplied.

Parameters

[in] key name of the key to check

◆ is_key_to_property_set()

bool falaise::config::property_set::is_key_to_property_set ( std::string const & key ) const

Returns true if the key's value is a property_set.

A nested key, e.g. foo.bar, may be supplied.

A key is only considered to have a property_set value if it only exists as a prefix to a set of nested keys, e.g.

pure.foo : int = 1
pure.bar : int = 2
pure.nested.x : int = 11
pure.nested.y : int = 22

Keys pure and pure.nested are considered as property_set values. In mixed properties/values such as

bad : int = 1

bad.foo : int = 2

bad is not considered as a property_set.

Parameters

[in] key name of the key to check

◆ is_key_to_sequence()

bool falaise::config::property_set::is_key_to_sequence ( std::string const & key ) const

Returns true if the keys's value is sequence.

A nested key, e.g. foo.bar, may be supplied.

Parameters

[in] key name of the key to check

◆ operator datatools::properties()

falaise::config::property_set::operator datatools::properties ( ) const

Convert back to datatools::properties.

◆ put() [1/2]

template<typename T >

void falaise::config::property_set::put	(	std::string const &	key,
		T const &	value
	)

Insert key-value pair in property_set.

Copies of the key and value are stored

Template Parameters

T	type of value to store

Parameters

[in]	key	key to store value at
[in]	value	value to store

Exceptions

wrong_type_error	if value's type is not storable
existing_key_error	if key is already stored

◆ put() [2/2]

template<>

void falaise::config::property_set::put	(	std::string const &	key,
		property_set const &	value
	)

inline

◆ put_impl_() [1/2]

template<>

void falaise::config::property_set::put_impl_	(	std::string const &	key,
		falaise::config::path const &	value
	)

inline

Private specialization of put_impl_ for path.

◆ put_impl_() [2/2]

template<>

void falaise::config::property_set::put_impl_	(	std::string const &	key,
		falaise::config::quantity const &	value
	)

inline

Private specialization of put_impl_ for quantity.

◆ put_or_replace() [1/2]

template<typename T >

void falaise::config::property_set::put_or_replace	(	std::string const &	key,
		T const &	value
	)

Insert key-value pair in property_set, replacing value if key exists.

Copies of the key and value are stored. For existing keys the value will be overwritten, and the types of the old and new value do not need to match.

Template Parameters

T	type of value to store

Parameters

[in]	key	key to store value at
[in]	value	value to store

Exceptions

wrong_type_error if value's type is not storable

◆ put_or_replace() [2/2]

template<>

void falaise::config::property_set::put_or_replace	(	std::string const &	key,
		property_set const &	value
	)

inline

◆ to_string()

std::string falaise::config::property_set::to_string ( ) const

Returns a string representation of the property_set.

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

falaise/config/property_set.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ property_set() [1/2]

◆ property_set() [2/2]

Member Function Documentation

◆ erase()

◆ get() [1/4]

◆ get() [2/4]

◆ get() [3/4]

◆ get() [4/4]

◆ get_impl_() [1/2]

◆ get_impl_() [2/2]

◆ get_names()

◆ has_key()

◆ is_empty()

◆ is_key_to_property()

◆ is_key_to_property_set()

◆ is_key_to_sequence()

◆ operator datatools::properties()

◆ put() [1/2]

◆ put() [2/2]

◆ put_impl_() [1/2]

◆ put_impl_() [2/2]

◆ put_or_replace() [1/2]

◆ put_or_replace() [2/2]

◆ to_string()