esp::core::config::Configuration class

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 getSubconfigValsOfTypeInVector(const std::string& subCfgName) const -> std::vector<float>
template<>
void setSubconfigValsOfTypeInVector(const std::string& subCfgName, const std::vector<float>& values)
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.
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.

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)

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.