class
#include <esp/core/Configuration.h>
Configuration 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 typeT
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 specifiedkey
. -
void set(const std::
string& key, const char* value) - Save the passed
value
char* as a string to the configuration at the passedkey
. -
void set(const std::
string& key, float value) - Save the passed float
value
as a double using the specifiedkey
. -
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 typeT
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 ConfigStoredTypedesiredType
. -
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 requestedkey
. 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 vector of all the config values this configuration holds and the types 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 give name.
-
void overwriteWithConfig(const std::
shared_ptr<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 tojsonName
within the passedjsonObj
. - 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 withkey
as name within the passedjsonObj
. -
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 byname
.
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 inconfig
. Returns the highest level wherekey
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:: |
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::
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::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::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 give 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<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::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 |