Configuration#

constellation::config Namespace#

using constellation::config::ScalarVariant = std::variant<bool, std::int64_t, double, std::string, std::chrono::system_clock::time_point>#
using constellation::config::ScalarMonostateVariant = utils::monostate_variant_t<ScalarVariant>#
using constellation::config::ArrayVariant = utils::vector_variant_t<ScalarVariant>#
using constellation::config::ArrayMonostateVariant = utils::monostate_variant_t<ArrayVariant>#
using constellation::config::CompositeVariant = std::variant<Scalar, Array, Dictionary>#
template<typename E>
E constellation::config::config_enum_cast(std::string_view value)#

Helper to cast string value to enum.

Parameters:

value – String with enum value name

Throws:

std::invalid_argument – If the string value is not a valid enum value name

Returns:

Enum in the requested type

template<typename T, typename U>
T constellation::config::config_numeric_cast(U value)#

Helper to cast one integer to another.

Parameters:

value – Integer value to cast

Throws:

std::invalid_argument – If the integer value is out of range for the requested type

Returns:

Integer in the requested type

class Array : public ArrayMonostateVariant#
#include <constellation/core/config/value_types.hpp>

Array of scalar values.

Public Functions

Array() = default#

Construct a new empty array.

template<typename T>
Array(std::initializer_list<T> init)#

Construct a new array from an initializer list.

Parameters:

init – Initializer list for array

template<typename R>
Array(const R &range)#

Construct a new array from a range.

Parameters:

range – Range to be set for the new array

template<typename R>
Array &operator=(const R &other)#

Assignment operator

template<typename R>
bool operator==(const R &other) const#

Equality operator

template<typename T>
std::vector<T> getVector() const#

Get array as std::vector in requested type.

Throws:

  • bad_variant_access – If the array could not be cast to a vector of the requested type

  • invalid_argument – If at least one of the array elements is not valid for the requested type

Returns:

Vector with elements in the type of the requested template parameter

inline bool empty() const#

Check if the array is empty.

Returns:

True if the array is empty, false otherwise

std::string to_string() const#

Convert array to string representation.

Returns:

String representation of the array

std::string demangle() const#

Demangle type held by the array.

Returns:

Demangled name of the currently held type

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

Pack with msgpack

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

Unpack with msgpack

class Composite : public CompositeVariant#
#include <constellation/core/config/value_types.hpp>

Composite which is either scalar, array, or dictionary.

Public Functions

Composite() = default#

Construct a new valueless composite.

template<typename T>
Composite(T value)#

Construct a new composite from underlying variant type.

Parameters:

value – Value to be set for the new composite

template<typename T>
Composite(const T &value)#

Construct a new composite.

Parameters:

value – Value to be set for the new composite

template<typename T>
Composite &operator=(const T &other)#

Assignment operator

template<typename T>
bool operator==(const T &other) const#

Equality operator

template<typename T>
T get() const#

Get composite in requested type.

Throws:

  • bad_variant_access – If the composite could not be cast to requested type

  • invalid_argument – If the composite value is not valid for the requested type

Returns:

Value in the type of the requested template parameter

template<typename T>
const T &get() const#

Get constant reference to underlying type.

Throws:

bad_variant_access – If the composite could not be cast to requested type

Returns:

Constant reference to the value in the type of the requested template parameter

template<typename T>
T &get()#

Get reference to underlying type.

Throws:

bad_variant_access – If the composite could not be cast to requested type

Returns:

Reference to the value in the type of the requested template parameter

std::string to_string() const#

Convert composite to string representation.

Returns:

String representation of the value

std::string demangle() const#

Demangle type held by the composite.

Returns:

Demangled name of the currently held type

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

Pack with msgpack

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

Unpack with msgpack

message::PayloadBuffer assemble() const#

Assemble via msgpack to message payload

Public Static Functions

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

Disassemble from message payload

class CompositeList : public std::vector<Composite>#
#include <constellation/core/config/value_types.hpp>

List of composites.

Public Functions

CompositeList() = default#

Construct a new empty composite list.

template<typename R>
CompositeList(const R &range)#

Construct a new composite list from a range.

Parameters:

range – Range to be set for the new composite list

std::string to_string() const#

Convert composite list to string representation.

Returns:

String representation of the composite list

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

Pack with msgpack

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

Unpack with msgpack

message::PayloadBuffer assemble() const#

Assemble via msgpack to message payload

Public Static Functions

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

Disassemble from message payload

class Configuration : private constellation::config::RootDictionaryHolder, public constellation::config::Section#
#include <constellation/core/config/Configuration.hpp>

Class for the top-level configuration of a satellite.

This class is is a Section with additional methods to make suitable to be used within the framework. It inherits from RootDictionaryHolder since constructors first initializes all base classes and then member variables, meaning it cannot own the root dictionary as member to initialize the base Section.

Public Types

enum class ConfigurationGroup : 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

Public Functions

Configuration()#

Construct an empty configuration.

virtual ~Configuration() = default#
Configuration(Dictionary root_dictionary)#

Construct a configuration from a dictionary.

Parameters:

root_dictionary – Root dictionary of the configuration

Configuration(Configuration &&other) noexcept#

Move constructor

Configuration &operator=(Configuration &&other) noexcept#

Move assignment

void swap(Configuration &other) noexcept#

Swap function

std::string to_string(ConfigurationGroup configuration_group = ALL) const#

Convert configuration to a YAML-like string.

Parameters:

configuration_group – Group of configuration key-value pairs to include

Returns:

String containing the configuration

message::PayloadBuffer assemble() const#

Assemble via msgpack to message payload

Public Static Functions

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

Disassemble from message payload

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::InvalidKeyError, constellation::config::InvalidTypeError, constellation::config::InvalidUpdateError, constellation::config::InvalidValueError, constellation::config::MissingKeyError

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

Dictionary which maps strings to a composite.

Public Types

using key_filter = bool(std::string_view key)#

Public Functions

Dictionary() = default#

Construct a new empty dictionary.

template<typename T>
Dictionary(const std::map<std::string, T> &map)#

Construct a new dictionary from an std::map.

Parameters:

map – Map to be set for the new dictionary

template<typename T>
Dictionary &operator=(const std::map<std::string, T> &other)#

Assignment operator

template<typename T>
bool operator==(const std::map<std::string, T> &other) const#

Equality operator

template<typename T>
std::map<std::string, T> getMap() const#

Get dictionary as std::map with values in requested type.

Note

This is only possible if the dictionary is homogeneous and flat.

Throws:

  • bad_variant_access – If the dictionary could not be cast to an std::map with values of the requested type

  • invalid_argument – If at least one of the dictionary values is not valid for the requested type

Returns:

Map with value in the type of the requested template parameter

Dictionary getFlattened() const#

Get flattened dictionary.

Returns:

Flattened dictionary

std::string to_string() const#

Convert dictionary to string representation.

Returns:

String representation of the dictionary

std::string format(bool newline_prefix, std::size_t indent = 2) const#

Format dictionary to YAML-style string.

Parameters:

  • newline_prefix – If the string should be prefix with a newline if not empty

  • indent – Indent to prefix keys with (always increased by 2 for nested dictionaries)

Returns:

String representation of the dictionary in YAML-style

std::string demangle() const#

Demangle type.

Returns:

Demangled name of the type

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

Pack with msgpack

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

Unpack with msgpack

message::PayloadBuffer assemble() const#

Assemble via msgpack to message payload

Public Static Functions

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

Disassemble 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 Section &config, std::initializer_list<std::string> keys, std::string_view reason = "")#

Construct an error for an invalid combination of keys.

Parameters:

  • config – Configuration section 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 InvalidKeyError : public constellation::config::ConfigurationError#
#include <constellation/core/config/exceptions.hpp>

Indicates an error with the presence of a key.

Should be raised if the configuration contains a key which should not be present.

Public Functions

InvalidKeyError(const Section &config, std::string_view key, std::string_view reason = "")#

Construct an error for an invalid key.

Parameters:

  • config – Configuration section containing the key

  • key – Name of the problematic key

  • reason – Reason why the key 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

InvalidTypeError(const Section &config, std::string_view key, std::string_view vtype, std::string_view type)#

Construct an error for a value with an invalid type.

Parameters:

  • config – Configuration section containing the key

  • key – Name of the problematic key

  • vtype – Type of the stored value

  • type – Type the value should have been converted to

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

Indicates an error when updating a configuration.

Should be raised if a configuration is updated but the updated value is invalid given the current configuration, such as switching the type.

Public Functions

InvalidUpdateError(const Section &config, std::string_view key, std::string_view reason)#

Construct an error for an invalid update.

Parameters:

  • config – Configuration section containing the problematic key combination

  • key – Name of the problematic key

  • reason – Reason why the updated value is invalid

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 Section &config, std::string_view key, std::string_view reason)#

Construct an error for an invalid value.

Parameters:

  • config – Configuration section containing the key

  • key – Name of the problematic key

  • reason – Reason why the value is invalid

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

Informs of a missing key that should have been defined.

Public Functions

MissingKeyError(const Section &config, std::string_view key)#

Construct an error for a missing key.

Parameters:

  • config – Configuration section containing the key

  • key – Name of the problematic key

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

Class which owns the root dictionary of the configuration.

This class is required since the Configuration class cannot own the root dictionary due to initialization order.

Subclassed by constellation::config::Configuration

Public Functions

RootDictionaryHolder() = default#

Construct with an empty root dictionary.

RootDictionaryHolder(Dictionary dictionary)#

Construct from an existing dictionary.

Note

This constructor iterates recursively over all keys and converts them to lower-case.

class Scalar : public ScalarMonostateVariant#
#include <constellation/core/config/value_types.hpp>

Scalar (non-nestable) value.

Public Functions

Scalar() = default#

Construct a new valueless scalar.

template<typename T>
Scalar(T value)#

Construct a new scalar.

Parameters:

value – Value to be set for the new scalar

template<typename T>
Scalar &operator=(T other)#

Assignment operator

template<typename T>
bool operator==(T other) const#

Equality operator

template<typename T>
std::partial_ordering operator<=>(T other) const#

Spaceship operator

std::partial_ordering operator<=>(const Scalar &other) const#

Spaceship operator (implementation)

template<typename T>
T get() const#

Get scalar in requested type.

Throws:

  • bad_variant_access – If the scalar could not be cast to requested type

  • invalid_argument – If the scalar value is not valid for the requested type

Returns:

Value in the type of the requested template parameter

std::string to_string() const#

Convert scalar to string representation.

Returns:

String representation of the value

std::string demangle() const#

Demangle type held by the scalar.

Returns:

Demangled name of the currently held type

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

Pack with msgpack

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

Unpack with msgpack

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

Class to access a section in the configuration.

Each Section corresponds to a Dictionary. It provides convenient access methods for the Dictionary, keeps track of used and unused values, and owns any nested Section classes corresponding to Dictionary classes contained in the Dictionary class corresponding to itself.

Subclassed by constellation::config::Configuration

Public Functions

Section(std::string prefix, Dictionary *dictionary)#

Construct a new configuration section.

Parameters:

  • prefix – Prefix for the configuration section, e.g. channel_1.

  • dictionary – Pointer to the corresponding Dictionary object

Throws:

InvalidKeyError – If two keys with the same lowercase spellings are contained in the dictionary

virtual ~Section() = default#

Destructor

bool has(std::string_view key) const#

Check if key is defined.

Parameters:

key – Key to check for existence

Returns:

True if key exists, false otherwise

std::size_t count(std::initializer_list<std::string_view> 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.

Parameters:

keys – Keys to check for existence

Returns:

Number of existing keys from the given list

template<typename T>
void setDefault(std::string_view key, T &&default_value)#

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

Note

This does not mark the key as used.

Parameters:

  • key – Key to possible set value of

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

void setAlias(std::string_view new_key, std::string_view old_key, bool warn = true) const#

Set alias name for an already existing key.

Note

This marks the old key as “used” automatically.

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

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

Get value of a key in requested type.

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(std::string_view key, T default_value)#

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

Parameters:

  • key – Key to get value of

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

Throws:
Returns:

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

template<typename T>
std::optional<T> getOptional(std::string_view key) const#

Get an optional with value of a key in requested type if available.

Parameters:

key – Key to get value of

Throws:
Returns:

Optional holding the value of the key in the type of the requested template parameter if available

template<typename T>
std::vector<T> getArray(std::string_view key) const#

Get values for a key containing an array.

Note

This will also attempt to read the configuration key as single value and will return a vector with one entry if succeeding.

Parameters:

key – Key to get values of

Throws:
Returns:

List of values in the array in the requested template parameter

template<typename T>
std::vector<T> getArray(std::string_view key, std::vector<T> default_value)#

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

Note

This will also attempt to read the configuration key as single value and will return a vector with one entry if succeeding.

Parameters:

  • key – Key to get values of

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

Throws:
Returns:

List of values in the array in the requested template parameter

template<typename T>
std::optional<std::vector<T>> getOptionalArray(std::string_view key) const#

Get an optional with the values for a key containing an array if available.

Note

This will also attempt to read the configuration key as single value and will return a vector with one entry if succeeding.

Parameters:

key – Key to get values of

Throws:
Returns:

Optional with a list of values in the array in the requested template parameter if available

template<typename T>
std::set<T> getSet(std::string_view key) const#

Get values for a key containing a set.

Note

This will also attempt to read the configuration key as single value and will return a set with one entry if succeeding.

Parameters:

key – Key to get values of

Throws:
Returns:

Set of values in the requested template parameter

template<typename T>
std::set<T> getSet(std::string_view key, const std::set<T> &default_value)#

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

Note

This will also attempt to read the configuration key as single value and will return a set with one entry if succeeding.

Parameters:

  • key – Key to get values of

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

Throws:
Returns:

Set of values in the requested template parameter

template<typename T>
std::optional<std::set<T>> getOptionalSet(std::string_view key) const#

Get an optional with values for a key containing a set if available.

Note

This will also attempt to read the configuration key as single value and will return a set with one entry if succeeding.

Parameters:

key – Key to get values of

Throws:
Returns:

Optional with a set of values in the requested template parameter if available

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

Get path.

Note

Relative paths are taken relative to the current work directory.

Parameters:

  • key – Key to get path of

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

Throws:
Returns:

Absolute path

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

Get list of paths.

Note

Relative paths are taken relative to the current work directory.

Parameters:

  • key – Key to get list of path of

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

Throws:
Returns:

List of absolute paths

const Section &getSection(std::string_view key) const#

Get nested configuration section (const)

Parameters:

key – Key to get section of

Throws:
Returns:

Configuration section contained by the key

Section &getSection(std::string_view key)#

Get nested configuration section.

Parameters:

key – Key to get section of

Throws:
Returns:

Configuration section contained by the key

Section &getSection(std::string_view key, Dictionary &&default_value)#

Get nested configuration section or a default dictionary if it does not exists.

Parameters:

  • key – Key to get section of

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

Throws:
Returns:

Configuration section contained by the key

std::optional<std::reference_wrapper<const Section>> getOptionalSection(std::string_view key) const#

Get an optional nested configuration section (const)

Note

Since optionals of references are not allowed, this returns an optional of a reference wrapper. In get the reference to the configuration section from the reference wrapper the .get() method has to be used.

Parameters:

key – Key to get section of

Throws:

InvalidTypeError – If the value is not a section

Returns:

Optional with nested configuration section contained by the key if available

std::optional<std::reference_wrapper<Section>> getOptionalSection(std::string_view key)#

Get an optional nested configuration section.

Note

Since optionals of references are not allowed, this returns an optional of a reference wrapper. In get the reference to the configuration section from the reference wrapper the .get() method has to be used.

Parameters:

key – Key to get section of

Throws:

InvalidTypeError – If the value is not a section

Returns:

Optional with nested configuration section contained by the key if available

std::vector<std::string> getKeys() const#

Get the keys of the configuration section.

Note

This does not mark the keys as used.

Returns:

List containing the keys of the section

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

Get literal value of a key as string.

Warning

This does not mark the key as used, and thus should never be used to retrieve a configuration value.

Parameters:

key – Key to get values of

Returns:

Literal value of the key

inline const Dictionary &asDictionary() const#

Get configuration as dictionary.

Warning

Accessing entries in the dictionary does not mark the key as used, and thus should never be used to retrieve configuration values.

Returns:

Dictionary containing the configuration section

inline bool empty() const#

Check if the configuration section is empty.

Returns:

True if section is empty, false otherwise

inline std::string_view prefix() const#

Return the prefix of the configuration section.

Returns:

Prefix with trailing dot

std::vector<std::string> removeUnusedEntries()#

Remove unused entries from the configuration section.

Returns:

List of unused keys

void update(const Section &other)#

Update configuration with values from another configuration section.

Before updating this method validates that all keys which are to be updated already exist and that their corresponding values have the same type after the update.

Parameters:

other – Configuration section from which to update values from

On this page
Edit on GitLab