Configuration#

constellation::config Namespace#

using constellation::config::value_t = std::variant<std::monostate, bool, std::int64_t, double, std::string, std::chrono::system_clock::time_point, std::vector<bool>, std::vector<char>, std::vector<std::int64_t>, std::vector<double>, std::vector<std::string>, std::vector<std::chrono::system_clock::time_point>>#

Value type for Dictionary using std::variant

Allowed types: nil, bool, int64, double, string, time point, vectors of bool, int64, double, string, time point, bytes (vector of char)

class Configuration#
#include <constellation/core/config/Configuration.hpp>

Generic configuration object storing keys.

The configuration holds a set of keys with arbitrary values that are internally stored as std::variant.

Public Types

enum class Group : std::uint8_t#

Values:

enumerator ALL#

All configuration key-value pairs, both user and internal

enumerator USER#

Configuration key-value pairs intended for framework users

enumerator INTERNAL#

Configuration key-value pairs intended for internal framework usage

enum class Usage : std::uint8_t#

Values:

enumerator ANY#

Both used and unused key-value pairs

enumerator USED#

Only used key-value pairs

enumerator UNUSED#

Only unused key-value pairs

Public Functions

Configuration() = default#

Construct an empty configuration object.

~Configuration() = default#
Configuration(const Dictionary &dict, bool mark_used = false)#

Construct a configuration object from a dictionary.

Parameters:

  • dict – Dictionary to construct configuration object from

  • mark_used – Whether to mark the key-value pairs in the dict as used

inline bool has(const std::string &key) const#

Check if key is defined.

Note

Keys are handled case-insensitively

Parameters:

key – Key to check for existence

Returns:

True if key exists, false otherwise

std::size_t count(std::initializer_list<std::string> keys) const#

Check how many of the given keys are defined.

This is useful to check if two or more conflicting configuration keys that are defined.

Note

Keys are handled case-insensitively

Parameters:

keys – Keys to check for existence

Returns:

number of existing keys from the given list

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

Get value of a key in requested type.

Note

Keys are handled case-insensitively

Parameters:

key – Key to get value of

Throws:
Returns:

Value of the key in the type of the requested template parameter

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

Get value of a key in requested type or default value if it does not exists.

Note

Keys are handled case-insensitively

Parameters:

  • key – Key to get value of

  • def – Default value to set if key is not defined

Throws:

  • InvalidKeyError – If the conversion to the requested type did not succeed

  • InvalidKeyError – If an overflow happened while converting the key

Returns:

Value of the key in the type of the requested template parameter or the default value if the key does not exists

template<typename T>
inline std::vector<T> getArray(const std::string &key) const#

Get values for a key containing an array.

Note

Keys are handled case-insensitively

Parameters:

key – Key to get values of

Throws:

  • MissingKeyError – If the requested key is not defined

  • InvalidKeyError – If the conversion to the requested type did not succeed

  • InvalidKeyError – If an overflow happened while converting the key

Returns:

List of values in the array in the requested template parameter

template<typename T>
std::vector<T> getArray(const std::string &key, const std::vector<T> &def)#

Get values for a key containing an array or default array if it does not exists.

Note

Keys are handled case-insensitively

Parameters:

  • key – Key to get values of

  • def – Default value array to set if key is not defined

Throws:

  • InvalidKeyError – If the conversion to the requested type did not succeed

  • InvalidKeyError – If an overflow happened while converting the key

Returns:

List of values in the array in the requested template parameter or the default array if the key does not exist

std::string getText(const std::string &key) const#

Get literal value of a key as string.

Note

This function does also not remove quotation marks in strings, Keys are handled case-insensitively

Parameters:

key – Key to get values of

Returns:

Literal value of the key

std::filesystem::path getPath(const std::string &key, bool check_exists = false) const#

Get absolute path to file with paths relative to the configuration.

Note

Keys are handled case-insensitively

Parameters:

  • key – Key to get path of

  • check_exists – If the file should be checked for existence (if yes always returns a canonical path)

Throws:

InvalidValueError – If the path did not exists while the check_exists parameter is given

Returns:

Absolute path to a file

std::filesystem::path getPathWithExtension(const std::string &key, const std::string &extension, bool check_exists = false) const#

Get absolute path to file with paths relative to the configuration.

Note

Keys are handled case-insensitively

Parameters:

  • key – Key to get path of

  • extension – File extension to be added to path if not present

  • check_exists – If the file should be checked for existence (if yes always returns a canonical path)

Throws:

InvalidValueError – If the path did not exists while the check_exists parameter is given

Returns:

Absolute path to a file

std::vector<std::filesystem::path> getPathArray(const std::string &key, bool check_exists = false) const#

Get array of absolute paths to files with paths relative to the configuration.

Note

Keys are handled case-insensitively

Parameters:

  • key – Key to get path of

  • check_exists – If the files should be checked for existence (if yes always returns a canonical path)

Throws:

InvalidValueError – If the path did not exists while the check_exists parameter is given

Returns:

List of absolute path to all the requested files

template<typename T>
void set(const std::string &key, const T &val, bool mark_used = false)#

Set value for a key in a given type.

Note

Keys are handled case-insensitively and stored in lower case.

Parameters:

  • key – Key to set value of

  • val – Value to assign to the key

  • mark_used – Flag whether key should be marked as “used” directly

template<typename T>
inline void setArray(const std::string &key, const std::vector<T> &val, bool mark_used = false)#

Set list of values for a key in a given type.

Note

Keys are handled case-insensitively and stored in lower case.

Parameters:

  • key – Key to set values of

  • val – List of values to assign to the key

  • mark_used – Flag whether key should be marked as “used” directly

template<typename T>
void setDefault(const std::string &key, const T &val)#

Set default value for a key only if it is not defined yet.

Note

This marks the default key as “used” automatically

Note

Keys are handled case-insensitively and stored in lower case.

Parameters:

  • key – Key to possible set value of

  • val – Value to assign if the key is not defined yet

template<typename T>
void setDefaultArray(const std::string &key, const std::vector<T> &val)#

Set default list of values for a key only if it is not defined yet.

Note

This marks the default key as “used” automatically

Note

Keys are handled case-insensitively and stored in lower case.

Parameters:

  • key – Key to possible set values of

  • val – List of values to assign to the key if the key is not defined yet

void setAlias(const std::string &new_key, const std::string &old_key, bool warn = false)#

Set alias name for an already existing key.

Note

This marks the old key as “used” automatically. Keys are handled case-insensitively and stored in lower case.

Parameters:

  • new_key – New alias to be created

  • old_key – Key the alias is created for

  • warn – Optionally print a warning message to notify of deprecation

std::size_t size(Group group = Group::ALL, Usage usage = Usage::ANY) const#

Get number of key-value pairs for specific group and usage setting.

Parameters:

  • group – Enum to restrict group of key-value pairs to include

  • usage – Enum to restrict usage status of key-value pairs to include

Returns:

Number of key-value pairs

Dictionary getDictionary(Group group = Group::ALL, Usage usage = Usage::ANY) const#

Get dictionary with key-value pairs for specific group and usage setting.

Parameters:

  • group – Enum to restrict group of key-value pairs to include

  • usage – Enum to restrict usage status of key-value pairs to include

Returns:

Dictionary containing the key-value pairs

void update(const Configuration &other)#

Update with keys from another configuration, potentially overriding keys in this configuration.

Note

This function only updates values that are actually used

Parameters:

other – Configuration with updated values

class ConfigurationError : public constellation::utils::RuntimeError#
#include <constellation/core/config/exceptions.hpp>

Base class for all configurations exceptions in the framework.

Subclassed by constellation::config::InvalidCombinationError, constellation::config::InvalidTypeError, constellation::config::InvalidValueError, constellation::config::MissingKeyError

class Dictionary : public std::map<std::string, Value>#
#include <constellation/core/config/Dictionary.hpp>

Dictionary type with serialization functions for MessagePack and ZeroMQ

Public Functions

void msgpack_pack(msgpack::packer<msgpack::sbuffer> &msgpack_packer) const#

Pack dictionary with msgpack

void msgpack_unpack(const msgpack::object &msgpack_object)#

Unpack dictionary with msgpack

message::PayloadBuffer assemble() const#

Assemble dictionary via msgpack to message payload

std::string to_string() const#

Convert dictionary to human readable string.

Returns:

String with one line for each key-value pair starting \n

Public Static Functions

static Dictionary disassemble(const message::PayloadBuffer &message)#

Disassemble dictionary from message payload

class InvalidCombinationError : public constellation::config::ConfigurationError#
#include <constellation/core/config/exceptions.hpp>

Indicates an error with a combination of configuration keys.

Should be raised if a disallowed combination of keys is used, such as two optional parameters which cannot be used at the same time because they contradict each other.

Public Functions

InvalidCombinationError(const Configuration &config, std::initializer_list<std::string> keys, const std::string &reason = "")#

Construct an error for an invalid combination of keys.

Parameters:

  • config – Configuration object containing the problematic key combination

  • keys – List of names of the conflicting keys

  • reason – Reason why the key combination is invalid (empty if no explicit reason)

class InvalidTypeError : public constellation::config::ConfigurationError#
#include <constellation/core/config/exceptions.hpp>

Indicates a problem converting the value of a configuration key to the value it should represent.

Public Functions

inline InvalidTypeError(std::string_view key, std::string_view vtype, std::string_view type, std::string_view reason = "")#

Construct an error for a value with an invalid type.

Parameters:

  • key – Name of the corresponding key

  • vtype – Type of the stored value

  • type – Type the value should have been converted to

  • reason – Reason why the conversion failed

class InvalidValueError : public constellation::config::ConfigurationError#
#include <constellation/core/config/exceptions.hpp>

Indicates an error with the contents of value.

Should be raised if the data contains valid data for its type (otherwise an InvalidTypeError should have been raised earlier), but the value is not in the range of allowed values.

Public Functions

InvalidValueError(const Configuration &config, const std::string &key, const std::string &reason = "")#

Construct an error for an invalid value.

Parameters:

  • config – Configuration object containing the invalid value

  • key – Name of the problematic key

  • reason – Reason why the value is invalid (empty if no explicit reason)

InvalidValueError(const std::string &value, const std::string &key, const std::string &reason = "")#

Construct an error for an invalid value.

Parameters:

  • value – invalid value

  • key – Name of the problematic key

  • reason – Reason why the value is invalid (empty if no explicit reason)

class List : public std::vector<Value>#
#include <constellation/core/config/Dictionary.hpp>

List type with serialization functions for MessagePack

Public Functions

void msgpack_pack(msgpack::packer<msgpack::sbuffer> &msgpack_packer) const#

Pack list with msgpack

void msgpack_unpack(const msgpack::object &msgpack_object)#

Unpack list with msgpack

message::PayloadBuffer assemble() const#

Assemble list via msgpack to message payload

std::string to_string() const#

Convert list to human readable string.

Returns:

String with one line for each value starting \n

Public Static Functions

static List disassemble(const message::PayloadBuffer &message)#

Disassemble list from message payload

class MissingKeyError : public constellation::config::ConfigurationError#
#include <constellation/core/config/exceptions.hpp>

Informs of a missing key that should have been defined.

Public Functions

inline MissingKeyError(const std::string &key)#

Construct an error for a missing key.

Parameters:

key – Name of the missing key

class Value : public value_t#
#include <constellation/core/config/Value.hpp>

Augmented std::variant with MsgPack packer and unpacker routines.

Public Functions

template<typename T>
Value &operator=(const T &value)#

Assignment operator for better handling, automatic conversion of variant types to Value.

Parameters:

value – Value to be set

std::string str() const#

Convert value to string representation.

Returns:

String representation of the value

template<typename T>
T get() const#

Get value in requested type.

Throws:

  • invalid_argument – If the conversion to the requested type did not succeed

  • bad_variant_access – If no suitable conversion was found and direct access did not succeed

Returns:

Value in the type of the requested template parameter

inline std::string demangle() const#

Demangle type held by the Value.

Returns:

Demangled name of the currently held type

void msgpack_pack(msgpack::packer<msgpack::sbuffer> &msgpack_packer) const#

Pack value with msgpack

void msgpack_unpack(const msgpack::object &msgpack_object)#

Unpack value with msgpack

message::PayloadBuffer assemble() const#

Assemble list via msgpack to message payload

Public Static Functions

template<typename T>
static inline Value set(const T &value)#

Set value from provided type.

Throws:

  • std::invalid_argument – If the conversion from the provided type did not succeed

  • std::bad_variant_access – If no suitable conversion was found and direct assignment did not succeed

Returns:

Value

static Value disassemble(const message::PayloadBuffer &message)#

Disassemble list from message payload

On this page
Edit on GitLab