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 isDefaultVal(const std::string& key) const -> bool: Returns whether or not the ConfigValue specified by key is a default/initialization value or was intentionally set.
auto isHiddenVal(const std::string& key) const -> bool: Returns whether or not the ConfigValue specified by key is a hidden value intended to be be only used internally.
auto isTranslated(const std::string& key) const -> bool: Returns whether or not the ConfigValue specified by key is a translated value, meaning a string that corresponds to, and is translated into, an enum value for consumption.
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 .
void setTranslated(const std::string& key, const char* value): Save the passed string value using specified key as an translated/enum-backed value. This value will be translated by the consumer of this Configuration to be an enum constant and so should not use the generic Configuration file read functionality but rather an implementation that will verify the validity of the input.
void setTranslated(const std::string& key, const std::string& value): Save the passed string value using specified key as an translated/enum-backed value. This value will be translated by the consumer of this Configuration to be an enum constant and so should not use the generic Configuration file read functionality but rather an implementation that will verify the validity of the input.
template<typename T> void setHidden(const std::string& key, const T& value): Save the passed value using specified key as a hidden value, to be used internally but not saved or exposed to the user except for debug purposes.
void setHidden(const std::string& key, const char* value): Save the passed value char* as a string to the Configuration at the passed key as a hidden value, to be used internally but not saved or exposed to the user except for debug purposes.
void setHidden(const std::string& key, float value): Save the passed float value as a double using the specified key as a hidden value, to be used internally but not saved or exposed to the user except for debug purposes.
void setHiddenTranslated(const std::string& key, const char* value): Save the passed string value using specified key as an translated/enum-backed valuethat is also a hidden value, to be used internally but not saved or exposed to the user except for debug purposes.This value will be translated by the consumer of this Configuration to be an enum constant and so should not use the generic Configuration file read functionality but rather an implementation that will verify the validity of the input.
void setHiddenTranslated(const std::string& key, const std::string& value): Save the passed string value using specified key as an translated/enum-backed valuethat is also a hidden value, to be used internally but not saved or exposed to the user except for debug purposes.This value will be translated by the consumer of this Configuration to be an enum constant and so should not use the generic Configuration file read functionality but rather an implementation that will verify the validity of the input.
template<typename T> void init(const std::string& key, const T& value): Save the passed value using specified key as a programmatically set initial value (will not be written to file if this Configuration is saved unless it is changed via a file read or user input).
void init(const std::string& key, const char* value): Save the passed value char* as a string to the Configuration at the passed key as a programmatically set initial value (will not be written to file if this Configuration is saved unless it is changed via a file read or user input).
void init(const std::string& key, float value): Save the passed float value as a double using the specified key as a programmatically set initial value (will not be written to file if this Configuration is saved unless it is changed via a file read or user input).
void initTranslated(const std::string& key, const char* value): Save the passed string value using specified key as a programmatically set initial value (will not be written to file if this Configuration is saved unless it is changed via a file read or user input) of the translated/enum-backed value. This value will be translated by the consumer of this Configuration to be an enum constant and so should not use the generic Configuration file read functionality but rather an implementation that will verify the validity of the input.
void initTranslated(const std::string& key, const std::string& value): Save the passed string value using specified key as a programmatically set initial value (will not be written to file if this Configuration is saved unless it is changed via a file read or user input) of the translated/enum-backed value. This value will be translated by the consumer of this Configuration to be an enum constant and so should not use the generic Configuration file read functionality but rather an implementation that will verify the validity of the input.
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 getNumVisibleValues() const -> int: Returns number of non-hidden values in this Configuration. This is necessary for determining whether or not configurations are "effectively" equal, where they contain the same data but may vary in number internal-use-only fields.
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 hasKeyToValOfType(const std::string& key, ConfigValType desiredType) const -> 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 hasSubconfig(const std::shared_ptr<T>& subConfig) const -> bool: return if passed subConfig exists in this Configuration's subconfig map. Does not compare hidden ConfigValues.
template<typename T> auto getSubconfigCopy(const std::string& cfgName) 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 cfgName .
auto getSubconfigView(const std::string& cfgName) const -> std::shared_ptr<const Configuration>: return pointer to read-only sub-Configuration of given cfgName. Will fail if Configuration with given name dne.
template<typename T> auto editSubconfig(const std::string& cfgName) -> std::shared_ptr<T>: Templated Version. Retrieves the stored shared pointer to the subConfig esp::core::config::Configuration that has the passed cfgName , 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& cfgName, 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& cfgName) -> 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& cfgName) 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 src into this Configuration, including all subconfigs. Passed config overwrites existing data in this config.
void filterFromConfig(const std::shared_ptr<const Configuration>& src): Performs the opposite operation to Configuration::overwriteWithConfig. All values and subconfigs in the passed Configuration will be removed from this config unless the data they hold is different. Any empty subconfigs will be removed as well.
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.

Friends

auto operator==(const Configuration& a, const Configuration& b) -> bool: Comparison - Ignores ConfigValues specified as hidden.
auto operator!=(const Configuration& a, const Configuration& b) -> bool: Inequality Comparison - Ignores ConfigValues specified as hidden.

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.

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

Save the passed string value using specified key as an translated/enum-backed value. This value will be translated by the consumer of this Configuration to be an enum constant and so should not use the generic Configuration file read functionality but rather an implementation that will verify the validity of the input.

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

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

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

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

Save the passed value using specified key as a hidden value, to be used internally but not saved or exposed to the user except for debug purposes.

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

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

Save the passed value char* as a string to the Configuration at the passed key as a hidden value, to be used internally but not saved or exposed to the user except for debug purposes.

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::setHidden(const std::string& key, float value)

Save the passed float value as a double using the specified key as a hidden value, to be used internally but not saved or exposed to the user except for debug purposes.

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

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

Save the passed string value using specified key as an translated/enum-backed valuethat is also a hidden value, to be used internally but not saved or exposed to the user except for debug purposes.This value will be translated by the consumer of this Configuration to be an enum constant and so should not use the generic Configuration file read functionality but rather an implementation that will verify the validity of the input.

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

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

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

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

Save the passed value using specified key as a programmatically set initial value (will not be written to file if this Configuration is saved unless it is changed via a file read or user input).

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

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

Save the passed value char* as a string to the Configuration at the passed key as a programmatically set initial value (will not be written to file if this Configuration is saved unless it is changed via a file read or user input).

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::init(const std::string& key, float value)

Save the passed float value as a double using the specified key as a programmatically set initial value (will not be written to file if this Configuration is saved unless it is changed via a file read or user input).

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

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

Save the passed string value using specified key as a programmatically set initial value (will not be written to file if this Configuration is saved unless it is changed via a file read or user input) of the translated/enum-backed value. This value will be translated by the consumer of this Configuration to be an enum constant and so should not use the generic Configuration file read functionality but rather an implementation that will verify the validity of the input.

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

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

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

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::hasKeyToValOfType(const std::string& key, ConfigValType desiredType) const

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& cfgName) const

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

Parameters
cfgName	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& cfgName) const

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

Parameters
cfgName	The name of the desired Configuration.

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

Templated Version. Retrieves the stored shared pointer to the subConfig esp::core::config::Configuration that has the passed cfgName , 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
cfgName	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& cfgName, 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
cfgName	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& cfgName)

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

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

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

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

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

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 src 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.

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

Performs the opposite operation to Configuration::overwriteWithConfig. All values and subconfigs in the passed Configuration will be removed from this config unless the data they hold is different. Any empty subconfigs will be removed as well.

Parameters
src	The source of Configuration data we wish to prune from 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.

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