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.
class esp::metadata::attributes::LinkSet: This class provides an alias for the nested Configuration tree used for a single link's 1 or more MarkerSets that should be attached to the named link.
class esp::metadata::attributes::MarkerSet: This class provides an alias for a single Configuration holding 1 or more marker points within a particular LinkSet.
class esp::metadata::attributes::MarkerSets: This class provides an alias for the nested Configuration tree used to hold multiple TaskSets.
class esp::metadata::attributes::TaskSet: This class provides an alias for the nested Configuration tree used for a single TaskSet, holding 1 or more LinkSets.

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<typename 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 -> ConfigValType: Return the ConfigValType enum representing the type of the value referenced by the passed key or ConfigValType::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(bool sorted = false) const -> std::vector<std::string>: Retrieve list of keys present in this Configuration's valueMap_. Subconfigs are not included.
auto getSubconfigKeys(bool sorted = false) const -> std::vector<std::string>: This function returns this Configuration's subconfig keys.
auto getKeysByType(ConfigValType storedType, bool sorted = false) 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<typename 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.
template<typename T> void removeAllOfType(): Remove all values from this Configuration of the specified type.
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 getConfigTreeNumEntries() const -> int: Return total number of value and subconfig entries held by this Configuration and all its subconfigs.
auto getNumSubconfigs() const -> int: Return number of subconfig entries in this Configuration. This only counts each subconfiguration entry as a single entry.
auto getConfigTreeNumSubconfigs() const -> int: Return size of entire subconfig tree (i.e. total number of subconfigs nested under this Configuration.)
auto getNumValues() const -> int: returns number of values in this Configuration.
auto getConfigTreeNumValues() const -> int: Return total number of values held by this Configuration and all its subconfigs.
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, ConfigValType desiredType) -> bool: Whether passed key references a ConfigValue of passed ConfigValType 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, ConfigValType>: 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<typename 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<typename 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<typename 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.
auto getSubconfigTreeNumEntries(const std::string& cfgName) const -> int: Retrieve the number of entries held by the subconfig with the given cfgName , recursing subordinate subconfigs.
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.
template<typename T> auto getSubconfigValsOfTypeInVector(const std::string& subCfgName) const -> std::vector<T>: Get all values of passed type held within subconfig specified by given tag subCfgName and place the values into a vector.
template<typename T> void setSubconfigValsOfTypeInVector(const std::string& subCfgName, const std::vector<T>& values): Set all values from vector of passed type into subconfig specified by given tag subCfgName as key-value pairs where the key is the index in the vector as a string (to preserve vector ordering). This function will remove all existing values of specified type from the subconfig before adding the values specified in the given map.
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.
auto rekeySubconfigValues(const std::string& subconfigKey) -> int: Find the subconfiguration with the given handle and rekey it such that all the value entries it contains are keyed by sequential numeric strings. These keys will preserve the order of the original keys.
auto rekeyAllValues() -> int: Rekey all the value entries in this Configuration such that all their keys are sequential numeric strings that presever the order of their original strings.
void _clearAllValues(): Clear all key-value pairs from this Configuration's valueMap.
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

auto loadOneConfigFromJson(int numVals, const std::string& key, const io::JsonGenericValue& jsonObj) -> int: Process passed json object into this Configuration, using passed key.
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.
template<typename T> auto addOrEditSubgroup(const std::string& name) -> std::pair<ConfigMapType::iterator, bool>: Retrieves named subgroup; if no subgroup with given name exists this will make one.

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 ConfigValType::Unknown

template<typename 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::getKeys(bool sorted = false) const

Retrieve list of keys present in this Configuration's valueMap_. Subconfigs are not included.

Returns	a vector of strings representing the subconfig keys for this configuration.

std::vector<std::string> esp::core::config::Configuration::getSubconfigKeys(bool sorted = false) const

This function returns this Configuration's subconfig keys.

Parameters
sorted	whether the keys should be sorted or not.
Returns	a vector of strings representing the subconfig keys for this configuration.

std::vector<std::string> esp::core::config::Configuration::getKeysByType(ConfigValType storedType, bool sorted = false) 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.
sorted	whether the keys should be sorted or not.
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<typename 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, ConfigValType desiredType)

Whether passed key references a ConfigValue of passed ConfigValType desiredType.

Parameters
key	The key to check the type of.
desiredType	the ConfigValType 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<typename 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<typename 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<typename 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

int esp::core::config::Configuration::getSubconfigTreeNumEntries(const std::string& cfgName) const

Retrieve the number of entries held by the subconfig with the given cfgName , recursing subordinate subconfigs.

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

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.

template<typename T>
std::vector<T> esp::core::config::Configuration::getSubconfigValsOfTypeInVector(const std::string& subCfgName) const

Get all values of passed type held within subconfig specified by given tag subCfgName and place the values into a vector.

Parameters
subCfgName	The handle of the

This assumes the subconfig's values of the specified type are all intended to be considered as part of a vector of data.

template<typename T>
void esp::core::config::Configuration::setSubconfigValsOfTypeInVector(const std::string& subCfgName, const std::vector<T>& values)

Set all values from vector of passed type into subconfig specified by given tag subCfgName as key-value pairs where the key is the index in the vector as a string (to preserve vector ordering). This function will remove all existing values of specified type from the subconfig before adding the values specified in the given map.

Parameters
subCfgName	The handle of the desired subconfig to add the values to.
values	The vector of values of type `T` to add to the specified subconfig.

This assumes the subconfig's values of the specified type are all intended to be considered as part of a vector of data.

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.

int esp::core::config::Configuration::rekeySubconfigValues(const std::string& subconfigKey)

Find the subconfiguration with the given handle and rekey it such that all the value entries it contains are keyed by sequential numeric strings. These keys will preserve the order of the original keys.

Parameters
subconfigKey	The key of this Configuration's subconfig whose values' keys we wish to have rekeyed.
Returns	the number of values whose keys have been changed.

NOTE : all values regardless of type in this subconfig will be rekeyed. This function is primarily intended to be used on subconfigs holding a collection of the same type of date, to facilitate accessing this data as a sorted list.

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)

int esp::core::config::Configuration::loadOneConfigFromJson(int numVals, const std::string& key, const io::JsonGenericValue& jsonObj) protected

Process passed json object into this Configuration, using passed key.

Parameters
numVals	number of values/configs loaded so far
key	key to use to search `jsonObj` and also to set value or subconfig within this Configuration.
jsonObj
Returns	the number of total fields successfully loaded after this function executes.

template<typename T>
std::pair<ConfigMapType::iterator, bool> esp::core::config::Configuration::addOrEditSubgroup(const std::string& name) protected

Retrieves named subgroup; if no subgroup with given name exists this will make one.

Parameters
name	Name of desired existing or new subgroup.
Returns	The resultant pair after attempting to emplace a Configuration at the requested location given by `name`. Consists of an iterator to the Configuration, and a boolean value that denotes whether this is a new Configuration or it existed already.

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