esp::core::config::Configuration class
#include <esp/core/Configuration.h>

This class holds configuration data in a map of ConfigValues, and also supports nested configurations via a map of smart pointers to this type.

Derived classes

class esp::metadata::attributes::AbstractAttributes: Base class for all implemented attributes. Inherits from esp::core::managedContainers::AbstractFileBasedManagedObject so the attributes can be managed by a esp::core::managedContainers::ManagedContainer.

Public types

using ValueMapType = std::unordered_map<std::string, ConfigValue>: Convenience typedef for the value map.
using ConfigMapType = std::map<std::string, std::shared_ptr<Configuration>>: Convenience typedef for the subconfiguration map.

Constructors, destructors, conversion operators

Configuration() defaulted: Constructor.
Configuration(const Configuration& otr): Copy Constructor.
Configuration(Configuration&& otr) noexcept: Move Constructor.
~Configuration() defaulted virtual

Public functions

auto operator=(const Configuration& otr) -> Configuration&: Copy Assignment.
auto operator=(Configuration&& otr) -> Configuration& defaulted noexcept: Move Assignment.
auto get(const std::string& key) const -> ConfigValue: Get ConfigValue specified by key, or empty ConfigValue if DNE.
template<class T> auto get(const std::string& key) const -> T: Get value specified by key and expected to be type T and return it if it exists and is appropriate type. Otherwise throw a warning and return a default value.
auto getType(const std::string& key) const -> ConfigStoredType: Return the ConfigStoredType enum representing the type of the value referenced by the passed key or ConfigStoredType::Unknown if unknown/unspecified.
auto getAsString(const std::string& key) const -> std::string: This method will look for the provided key, and return a string holding the object, if it is found in one of this configuration's maps.
auto getKeys() const -> std::vector<std::string>: Retrieve list of keys present in this Configuration's valueMap_. Subconfigs are not included.
auto getSubconfigKeys() const -> std::vector<std::string>: This function returns this Configuration's subconfig keys.
auto getStoredKeys(ConfigStoredType storedType) const -> std::vector<std::string>: Retrieve a list of all the keys in this Configuration pointing to values of passed type storedType.
template<typename T> void set(const std::string& key, const T& value): Save the passed value using specified key.
void set(const std::string& key, const char* value): Save the passed value char* as a string to the configuration at the passed key.
void set(const std::string& key, float value): Save the passed float value as a double using the specified key .
auto remove(const std::string& key) -> ConfigValue: Remove value specified by key and return it if it exists. Otherwise throw a warning and return a default value.
template<class T> auto remove(const std::string& key) -> T: Remove value specified by key and expected to be type T and return it if it exists and is appropriate type. Otherwise throw a warning and return a default value.
auto getNumEntries() const -> int: Return number of value and subconfig entries in this configuration. This only counts each subconfiguration entry as a single entry.
auto getNumSubconfigEntries() const -> int: Return number of subconfig entries in this configuration. This only counts each subconfiguration entry as a single entry.
auto getNumValues() const -> int: returns number of values in this configuration.
auto hasValue(const std::string& key) const -> bool: Returns whether this Configuration has the passed key as a non-configuration value. Does not check subconfigurations.
auto hasKeyOfType(const std::string& key, ConfigStoredType desiredType) -> bool: Whether passed key references a ConfigValue of passed ConfigStoredType desiredType.
auto findValue(const std::string& key) const -> std::vector<std::string>: Checks if passed key is contained in this configuration. Returns a list of nested subconfiguration keys, in order, to the configuration where the key was found, ending in the requested key. If list is empty, key was not found.
auto getConfigGroup() const -> Cr::Utility::ConfigurationGroup: Builds and returns Corrade::Utility::ConfigurationGroup holding the values in this esp::core::config::Configuration.
auto getValueTypes() const -> std::unordered_map<std::string, ConfigStoredType>: This method will build a map of the keys of all the config values this configuration holds and the types of each of these values.
auto hasSubconfig(const std::string& key) const -> bool: return if passed key corresponds to a subconfig in this configuration
template<class T> auto getSubconfigCopy(const std::string& name) const -> std::shared_ptr<T>: Templated subconfig copy getter. Retrieves a shared pointer to a copy of the subConfig esp::core::config::Configuration that has the passed name .
auto getSubconfigView(const std::string& name) const -> std::shared_ptr<const Configuration>: return pointer to read-only sub-configuration of given name. Will fail if configuration with given name dne.
template<class T> auto editSubconfig(const std::string& name) -> std::shared_ptr<T>: Templated Version. Retrieves the stored shared pointer to the subConfig esp::core::config::Configuration that has the passed name , cast to the specified type. This will create a shared pointer to a new sub-configuration if none exists and return it, cast to specified type.
template<class T> void setSubconfigPtr(const std::string& name, std::shared_ptr<T>& configPtr): move specified subgroup config into configMap at desired name. Will replace any subconfiguration at given name without warning if present.
auto removeSubconfig(const std::string& name) -> std::shared_ptr<Configuration>: Removes and returns the named subconfig. If not found, returns an empty subconfig with a warning.
auto getSubconfigNumEntries(const std::string& name) const -> int: Retrieve the number of entries held by the subconfig with the given name.
void overwriteWithConfig(const std::shared_ptr<const Configuration>& src): Merges configuration pointed to by config into this configuration, including all subconfigs. Passed config overwrites existing data in this config.
auto getValuesIterator() const -> std::pair<ValueMapType::const_iterator, ValueMapType::const_iterator>: Returns a const iterator across the map of values.
auto getSubconfigIterator() const -> std::pair<ConfigMapType::const_iterator, ConfigMapType::const_iterator>: Returns a const iterator across the map of subconfigurations.
auto loadFromJson(const io::JsonGenericValue& jsonObj) -> int: Load values into this Configuration from the passed jsonObj. Will recurse for subconfigurations.
auto writeToJsonObject(io::JsonAllocator& allocator) const -> io::JsonGenericValue: Build and return a json object holding the values and nested objects holding the subconfigs of this Configuration.
void writeValuesToJson(io::JsonGenericValue& jsonObj, io::JsonAllocator& allocator) const virtual: Populate a json object with all the first-level values held in this configuration. May be overridden to handle special cases for root-level configuration of Attributes classes derived from Configuration.
void writeSubconfigsToJson(io::JsonGenericValue& jsonObj, io::JsonAllocator& allocator) const virtual: Populate a json object with all the data from the subconfigurations, held in json sub-objects, for this Configuration.
void writeValueToJson(const char* key, const char* jsonName, io::JsonGenericValue& jsonObj, io::JsonAllocator& allocator) const: Take the passed key and query the config value for that key, writing it to jsonName within the passed jsonObj.
void writeValueToJson(const char* key, io::JsonGenericValue& jsonObj, io::JsonAllocator& allocator) const: Take the passed key and query the config value for that key, writing it to tag with key as name within the passed jsonObj.
auto getAllValsAsString(const std::string& newLineStr = "\n") const -> std::string: Return all the values in this cfg in a formatted string. Subconfigs will be displaced by a tab.
template<> auto getSubconfigCopy(const std::string& name) const -> std::shared_ptr<Configuration>: Retrieves a shared pointer to a copy of the subConfig esp::core::config::Configuration that has the passed name . This will create a pointer to a new sub-configuration if none exists already with that name, but will not add this configuration to this Configuration's internal storage.
template<> auto editSubconfig(const std::string& name) -> std::shared_ptr<Configuration>: Retrieve a shared pointer to the actual subconfiguration given by name, or a new subconfiguration with that name, if none exists.
template<> void setSubconfigPtr(const std::string& name, std::shared_ptr<Configuration>& configPtr): Save the passed Configuration pointed to by configPtr at location specified by name.

Protected static functions

static auto findValueInternal(const Configuration& config, const std::string& key, int parentLevel, std::vector<std::string>& breadcrumb) -> int: Friend function. Checks if passed key is contained in config. Returns the highest level where key was found.

Protected functions

void putAllValuesInConfigGroup(Cr::Utility::ConfigurationGroup& cfg) const: Populate the passed cfg with all the values this map holds, along with the values any subgroups/sub-Configs it may hold.
auto addSubgroup(const std::string& name) -> std::shared_ptr<Configuration>: if no subgroup with given name this will make one, otherwise does nothing.

Protected variables

ConfigMapType configMap_: Map to hold configurations as subgroups.
ValueMapType valueMap_: Map that holds all config values.

Function documentation

ConfigValue esp::core::config::Configuration::get(const std::string& key) const

Get ConfigValue specified by key, or empty ConfigValue if DNE.

Parameters
key	The key of the value desired to be retrieved.
Returns	ConfigValue specified by key. If none exists, will be empty ConfigValue, with type ConfigStoredType::Unknown

template<class T>
T esp::core::config::Configuration::get(const std::string& key) const

Get value specified by key and expected to be type T and return it if it exists and is appropriate type. Otherwise throw a warning and return a default value.

Parameters
key	The key of the value desired to be retrieved.
Returns	The value held at `key`, expected to be type `T` . If not found, or not of expected type, gives an error message and returns a default value.

std::vector<std::string> esp::core::config::Configuration::getStoredKeys(ConfigStoredType storedType) const

Retrieve a list of all the keys in this Configuration pointing to values of passed type storedType.

Parameters
storedType	The desired type of value whose key should be returned.
Returns	vector of string keys pointing to values of desired `storedType`

template<typename T>
void esp::core::config::Configuration::set(const std::string& key, const T& value)

Save the passed value using specified key.

Parameters
key	The key to assign to the passed value.
value	The value to save at given `key`

void esp::core::config::Configuration::set(const std::string& key, const char* value)

Save the passed value char* as a string to the configuration at the passed key.

Parameters
key	The key to assign to the passed value.
value	The char* to save at given `key` as a string.

void esp::core::config::Configuration::set(const std::string& key, float value)

Save the passed float value as a double using the specified key .

Parameters
key	The key to assign to the passed value.
value	The float value to save at given `key` as a double.

ConfigValue esp::core::config::Configuration::remove(const std::string& key)

Remove value specified by key and return it if it exists. Otherwise throw a warning and return a default value.

Parameters
key	The key of the value desired to be retrieved/removed.
Returns	The erased value, held at `key` if found. If not found, or not of expected type, gives a warning and returns a default value.

template<class T>
T esp::core::config::Configuration::remove(const std::string& key)

Remove value specified by key and expected to be type T and return it if it exists and is appropriate type. Otherwise throw a warning and return a default value.

Parameters
key	The key of the value desired to be retrieved/removed.
Returns	The erased value, held at `key` and expected to be type `T` , if found. If not found, or not of expected type, gives a warning and returns a default value.

bool esp::core::config::Configuration::hasKeyOfType(const std::string& key, ConfigStoredType desiredType)

Whether passed key references a ConfigValue of passed ConfigStoredType desiredType.

Parameters
key	The key to check the type of.
desiredType	the ConfigStoredType to compare the value's type to
Returns	Whether `key` references a value that is of `desiredType`.

std::vector<std::string> esp::core::config::Configuration::findValue(const std::string& key) const

Checks if passed key is contained in this configuration. Returns a list of nested subconfiguration keys, in order, to the configuration where the key was found, ending in the requested key. If list is empty, key was not found.

Parameters
key	The key to look for
Returns	A breadcrumb list to where the value referenced by `key` resides. An empty list means the value was not found.

Cr::Utility::ConfigurationGroup esp::core::config::Configuration::getConfigGroup() const

Builds and returns Corrade::Utility::ConfigurationGroup holding the values in this esp::core::config::Configuration.

Returns	a reference to a configuration group for this configuration object.

template<class T>
std::shared_ptr<T> esp::core::config::Configuration::getSubconfigCopy(const std::string& name) const

Templated subconfig copy getter. Retrieves a shared pointer to a copy of the subConfig esp::core::config::Configuration that has the passed name .

Parameters
name	The name of the configuration to retrieve.
Returns	A pointer to a copy of the configuration having the requested name, cast to the appropriate type, or nullptr if not found.

std::shared_ptr<const Configuration> esp::core::config::Configuration::getSubconfigView(const std::string& name) const

return pointer to read-only sub-configuration of given name. Will fail if configuration with given name dne.

Parameters
name	The name of the desired configuration.

template<class T>
std::shared_ptr<T> esp::core::config::Configuration::editSubconfig(const std::string& name)

Templated Version. Retrieves the stored shared pointer to the subConfig esp::core::config::Configuration that has the passed name , cast to the specified type. This will create a shared pointer to a new sub-configuration if none exists and return it, cast to specified type.

Parameters
name	The name of the configuration to edit.
Returns	The actual pointer to the configuration having the requested name, cast to the specified type.

Use this function when you wish to modify this configuration's subgroup, possibly creating it in the process.

template<class T>
void esp::core::config::Configuration::setSubconfigPtr(const std::string& name, std::shared_ptr<T>& configPtr)

move specified subgroup config into configMap at desired name. Will replace any subconfiguration at given name without warning if present.

Parameters
name	The name of the subconfiguration to add
configPtr	A pointer to a subconfiguration to add.

std::shared_ptr<Configuration> esp::core::config::Configuration::removeSubconfig(const std::string& name)

Removes and returns the named subconfig. If not found, returns an empty subconfig with a warning.

Parameters
name	The name of the subconfiguration to delete
Returns	a shared pointer to the removed subconfiguration.

int esp::core::config::Configuration::getSubconfigNumEntries(const std::string& name) const

Retrieve the number of entries held by the subconfig with the given name.

Parameters
name	The name of the subconfig to query. If not found, returns 0 with a warning.
Returns	The number of entries in the named subconfig

void esp::core::config::Configuration::overwriteWithConfig(const std::shared_ptr<const Configuration>& src)

Merges configuration pointed to by config into this configuration, including all subconfigs. Passed config overwrites existing data in this config.

Parameters
src	The source of configuration data we wish to merge into this configuration.

int esp::core::config::Configuration::loadFromJson(const io::JsonGenericValue& jsonObj)

Load values into this Configuration from the passed jsonObj. Will recurse for subconfigurations.

Parameters
jsonObj	The JSON object to read from for the data for this configuration.
Returns	The number of fields successfully read and populated.

void esp::core::config::Configuration::writeValueToJson(const char* key, const char* jsonName, io::JsonGenericValue& jsonObj, io::JsonAllocator& allocator) const

Take the passed key and query the config value for that key, writing it to jsonName within the passed jsonObj.

Parameters
key	The key of the data in the configuration
jsonName	The tag to use in the json file
jsonObj	The json object to write to
allocator	The json allocator to use to build the json object

void esp::core::config::Configuration::writeValueToJson(const char* key, io::JsonGenericValue& jsonObj, io::JsonAllocator& allocator) const

Take the passed key and query the config value for that key, writing it to tag with key as name within the passed jsonObj.

Parameters
key	The key of the data in the configuration
jsonObj	The json object to write to
allocator	The json allocator to use to build the json object

std::string esp::core::config::Configuration::getAllValsAsString(const std::string& newLineStr = "\n") const

Return all the values in this cfg in a formatted string. Subconfigs will be displaced by a tab.

Parameters
newLineStr	The string to put at the end of each newline. As subconfigs are called, add a tab to this.

template<>
std::shared_ptr<Configuration> esp::core::config::Configuration::getSubconfigCopy(const std::string& name) const

Retrieves a shared pointer to a copy of the subConfig esp::core::config::Configuration that has the passed name . This will create a pointer to a new sub-configuration if none exists already with that name, but will not add this configuration to this Configuration's internal storage.

Parameters
name	The name of the configuration to retrieve.
Returns	A pointer to a copy of the configuration having the requested name, or a pointer to an empty configuration.

template<>
std::shared_ptr<Configuration> esp::core::config::Configuration::editSubconfig(const std::string& name)

Retrieve a shared pointer to the actual subconfiguration given by name, or a new subconfiguration with that name, if none exists.

Parameters
name	The name of the desired subconfiguration
Returns	A pointer to the configuration having the requested name, or a pointer to an empty configuration.

template<>
void esp::core::config::Configuration::setSubconfigPtr(const std::string& name, std::shared_ptr<Configuration>& configPtr)

Save the passed Configuration pointed to by configPtr at location specified by name.

Parameters
name	The name to save the subconfiguration by
configPtr	A pointer to the Configuration to save with the given `name` .

static int esp::core::config::Configuration::findValueInternal(const Configuration& config, const std::string& key, int parentLevel, std::vector<std::string>& breadcrumb) protected

Friend function. Checks if passed key is contained in config. Returns the highest level where key was found.

Parameters
config	The configuration to search for passed key
key	The key to look for
parentLevel	The parent level to the current iteration. If iteration finds `key`, it will return parentLevel+1
breadcrumb	[out] List of keys to subconfigs to get to value. Always should end with `key`.
Returns	The level `key` was found. 0 if not found (so can be treated as bool)

std::shared_ptr<Configuration> esp::core::config::Configuration::addSubgroup(const std::string& name) protected

if no subgroup with given name this will make one, otherwise does nothing.

Parameters
name	Desired name of new subgroup.
Returns	whether a group was made or not

esp::core::config::Configuration class #include <esp/core/Configuration.h>