werkzeugkiste::config::Configuration class
#include <configuration.h>

Encapsulates configuration data.

Contents

This class provides a unified access to different configuration file formats, as well as several convenience utilities, such as replacing string placeholders, adjusting file paths, etc.

This utitility class is intended for *"typical"*, human-friendly configuration scenarios and, similar to TOML, supports the following parameter types:

  • Basic scalars: bool, int32_t, int64_t, double, and std::string.
  • Local date, local time, and date-time (date + time + time zone offset) types.
  • Aggregate types, i.e. lists and groups of parameters.

The following configuration formats are supported:

For usage convenience, this class support conversion from the TOML-compatible parameter types to:

#include <werkzeugkiste/config/configuration.h>
namespace wkc = werkzeugkiste::config;
using namespace std::string_view_literals;
// Load a configuration from a file (format will be deduced from the
// file extension)...
wkc::Configuration cfg = wkc::LoadFile("path/to/config.toml");
// ... or a string:
wkc::Configuration cfg = wkc::LoadTOMLString("value = 42.17"sv);
wkc::Configuration cfg = wkc::LoadJSONString("{ 'value': 42.17 }"sv);

// TODO Extend example

Public static functions

static auto LoadTOMLString(std::string_view toml_string) -> Configuration
Loads a TOML configuration from a string.
static auto LoadTOMLFile(std::string_view filename) -> Configuration
Loads a TOML configuration from the given file.
static auto KeyForListElement(std::string_view key, std::size_t index) -> std::string
Returns the Fully qualified parameter name for the given parameter name and element index.
static void HandleNullValue(Configuration& cfg, std::string_view key, NullValuePolicy policy, bool append)
Applies the selected NullValuePolicy to the given parameter.

Constructors, destructors, conversion operators

Configuration()
Constructs an empty configuration.
~Configuration()
Destructor.
Configuration(const Configuration& other)
Copy constructor - creates a deep copy.
Configuration(Configuration&& other) noexcept
Move constructor.

Public functions

auto operator=(const Configuration& other) -> Configuration&
Copy assignment - creates a deep copy.
auto operator=(Configuration&& other) -> Configuration& noexcept
Move assignment.
auto Empty() const -> bool
Returns true if this configuration has no parameters set.
auto Equals(const Configuration& other) const -> bool
Returns true if all configuration keys and values match exactly.
auto operator==(const Configuration& other) const -> bool
Returns true if all configuration keys and values match exactly.
auto operator!=(const Configuration& other) const -> bool
Returns true if any configuration key or value differs.
auto Contains(std::string_view key) const -> bool
Checks if the given key exists in this configuration.
auto Size(std::string_view key) const -> std::size_t
Returns the length of the parameter list/group named key.
auto Size() const -> std::size_t
Returns the number of parameters (key-value pairs) in this configuration.
auto Type(std::string_view key) const -> ConfigType
Returns the type of the parameter at the given key.
void Delete(std::string_view key)
Deletes the parameter with the given key.
auto IsHomogeneousScalarList(std::string_view key) const -> bool
Checks if a list parameter contains only scalars of the same type.
auto ListParameterNames(std::string_view key, bool include_array_entries, bool recursive) const -> std::vector<std::string>
Returns a list of (Fully qualified) parameter names below the given key.
auto ListParameterNames(bool include_array_entries, bool recursive) const -> std::vector<std::string>
Returns a list of (Fully qualified) parameter names below the configuration root.
auto EnsureTypeIfExists(std::string_view key, ConfigType expected) const -> bool
Raises a TypeError if the parameter exists, but is of a different type.

Boolean

@desc Getter/Setter for boolean parameters.

auto GetBool(std::string_view key) const -> bool
Returns the boolean parameter.
auto GetBoolOr(std::string_view key, bool default_val) const -> bool
Returns the boolean parameter or the default_val if it does not exist.
auto GetOptionalBool(std::string_view key) const -> std::optional<bool>
Returns an optional boolean or std::nullopt if it does not exist.
void SetBool(std::string_view key, bool value)
Sets a boolean parameter.
auto GetBoolList(std::string_view key) const -> std::vector<bool>
Returns a list of boolean flags.
void SetBoolList(std::string_view key, const std::vector<bool>& values)
Sets or replaces a list of boolean flags.

Integer

@desc Getter/Setter for 32- and 64-bit integer parameters.

auto GetInt32(std::string_view key) const -> int32_t
Returns the 32-bit integer parameter.
auto GetInt32Or(std::string_view key, int32_t default_val) const -> int32_t
Returns the 32-bit integer parameter or the default value.
auto GetOptionalInt32(std::string_view key) const -> std::optional<int32_t>
Returns the 32-bit integer parameter or std::nullopt if it does not exist.
void SetInt32(std::string_view key, int32_t value)
Sets a 32-bit signed integer parameter.
auto GetInt32List(std::string_view key) const -> std::vector<int32_t>
Returns a list of 32-bit integers.
void SetInt32List(std::string_view key, const std::vector<int32_t>& values)
Sets or replaces a list of 32-bit integers.
auto GetInt64(std::string_view key) const -> int64_t
Returns the 64-bit integer parameter.
auto GetInt64Or(std::string_view key, int64_t default_val) const -> int64_t
Returns the 64-bit integer parameter or the default value.
auto GetOptionalInt64(std::string_view key) const -> std::optional<int64_t>
Returns the 64-bit integer parameter or std::nullopt if it does not exist.
void SetInt64(std::string_view key, int64_t value)
Sets a 64-bit signed integer parameter.
auto GetInt64List(std::string_view key) const -> std::vector<int64_t>
Returns a list of 64-bit integers.
void SetInt64List(std::string_view key, const std::vector<int64_t>& values)
Sets or replaces a list of 64-bit integers.
auto GetInt64Point2D(std::string_view key) const -> point2d<int64_t>
Returns a 2D point with integer coordinates.
auto GetInt64Point3D(std::string_view key) const -> point3d<int64_t>
Returns a 3D point with integer coordinates.
auto GetInt64Points2D(std::string_view key) const -> std::vector<point2d<int64_t>>
Returns a list of 2D points (e.g. a polyline or polygon).
auto GetInt64Points3D(std::string_view key) const -> std::vector<point3d<int64_t>>
Returns a list of 3D points (e.g. a polyline or polygon).

Floating point

@desc Getter/Setter for double-precision floating point parameters.

auto GetDouble(std::string_view key) const -> double
Returns the double-precision floating point parameter.
auto GetDoubleOr(std::string_view key, double default_val) const -> double
Returns the double-precision floating point parameter or the default value.
auto GetOptionalDouble(std::string_view key) const -> std::optional<double>
Returns the double-precision floating point parameter or std::nullopt if it does not exist.
void SetDouble(std::string_view key, double value)
Sets a double-precision floating point parameter.
auto GetDoubleList(std::string_view key) const -> std::vector<double>
Returns a list of double-precision floating point values.
void SetDoubleList(std::string_view key, const std::vector<double>& values)
Sets or replaces a list of double-precision floating point values.
auto GetDoublePoint2D(std::string_view key) const -> point2d<double>
Returns a 2D point with floating point coordinates.
auto GetDoublePoint3D(std::string_view key) const -> point3d<double>
Returns a 3D point with floating point coordinates.
auto GetDoublePoints2D(std::string_view key) const -> std::vector<point2d<double>>
Returns a list of 2D points (e.g. a polyline or polygon).
auto GetDoublePoints3D(std::string_view key) const -> std::vector<point3d<double>>
Returns a list of 3D points (e.g. a polyline or polygon).

String

@desc Getter/Setter for string parameters.

auto GetString(std::string_view key) const -> std::string
Returns the string parameter.
auto GetStringOr(std::string_view key, std::string_view default_val) const -> std::string
Returns the string parameter or the default_val if it does not exist.
auto GetOptionalString(std::string_view key) const -> std::optional<std::string>
Returns an optional string or std::nullopt if it does not exist.
void SetString(std::string_view key, std::string_view value)
Sets a string parameter.
auto GetStringList(std::string_view key) const -> std::vector<std::string>
Returns a list of strings.
void SetStringList(std::string_view key, const std::vector<std::string_view>& values)
Creates or replaces a parameter holding a list of strings.

Date

@desc Getter/Setter for werkzeugkiste::config::date parameters.

auto GetDate(std::string_view key) const -> date
Returns the date parameter.
auto GetDateOr(std::string_view key, const date& default_val) const -> date
Returns the date parameter or the default_val if it does not exist.
auto GetOptionalDate(std::string_view key) const -> std::optional<date>
Returns an optional date or std::nullopt if it does not exist.
void SetDate(std::string_view key, const date& value)
Sets a local date parameter.
auto GetDateList(std::string_view key) const -> std::vector<date>
Returns a list of date parameters.
void SetDateList(std::string_view key, const std::vector<date>& values)
Sets or replaces a list of date parameters.

Time

@desc Getter/Setter for werkzeugkiste::config::time parameters.

auto GetTime(std::string_view key) const -> time
Returns the time parameter.
auto GetTimeOr(std::string_view key, const time& default_val) const -> time
Returns the time parameter or the default_val if it does not exist.
auto GetOptionalTime(std::string_view key) const -> std::optional<time>
Returns an optional time or std::nullopt if it does not exist.
void SetTime(std::string_view key, const time& value)
Sets a local time parameter.
auto GetTimeList(std::string_view key) const -> std::vector<time>
Returns a list of time parameters.
void SetTimeList(std::string_view key, const std::vector<time>& values)
Sets or replaces a list of time parameters.

Date-Time

@desc Getter/Setter for werkzeugkiste::config::date_time parameters.

auto GetDateTime(std::string_view key) const -> date_time
Returns the date-time parameter with optional timezone offset.
auto GetDateTimeOr(std::string_view key, const date_time& default_val) const -> date_time
Returns the date-time parameter or the default_val if it does not exist.
auto GetOptionalDateTime(std::string_view key) const -> std::optional<date_time>
Returns an optional date_time or std::nullopt if it does not exist.
void SetDateTime(std::string_view key, const date_time& value)
Sets a date-time parameter.
auto GetDateTimeList(std::string_view key) const -> std::vector<date_time>
Returns a list of date-time parameters.
void SetDateTimeList(std::string_view key, const std::vector<date_time>& values)
Sets or replaces a list of date-time parameters.

Lists

@desc These methods allow working with mixed type lists.

void CreateList(std::string_view key)
Creates an empty list with the given name.
void ClearList(std::string_view key)
Clears an existing list.
void AppendList(std::string_view key)
Appends an empty list to an existing list in order to supported creating nested lists programmatically.
void Append(std::string_view key, bool value)
Appends a boolean flag to an existing list.
void Append(std::string_view key, int32_t value)
Appends a 32-bit integer to an existing list.
void Append(std::string_view key, int64_t value)
Appends a 64-bit integer to an existing list.
void Append(std::string_view key, double value)
Appends a floating point value to an existing list.
void Append(std::string_view key, std::string_view value)
Appends a string to an existing list.
void Append(std::string_view key, const date& value)
Appends a date to an existing list.
void Append(std::string_view key, const time& value)
Appends a local time to an existing list.
void Append(std::string_view key, const date_time& value)
Appends a date-time to an existing list.
void Append(std::string_view key, const Configuration& group)
Appends a group/sub-configuration to an existing list.

Group/Sub-Configuration

@desc Getter/Setter for groups.

auto GetGroup(std::string_view key) const -> Configuration
Returns a copy of the sub-group.
void SetGroup(std::string_view key, const Configuration& group)
Inserts (or replaces) the given configuration group.

Matrix

@desc Conversion between Eigen::Matrix and (nested) lists.

auto GetMatrixUInt8(std::string_view key) const -> Matrix<uint8_t>
Returns a list/nested list as a 2D matrix.
auto GetMatrixInt32(std::string_view key) const -> Matrix<int32_t>
Returns a list/nested list as a 2D matrix.
auto GetMatrixInt64(std::string_view key) const -> Matrix<int64_t>
Returns a list/nested list as a 2D matrix.
auto GetMatrixFloat(std::string_view key) const -> Matrix<float>
Returns a list/nested list as a 2D matrix.
auto GetMatrixDouble(std::string_view key) const -> Matrix<double>
Returns a list/nested list as a 2D matrix.
template<typename Derived, typename TpMat = typename Derived::Scalar>
void SetMatrix(std::string_view key, const Eigen::MatrixBase<Derived>& mat)
Stores a matrix as list.

Generic Setters

@desc Creates or replaces a parameter value.

void Set(std::string_view key, bool value)
void Set(std::string_view key, int32_t value)
void Set(std::string_view key, int64_t value)
void Set(std::string_view key, double value)
void Set(std::string_view key, std::string_view value)
void Set(std::string_view key, const date& value)
void Set(std::string_view key, const time& value)
void Set(std::string_view key, const date_time& value)
void Set(std::string_view key, const Configuration& group)

Utilities

auto AdjustRelativePaths(std::string_view key, std::string_view base_path, const std::vector<std::string_view>& parameters) -> bool
Adjusts the given parameters below the key group to hold either an absolute file path, or the result of "base_path / <param>" if they initially held a relative file path.
auto AdjustRelativePaths(std::string_view base_path, const std::vector<std::string_view>& parameters) -> bool
Adjusts the given parameters below the configuration root to hold either an absolute file path, or the result of "base_path / <param>" if they initially held a relative file path.
auto ReplaceStringPlaceholders(std::string_view key, const std::vector<std::pair<std::string_view, std::string_view>>& replacements) -> bool
Visits all string parameters below the given key group and replaces any occurrence of the given needle/replacement pairs.
auto ReplaceStringPlaceholders(const std::vector<std::pair<std::string_view, std::string_view>>& replacements) -> bool
Visits all string parameters below the root configuration and replaces any occurrence of the given needle/replacement pairs.
void LoadNestedConfiguration(std::string_view key)
Loads a nested configuration.

Serialization

@desc Represent this configuration as a string in a specific format.

auto ToTOML() const -> std::string
Returns a TOML-formatted string of this configuration.
auto ToJSON() const -> std::string
Returns a JSON-formatted string of this configuration.
auto ToYAML() const -> std::string
Returns a YAML-formatted string of this configuration.
auto ToLibconfig() const -> std::string
Returns a libconfig-formatted string of this configuration.

Function documentation

static Configuration werkzeugkiste::config::Configuration::LoadTOMLString(std::string_view toml_string)

Loads a TOML configuration from a string.

Parameters
toml_string String representation of the TOML config.

static Configuration werkzeugkiste::config::Configuration::LoadTOMLFile(std::string_view filename)

Loads a TOML configuration from the given file.

Parameters
filename Path to the .toml file.

static std::string werkzeugkiste::config::Configuration::KeyForListElement(std::string_view key, std::size_t index)

Returns the Fully qualified parameter name for the given parameter name and element index.

Parameters
key The parameter name of the list.
index The 0-based index of the list element.
Returns The Fully qualified name, i.e. key[index].

static void werkzeugkiste::config::Configuration::HandleNullValue(Configuration& cfg, std::string_view key, NullValuePolicy policy, bool append)

Applies the selected NullValuePolicy to the given parameter.

Parameters
cfg Configuration to be modified.
key Fully qualified parameter name.
policy The selected NullValuePolicy.
append If true, key is assumed to be a list and the replacement value (depending on the policy) will be Appended, otherwise, it will be Set.

This method is intended for parsers and should be called if the parsed key parameter was a null/none value.

bool werkzeugkiste::config::Configuration::Contains(std::string_view key) const

Checks if the given key exists in this configuration.

Parameters
key Fully qualified identifier of the parameter.

std::size_t werkzeugkiste::config::Configuration::Size(std::string_view key) const

Returns the length of the parameter list/group named key.

Parameters
key Fully qualified identifier of the parameter.

Raises a KeyError if the parameter does not exist. Raises a TypeError if the parameter is not a list or a group.

ConfigType werkzeugkiste::config::Configuration::Type(std::string_view key) const

Returns the type of the parameter at the given key.

Parameters
key Fully qualified identifier of the parameter.

Raises a KeyError if the parameter does not exist.

void werkzeugkiste::config::Configuration::Delete(std::string_view key)

Deletes the parameter with the given key.

Parameters
key Fully qualified parameter name.

Can be used to delete a scalar, list or (sub-)group of the configuration. Cannot be used to delete a specific element of a list (arr[0]). For the latter, you need to delete (then recreate) the whole list.

Raises a KeyError if the parameter does not exist or refers to an element of a list.

bool werkzeugkiste::config::Configuration::IsHomogeneousScalarList(std::string_view key) const

Checks if a list parameter contains only scalars of the same type.

Parameters
key Fully qualified name of the parameter.
Returns True if the list is empty or contains only scalars of the same type. False otherwise.

Raises a KeyError if the parameter does not exist. Raises a TypeError if the parameter is not a list.

std::vector<std::string> werkzeugkiste::config::Configuration::ListParameterNames(std::string_view key, bool include_array_entries, bool recursive) const

Returns a list of (Fully qualified) parameter names below the given key.

Parameters
key Fully qualified name of the parameter.
include_array_entries If true, the name of each parameter will be returned, i.e. each array element will be included. Otherwise, only named parameters (e.g. a dictionary/table within an array, such as arr[3].name) will be included.
recursive If true, the names of all parameters "below" this configuration/group will be returned. Otherwise, only the first-level child parameters will be returned.

std::vector<std::string> werkzeugkiste::config::Configuration::ListParameterNames(bool include_array_entries, bool recursive) const

Returns a list of (Fully qualified) parameter names below the configuration root.

Parameters
include_array_entries If true, the name of each parameter will be returned, i.e. each array element will be included. Otherwise, only named parameters (e.g. a dictionary/table within an array, such as arr[3].name) will be included.
recursive If true, the names of all parameters "below" this configuration/group will be returned. Otherwise, only the first-level child parameters will be returned.

bool werkzeugkiste::config::Configuration::EnsureTypeIfExists(std::string_view key, ConfigType expected) const

Raises a TypeError if the parameter exists, but is of a different type.

Parameters
key Fully qualified parameter name.
expected The expected type of the parameter.
Returns True if the parameter exists, false otherwise.

bool werkzeugkiste::config::Configuration::GetBool(std::string_view key) const

Returns the boolean parameter.

Parameters
key Fully qualified parameter name.

Raises a KeyError if the parameter does not exist. Raises a TypeError if the parameter is of a different type.

bool werkzeugkiste::config::Configuration::GetBoolOr(std::string_view key, bool default_val) const

Returns the boolean parameter or the default_val if it does not exist.

Parameters
key Fully qualified parameter name.
default_val Value to return if the parameter does not exist.

Raises a TypeError if the parameter exists but is of a different type.

std::optional<bool> werkzeugkiste::config::Configuration::GetOptionalBool(std::string_view key) const

Returns an optional boolean or std::nullopt if it does not exist.

Parameters
key Fully qualified parameter name.

Raises a TypeError if the parameter exists but is of a different type.

void werkzeugkiste::config::Configuration::SetBool(std::string_view key, bool value)

Sets a boolean parameter.

Parameters
key Fully qualified parameter name.
value The value to be set.

Raises a TypeError if the parameter exists and is of a different type. Raises a std::logic_error if setting the value in the underlying TOML library failed for unforeseen/not handled reasons.

std::vector<bool> werkzeugkiste::config::Configuration::GetBoolList(std::string_view key) const

Returns a list of boolean flags.

Parameters
key Fully qualified parameter name.

Raises a KeyError if the parameter does not exist. Raises a TypeError if the parameter is of a different type.

void werkzeugkiste::config::Configuration::SetBoolList(std::string_view key, const std::vector<bool>& values)

Sets or replaces a list of boolean flags.

Parameters
key Fully qualified parameter name.
values List of flags.

Raises a TypeError if the parameter exists but is of a different type.

int32_t werkzeugkiste::config::Configuration::GetInt32(std::string_view key) const

Returns the 32-bit integer parameter.

Parameters
key Fully qualified parameter name.

Raises a KeyError if the parameter does not exist. Raises a TypeError if the parameter is of a different type, unless it can be safely cast (e.g. double(2.0) can be exactly represented by a 32-bit integer, whereas double(1.5) cannot).

int32_t werkzeugkiste::config::Configuration::GetInt32Or(std::string_view key, int32_t default_val) const

Returns the 32-bit integer parameter or the default value.

Parameters
key Fully qualified parameter name.
default_val Value to be returned if the parameter does not exist.

Raises a TypeError if the parameter is of a different type, unless it can be safely cast (e.g. double(2.0) can be exactly represented by a 32-bit integer, whereas double(1.5) cannot).

std::optional<int32_t> werkzeugkiste::config::Configuration::GetOptionalInt32(std::string_view key) const

Returns the 32-bit integer parameter or std::nullopt if it does not exist.

Parameters
key Fully qualified parameter name.

Raises a TypeError if the parameter is of a different type, unless it can be safely cast (e.g. double(2.0) can be exactly represented by a 32-bit integer, whereas double(1.5) cannot).

void werkzeugkiste::config::Configuration::SetInt32(std::string_view key, int32_t value)

Sets a 32-bit signed integer parameter.

Parameters
key Fully qualified parameter name.
value The value to be set.

Raises a TypeError if the parameter exists and is of a different type, unless the value is exactly representable by the existing type. For example, an integer value can usually be exactly represented as a floating point number, thus SetInt32("my-float"sv, 2) will not raise an exception. Raises a std::logic_error if setting the value in the underlying TOML library failed for unforeseen/not handled reasons.

std::vector<int32_t> werkzeugkiste::config::Configuration::GetInt32List(std::string_view key) const

Returns a list of 32-bit integers.

Parameters
key Fully qualified parameter name.

Raises a KeyError if the parameter does not exist. Raises a TypeError if the parameter is of a different type, unless it can be safely cast. For example, a list like [0.0, -2.0, 100.0, 12345.0] can be exactly represented by a list of 32-bit integer, whereas [0.0, 1.5] cannot.

void werkzeugkiste::config::Configuration::SetInt32List(std::string_view key, const std::vector<int32_t>& values)

Sets or replaces a list of 32-bit integers.

Parameters
key Fully qualified parameter name.
values List of flags.

Raises a TypeError if the parameter exists but is of a different type. If the parameter is a mixed numeric list, however, the values will be cast to the corresponding data type. For example, replacing an existing [int, double, int] list by [1, 2, 3, 4] results in a parameter list [int(1), double(2.0), int(3), int(4)].

int64_t werkzeugkiste::config::Configuration::GetInt64(std::string_view key) const

Returns the 64-bit integer parameter.

Parameters
key Fully qualified parameter name.

Raises a KeyError if the parameter does not exist. Raises a TypeError if the parameter is of a different type, unless it can be safely cast (e.g. double(2.0) can be exactly represented by a 64-bit integer, whereas double(1.5) cannot).

int64_t werkzeugkiste::config::Configuration::GetInt64Or(std::string_view key, int64_t default_val) const

Returns the 64-bit integer parameter or the default value.

Parameters
key Fully qualified parameter name.
default_val Value to be returned if the parameter does not exist.

Raises a TypeError if the parameter is of a different type, unless it can be safely cast (e.g. double(2.0) can be exactly represented by a 64-bit integer, whereas double(1.5) cannot).

std::optional<int64_t> werkzeugkiste::config::Configuration::GetOptionalInt64(std::string_view key) const

Returns the 64-bit integer parameter or std::nullopt if it does not exist.

Parameters
key Fully qualified parameter name.

Raises a TypeError if the parameter is of a different type, unless it can be safely cast. For example, double(2.0) can be exactly represented by a 64-bit integer, whereas double(1.5) cannot.

void werkzeugkiste::config::Configuration::SetInt64(std::string_view key, int64_t value)

Sets a 64-bit signed integer parameter.

Parameters
key Fully qualified parameter name.
value The value to be set.

Raises a TypeError if the parameter exists and is of a different type, unless the value is exactly representable by the existing type. For example, an integer value can usually be exactly represented as a floating point number, thus SetInt64("my-float"sv, 2) will not raise an exception. Raises a std::logic_error if setting the value in the underlying TOML library failed for unforeseen/not handled reasons.

std::vector<int64_t> werkzeugkiste::config::Configuration::GetInt64List(std::string_view key) const

Returns a list of 64-bit integers.

Parameters
key Fully qualified parameter name.

Raises a KeyError if the parameter does not exist. Raises a TypeError if the parameter is of a different type, unless it can be safely cast. For example, a list like [0.0, -2.0, 100.0, 12345.0] can be exactly represented by a list of 64-bit integer, whereas [0.0, 1.5] cannot.

void werkzeugkiste::config::Configuration::SetInt64List(std::string_view key, const std::vector<int64_t>& values)

Sets or replaces a list of 64-bit integers.

Parameters
key Fully qualified parameter name.
values List of flags.

Raises a TypeError if the parameter exists but is of a different type. If the parameter is a mixed numeric list, however, the values will be cast to the corresponding data type. For example, replacing an existing [int, double, int] list by [1, 2, 3, 4] results in a parameter list [int(1), double(2.0), int(3), int(4)].

point2d<int64_t> werkzeugkiste::config::Configuration::GetInt64Point2D(std::string_view key) const

Returns a 2D point with integer coordinates.

Parameters
key Fully qualified parameter name

Interprets a list of numbers as 2D point. If the list contains more than two elements, only the first two entries are loaded as x and y coordinate, respectively. Similarly, a group which holds (at least) x and y parameters can also be loaded as a 2D point.

const wkc::Configuration cfg = wkc::LoadTOMLString(R"toml(
    lst-2d = [1, 2]
    lst-nd = [1, 2, 3, 4, 5]
    grp-2d = { x = 1, y = 2 }
    )toml");
// Load 2-element list as 2D point:
const auto pt1 = cfg.GetInt64Point2D("lst-2d");
// Load 2D point from the first 2 elements of a 5-element list:
const auto pt2 = cfg.GetInt64Point2D("lst-nd");
// Load 2D point from a group containing x and y parameters:
const auto pt3 = cfg.GetInt64Point2D("grp-2d");

Raises a KeyError if the parameter does not exist. Raises a TypeError if the parameter cannot be converted to a 2D point.

point3d<int64_t> werkzeugkiste::config::Configuration::GetInt64Point3D(std::string_view key) const

Returns a 3D point with integer coordinates.

Parameters
key Fully qualified parameter name

Interprets a list of numbers as 3D point. If the list contains more than three elements, only the first three entries are loaded as x, y and z coordinate, respectively. Similarly, a group which holds (at least) x, y and z parameters can also be loaded as a 3D point.

const wkc::Configuration cfg = wkc::LoadTOMLString(R"toml(
    lst-3d = [1, 2, 3]
    lst-nd = [1, 2, 3, 4, 5]
    grp-3d = { x = 1, y = 2, z = 3 }
    )toml");
// Load 3-element list as 3D point:
const auto pt1 = cfg.GetInt64Point3D("lst-3d");
// Load 3D point from the first 3 elements of a 5-element list:
const auto pt2 = cfg.GetInt64Point3D("lst-nd");
// Load 3D point from a group containing x, y and z parameters:
const auto pt3 = cfg.GetInt64Point3D("grp-3d");

Raises a KeyError if the parameter does not exist. Raises a TypeError if the parameter cannot be converted to a 2D point.

std::vector<point2d<int64_t>> werkzeugkiste::config::Configuration::GetInt64Points2D(std::string_view key) const

Returns a list of 2D points (e.g. a polyline or polygon).

Parameters
key Fully qualified parameter name.

Supports loading nested lists and lists of {x, y} tables as a list of 2D points. Each point in the configuration must have at least 2 dimensions, but may also have more (i.e. only loading the x/y components of 3D points is allowed).

Raises a KeyError if the parameter does not exist. Raises a TypeError if any coordinate is defined as a different type, unless it can be safely cast.

std::vector<point3d<int64_t>> werkzeugkiste::config::Configuration::GetInt64Points3D(std::string_view key) const

Returns a list of 3D points (e.g. a polyline or polygon).

Parameters
key Fully qualified parameter name.

Supports loading nested lists and lists of {x, y} tables as a list of 3D points. Each point in the configuration must have at least 3 dimensions, but may also have more (i.e. only loading the first 3 components of n-dim points is allowed).

Raises a KeyError if the parameter does not exist. Raises a TypeError if any coordinate is defined as a different type, unless it can be safely cast.

double werkzeugkiste::config::Configuration::GetDouble(std::string_view key) const

Returns the double-precision floating point parameter.

Parameters
key Fully qualified parameter name.

Raises a KeyError if the parameter does not exist. Raises a TypeError if the parameter is of a different type, unless it can be safely cast (e.g. integer values can usually be exactly represented by a double).

double werkzeugkiste::config::Configuration::GetDoubleOr(std::string_view key, double default_val) const

Returns the double-precision floating point parameter or the default value.

Parameters
key Fully qualified parameter name.
default_val Value to be returned if the parameter does not exist.

Raises a TypeError if the parameter is of a different type, unless it can be safely cast (e.g. integer values can usually be exactly represented by a double).

std::optional<double> werkzeugkiste::config::Configuration::GetOptionalDouble(std::string_view key) const

Returns the double-precision floating point parameter or std::nullopt if it does not exist.

Parameters
key Fully qualified parameter name.

Raises a TypeError if the parameter is of a different type, unless it can be safely cast. For example, integer values can usually be exactly represented by a double.

void werkzeugkiste::config::Configuration::SetDouble(std::string_view key, double value)

Sets a double-precision floating point parameter.

Parameters
key Fully qualified parameter name.
value The value to be set.

Raises a TypeError if the parameter exists and is of a different type, unless the value is exactly representable by the existing type. For example, SetDouble("my-integer"sv, 12.0) will not raise an exception. However, the parameter type of my-integer would still be integer. Raises a std::logic_error if setting the value in the underlying TOML library failed for unforeseen/not handled reasons.

std::vector<double> werkzeugkiste::config::Configuration::GetDoubleList(std::string_view key) const

Returns a list of double-precision floating point values.

Parameters
key Fully qualified parameter name.

Raises a KeyError if the parameter does not exist. Raises a TypeError if the parameter is of a different type, unless it can be safely cast (e.g. integer values can usually be exactly represented by a double).

void werkzeugkiste::config::Configuration::SetDoubleList(std::string_view key, const std::vector<double>& values)

Sets or replaces a list of double-precision floating point values.

Parameters
key Fully qualified parameter name.
values List of flags.

Raises a TypeError if the parameter exists but is of a different type. If the parameter is a mixed numeric list, however, this call can succeed if all values can be exactly represented by the corresponding data type. For example, replacing an existing [int, double, int] list by [1.0, 2.3, 3e3, 4.5] results in a parameter list [int(1), double(2.3), int(3000), double(4.5)].

point2d<double> werkzeugkiste::config::Configuration::GetDoublePoint2D(std::string_view key) const

Returns a 2D point with floating point coordinates.

Parameters
key Fully qualified parameter name

Interprets a list of numbers as 2D point. If the list contains more than two elements, only the first two entries are loaded as x and y coordinate, respectively. Similarly, a group which holds (at least) x and y parameters can also be loaded as a 2D point.

Raises a KeyError if the parameter does not exist. Raises a TypeError if the parameter cannot be converted to a 2D point.

point3d<double> werkzeugkiste::config::Configuration::GetDoublePoint3D(std::string_view key) const

Returns a 3D point with floating point coordinates.

Parameters
key Fully qualified parameter name

Interprets a list of numbers as 3D point. If the list contains more than three elements, only the first three entries are loaded as x, y and z coordinate, respectively. Similarly, a group which holds (at least) x, y and z parameters can also be loaded as a 3D point.

Raises a KeyError if the parameter does not exist. Raises a TypeError if the parameter cannot be converted to a 2D point.

std::vector<point2d<double>> werkzeugkiste::config::Configuration::GetDoublePoints2D(std::string_view key) const

Returns a list of 2D points (e.g. a polyline or polygon).

Parameters
key Fully qualified parameter name.

Supports loading nested lists and lists of {x, y} tables as a list of 2D points. Each point in the configuration must have at least 2 dimensions, but may also have more (i.e. only loading the x/y components of 3D points is allowed).

Raises a KeyError if the parameter does not exist. Raises a TypeError if any coordinate is defined as a different type, unless it can be safely cast.

std::vector<point3d<double>> werkzeugkiste::config::Configuration::GetDoublePoints3D(std::string_view key) const

Returns a list of 3D points (e.g. a polyline or polygon).

Parameters
key Fully qualified parameter name.

Supports loading nested lists and lists of {x, y} tables as a list of 3D points. Each point in the configuration must have at least 3 dimensions, but may also have more (i.e. only loading the x/y/z components of n-dim points is allowed).

Raises a KeyError if the parameter does not exist. Raises a TypeError if any coordinate is defined as a different type, unless it can be safely cast.

std::string werkzeugkiste::config::Configuration::GetString(std::string_view key) const

Returns the string parameter.

Parameters
key Fully qualified parameter name.

Raises a KeyError if the parameter does not exist. Raises a TypeError if the parameter is of a different type.

std::string werkzeugkiste::config::Configuration::GetStringOr(std::string_view key, std::string_view default_val) const

Returns the string parameter or the default_val if it does not exist.

Parameters
key Fully qualified parameter name.
default_val Value to return if the parameter does not exist.

Raises a TypeError if the parameter exists but is of a different type.

std::optional<std::string> werkzeugkiste::config::Configuration::GetOptionalString(std::string_view key) const

Returns an optional string or std::nullopt if it does not exist.

Parameters
key Fully qualified parameter name.

Raises a TypeError if the parameter exists but is of a different type.

void werkzeugkiste::config::Configuration::SetString(std::string_view key, std::string_view value)

Sets a string parameter.

Parameters
key Fully qualified parameter name.
value The value to be set.

Raises a TypeError if the parameter exists and is of a different type. Raises a std::logic_error if setting the value in the underlying TOML library failed for unforeseen/not handled reasons.

std::vector<std::string> werkzeugkiste::config::Configuration::GetStringList(std::string_view key) const

Returns a list of strings.

Parameters
key Fully qualified parameter name.

Raises a KeyError if the parameter does not exist. Raises a TypeError if the parameter is of a different type.

void werkzeugkiste::config::Configuration::SetStringList(std::string_view key, const std::vector<std::string_view>& values)

Creates or replaces a parameter holding a list of strings.

Parameters
key Fully qualified parameter name.
values List of strings to be set.

Raises a TypeError if the parameter exists but is of a different type, i.e. this method can not be used to change the type of an existing parameter.

date werkzeugkiste::config::Configuration::GetDate(std::string_view key) const

Returns the date parameter.

Parameters
key Fully qualified parameter name.

Raises a KeyError if the parameter does not exist. Raises a TypeError if the parameter is of a different type.

date werkzeugkiste::config::Configuration::GetDateOr(std::string_view key, const date& default_val) const

Returns the date parameter or the default_val if it does not exist.

Parameters
key Fully qualified parameter name.
default_val Value to return if the parameter does not exist.

Raises a TypeError if the parameter exists but is of a different type.

std::optional<date> werkzeugkiste::config::Configuration::GetOptionalDate(std::string_view key) const

Returns an optional date or std::nullopt if it does not exist.

Parameters
key Fully qualified parameter name.

Raises a TypeError if the parameter exists but is of a different type.

void werkzeugkiste::config::Configuration::SetDate(std::string_view key, const date& value)

Sets a local date parameter.

Parameters
key Fully qualified parameter name.
value The value to be set.

Raises a TypeError if the parameter exists and is of a different type. Raises a std::logic_error if setting the value in the underlying TOML library failed for unforeseen/not handled reasons.

std::vector<date> werkzeugkiste::config::Configuration::GetDateList(std::string_view key) const

Returns a list of date parameters.

Parameters
key Fully qualified parameter name.

Raises a KeyError if the parameter does not exist. Raises a TypeError if the parameter is of a different type.

void werkzeugkiste::config::Configuration::SetDateList(std::string_view key, const std::vector<date>& values)

Sets or replaces a list of date parameters.

Parameters
key Fully qualified parameter name.
values List of dates.

Raises a TypeError if the parameter exists but is of a different type.

time werkzeugkiste::config::Configuration::GetTime(std::string_view key) const

Returns the time parameter.

Parameters
key Fully qualified parameter name.

Raises a KeyError if the parameter does not exist. Raises a TypeError if the parameter is of a different type.

time werkzeugkiste::config::Configuration::GetTimeOr(std::string_view key, const time& default_val) const

Returns the time parameter or the default_val if it does not exist.

Parameters
key Fully qualified parameter name.
default_val Value to return if the parameter does not exist.

Raises a TypeError if the parameter exists but is of a different type.

std::optional<time> werkzeugkiste::config::Configuration::GetOptionalTime(std::string_view key) const

Returns an optional time or std::nullopt if it does not exist.

Parameters
key Fully qualified parameter name.

Raises a TypeError if the parameter exists but is of a different type.

void werkzeugkiste::config::Configuration::SetTime(std::string_view key, const time& value)

Sets a local time parameter.

Parameters
key Fully qualified parameter name.
value The value to be set.

Raises a TypeError if the parameter exists and is of a different type. Raises a std::logic_error if setting the value in the underlying TOML library failed for unforeseen/not handled reasons.

std::vector<time> werkzeugkiste::config::Configuration::GetTimeList(std::string_view key) const

Returns a list of time parameters.

Parameters
key Fully qualified parameter name.

Raises a KeyError if the parameter does not exist. Raises a TypeError if the parameter is of a different type.

void werkzeugkiste::config::Configuration::SetTimeList(std::string_view key, const std::vector<time>& values)

Sets or replaces a list of time parameters.

Parameters
key Fully qualified parameter name.
values List of times.

Raises a TypeError if the parameter exists but is of a different type.

date_time werkzeugkiste::config::Configuration::GetDateTime(std::string_view key) const

Returns the date-time parameter with optional timezone offset.

Parameters
key Fully qualified parameter name.

Raises a KeyError if the parameter does not exist. Raises a TypeError if the parameter is of a different type.

date_time werkzeugkiste::config::Configuration::GetDateTimeOr(std::string_view key, const date_time& default_val) const

Returns the date-time parameter or the default_val if it does not exist.

Parameters
key Fully qualified parameter name.
default_val Value to return if the parameter does not exist.

Raises a TypeError if the parameter exists but is of a different type.

std::optional<date_time> werkzeugkiste::config::Configuration::GetOptionalDateTime(std::string_view key) const

Returns an optional date_time or std::nullopt if it does not exist.

Parameters
key Fully qualified parameter name.

Raises a TypeError if the parameter exists but is of a different type.

void werkzeugkiste::config::Configuration::SetDateTime(std::string_view key, const date_time& value)

Sets a date-time parameter.

Parameters
key Fully qualified parameter name.
value The value to be set.

A date-time consists of a date, a time and an optional timezone offset, following RFC 3339, https://www.rfc-editor.org/rfc/rfc3339

Raises a TypeError if the parameter exists and is of a different type. Raises a std::logic_error if setting the value in the underlying TOML library failed for unforeseen/not handled reasons.

std::vector<date_time> werkzeugkiste::config::Configuration::GetDateTimeList(std::string_view key) const

Returns a list of date-time parameters.

Parameters
key Fully qualified parameter name.

Raises a KeyError if the parameter does not exist. Raises a TypeError if the parameter is of a different type.

void werkzeugkiste::config::Configuration::SetDateTimeList(std::string_view key, const std::vector<date_time>& values)

Sets or replaces a list of date-time parameters.

Parameters
key Fully qualified parameter name.
values List of date-times.

Raises a TypeError if the parameter exists but is of a different type.

void werkzeugkiste::config::Configuration::CreateList(std::string_view key)

Creates an empty list with the given name.

Parameters
key Fully qualified name of the parameter.

After successful creation, any values can be Appended.

Raises a KeyError if the key already exists or if a "parent" could not be created.

void werkzeugkiste::config::Configuration::ClearList(std::string_view key)

Clears an existing list.

Parameters
key Fully qualified name of the parameter.

Afterwards, any values can be Appended.

Raises a KeyError if the parameter does not exist. Raises a TypeError if the parameter is not a list.

void werkzeugkiste::config::Configuration::AppendList(std::string_view key)

Appends an empty list to an existing list in order to supported creating nested lists programmatically.

Parameters
key Fully qualified name of the existing list parameter.

Raises a KeyError if the key does not exist. Raises a TypeError if the key exists, but is not a list.

void werkzeugkiste::config::Configuration::Append(std::string_view key, bool value)

Appends a boolean flag to an existing list.

Parameters
key Fully qualified name of the existing list parameter.
value Value to be appended.

Raises a KeyError if the key does not exist. Raises a TypeError if the key exists, but is not a list.

void werkzeugkiste::config::Configuration::Append(std::string_view key, int32_t value)

Appends a 32-bit integer to an existing list.

Parameters
key Fully qualified name of the existing list parameter.
value Value to be appended.

Raises a KeyError if the key does not exist. Raises a TypeError if the key exists, but is not a list.

void werkzeugkiste::config::Configuration::Append(std::string_view key, int64_t value)

Appends a 64-bit integer to an existing list.

Parameters
key Fully qualified name of the existing list parameter.
value Value to be appended.

Raises a KeyError if the key does not exist. Raises a TypeError if the key exists, but is not a list.

void werkzeugkiste::config::Configuration::Append(std::string_view key, double value)

Appends a floating point value to an existing list.

Parameters
key Fully qualified name of the existing list parameter.
value Value to be appended.

Raises a KeyError if the key does not exist. Raises a TypeError if the key exists, but is not a list.

void werkzeugkiste::config::Configuration::Append(std::string_view key, std::string_view value)

Appends a string to an existing list.

Parameters
key Fully qualified name of the existing list parameter.
value Value to be appended.

Raises a KeyError if the key does not exist. Raises a TypeError if the key exists, but is not a list.

void werkzeugkiste::config::Configuration::Append(std::string_view key, const date& value)

Appends a date to an existing list.

Parameters
key Fully qualified name of the existing list parameter.
value Value to be appended.

Raises a KeyError if the key does not exist. Raises a TypeError if the key exists, but is not a list.

void werkzeugkiste::config::Configuration::Append(std::string_view key, const time& value)

Appends a local time to an existing list.

Parameters
key Fully qualified name of the existing list parameter.
value Value to be appended.

Raises a KeyError if the key does not exist. Raises a TypeError if the key exists, but is not a list.

void werkzeugkiste::config::Configuration::Append(std::string_view key, const date_time& value)

Appends a date-time to an existing list.

Parameters
key Fully qualified name of the existing list parameter.
value Value to be appended.

Raises a KeyError if the key does not exist. Raises a TypeError if the key exists, but is not a list.

void werkzeugkiste::config::Configuration::Append(std::string_view key, const Configuration& group)

Appends a group/sub-configuration to an existing list.

Parameters
key Fully qualified name of the existing list parameter.
group Group/"Sub-Configuration" to be appended.

Raises a KeyError if the key does not exist. Raises a TypeError if the key exists, but is not a list.

Configuration werkzeugkiste::config::Configuration::GetGroup(std::string_view key) const

Returns a copy of the sub-group.

Parameters
key Fully qualified name of the parameter (which must be a group, e.g. a JSON dictionary, a TOML table, or a libconfig group).

void werkzeugkiste::config::Configuration::SetGroup(std::string_view key, const Configuration& group)

Inserts (or replaces) the given configuration group.

Parameters
key Fully qualified name of the parameter. If it exists, it must already be a group. The empty string is not allowed. To replace the "root", create a new Configuration instance instead or use the overloaded assignment operators.
group The group to be inserted.

If the key already exists, it must be a group. Otherwise, the parameter will be newly created, along with all "parents" in the Fully qualified name (which defines a "path" through the configuration table/tree).

Matrix<uint8_t> werkzeugkiste::config::Configuration::GetMatrixUInt8(std::string_view key) const

Returns a list/nested list as a 2D matrix.

Parameters
key Fully qualified name of the parameter.
Returns Matrix of uint8_t values in row-major order. 
auto config = werkzeugkiste::config::LoadTOMLString(R"toml(
   mat = [
     [0, 127],
     [10, 100],
     [32, 64]]

   lst = [1, 2, 3]
   )toml");

// A nested list can be loaded as a matrix.
auto mat = config.GetMatrixUInt8("mat"sv);
assert(mat.rows() == 3);
assert(mat.cols() == 2);

// A single list will always be loaded as a row vector.
auto mat = config.GetMatrixUInt8("lst"sv);
assert(mat.rows() == 3);
assert(mat.cols() == 1);

Matrix<int32_t> werkzeugkiste::config::Configuration::GetMatrixInt32(std::string_view key) const

Returns a list/nested list as a 2D matrix.

Parameters
key Fully qualified name of the parameter.
Returns Matrix of int32_t values in row-major order. 
auto config = werkzeugkiste::config::LoadTOMLString(R"toml(
   mat = [
     [0, 127],
     [10, 100],
     [32, 64]]

   lst = [1, 2, 3]
   )toml");

// A nested list can be loaded as a matrix.
auto mat = config.GetMatrixInt32("mat"sv);
assert(mat.rows() == 3);
assert(mat.cols() == 2);

// A single list will always be loaded as a row vector.
auto mat = config.GetMatrixInt32("lst"sv);
assert(mat.rows() == 3);
assert(mat.cols() == 1);

Matrix<int64_t> werkzeugkiste::config::Configuration::GetMatrixInt64(std::string_view key) const

Returns a list/nested list as a 2D matrix.

Parameters
key Fully qualified name of the parameter.
Returns Matrix of int64_t values in row-major order. 
auto config = werkzeugkiste::config::LoadTOMLString(R"toml(
   mat = [
     [0, 127],
     [10, 100],
     [32, 64]]

   lst = [1, 2, 3]
   )toml");

// A nested list can be loaded as a matrix.
auto mat = config.GetMatrixInt64("mat"sv);
assert(mat.rows() == 3);
assert(mat.cols() == 2);

// A single list will always be loaded as a row vector.
auto mat = config.GetMatrixInt64("lst"sv);
assert(mat.rows() == 3);
assert(mat.cols() == 1);

Matrix<float> werkzeugkiste::config::Configuration::GetMatrixFloat(std::string_view key) const

Returns a list/nested list as a 2D matrix.

Parameters
key Fully qualified name of the parameter.
Returns Matrix of float values in row-major order. 
auto config = werkzeugkiste::config::LoadTOMLString(R"toml(
   mat = [
     [0, 127],
     [10, 100],
     [32, 64]]

   lst = [1, 2, 3]
   )toml");

// A nested list can be loaded as a matrix.
auto mat = config.GetMatrixFloat("mat"sv);
assert(mat.rows() == 3);
assert(mat.cols() == 2);

// A single list will always be loaded as a row vector.
auto mat = config.GetMatrixFloat("lst"sv);
assert(mat.rows() == 3);
assert(mat.cols() == 1);

Matrix<double> werkzeugkiste::config::Configuration::GetMatrixDouble(std::string_view key) const

Returns a list/nested list as a 2D matrix.

Parameters
key Fully qualified name of the parameter.
Returns Matrix of double values in row-major order. 
auto config = werkzeugkiste::config::LoadTOMLString(R"toml(
   mat = [
     [0, 127],
     [10, 100],
     [32, 64]]

   lst = [1, 2, 3]
   )toml");

// A nested list can be loaded as a matrix.
auto mat = config.GetMatrixDouble("mat"sv);
assert(mat.rows() == 3);
assert(mat.cols() == 2);

// A single list will always be loaded as a row vector.
auto mat = config.GetMatrixDouble("lst"sv);
assert(mat.rows() == 3);
assert(mat.cols() == 1);

template<typename Derived, typename TpMat = typename Derived::Scalar>
void werkzeugkiste::config::Configuration::SetMatrix(std::string_view key, const Eigen::MatrixBase<Derived>& mat)

Stores a matrix as list.

Template parameters
Derived Eigen matrix type.
TpMat The corresponding scalar type.
Parameters
key Fully qualified parameter name.
mat The Eigen::Matrix or Eigen::Vector.

Matrices will be stored as lists of either 64-bit integers or double precision floating point numbers, depending on the Scalar type of the matrix. Nx1 or 1xN matrices (i.e. column or row vectors) will be stored as a single list. RxC matrices will be stored as nested lists.

Any dense matrix type is supported. To extend this functionality for other types, refer to: https://eigen.tuxfamily.org/dox/TopicFunctionTakingEigenTypes.html

bool werkzeugkiste::config::Configuration::AdjustRelativePaths(std::string_view key, std::string_view base_path, const std::vector<std::string_view>& parameters)

Adjusts the given parameters below the key group to hold either an absolute file path, or the result of "base_path / <param>" if they initially held a relative file path.

Parameters
key Fully qualified parameter name.
base_path Base path to be prepended to relative file paths.
parameters A list of parameter names / patterns. The wildcard '*' is also supported. For example, valid names are: "my-param", "files.video1", etc. Valid patterns would be "*path", "some.nested.*.filename", etc. Parameters that match the pattern, but are not strings will be skipped.
Returns True if any parameter has been adjusted.

bool werkzeugkiste::config::Configuration::AdjustRelativePaths(std::string_view base_path, const std::vector<std::string_view>& parameters)

Adjusts the given parameters below the configuration root to hold either an absolute file path, or the result of "base_path / <param>" if they initially held a relative file path.

Parameters
base_path Base path to be prepended to relative file paths.
parameters A list of parameter names / patterns. The wildcard '*' is also supported. For example, valid names are: "my-param", "files.video1", etc. Valid patterns would be "*path", "some.nested.*.filename", etc. Parameters that match the pattern, but are not strings will be skipped.
Returns True if any parameter has been adjusted.

bool werkzeugkiste::config::Configuration::ReplaceStringPlaceholders(std::string_view key, const std::vector<std::pair<std::string_view, std::string_view>>& replacements)

Visits all string parameters below the given key group and replaces any occurrence of the given needle/replacement pairs.

Parameters
key Fully qualified parameter name.
replacements List of <search, replacement> pairs.
Returns True if any placeholder has actually been replaced.

bool werkzeugkiste::config::Configuration::ReplaceStringPlaceholders(const std::vector<std::pair<std::string_view, std::string_view>>& replacements)

Visits all string parameters below the root configuration and replaces any occurrence of the given needle/replacement pairs.

Parameters
replacements List of <search, replacement> pairs.
Returns True if any placeholder has actually been replaced.

void werkzeugkiste::config::Configuration::LoadNestedConfiguration(std::string_view key)

Loads a nested configuration.

Parameters
key Parameter name (Fully qualified TOML path) which holds the file name of the nested configuration file. The file name must be given as string.

For example, if your configuration had a field "storage", which should be defined in a separate (e.g. machine-dependent) configuration file, the "main" config could define it as storage = "path/to/conf.toml" This function will then load this TOML and replace storage by the loaded configuration. Suppose that conf.toml defines location = ... and duration = .... Then, after loading, you can access these as "storage.location" and "storage.duration".

This method deduces the type of the configuration from the file extension, similar to LoadFile.

Raises a KeyError if the parameter does not exist. Raises a TypeError if the parameter is not a string. Raises a ParseError if parsing the external configuration failed. Raises a std::runtime_error if replacing the internal configuration failed for unforeseen reasons.