Class to manage a set of configurable values, and read their values from config/ini files and the command line.

The configuration files are TOML/ini-style, with sections. That is

key1=value1
key2=value2

[section1]
key3=value3
key4=value4,value4.1, value4.2, value4.3

[section2]
key3=value5
key3=value5.1
key4=value6_over_
     multiple_lines

such that section1.key3 is distinct from section2.key3 (they must have different config-target names though).

Additional syntax rules:

Leading whitespace is stripped from the value, so key=val and key= val are equivalent.
Additional entries within one file with the same section and key are appended to the previous entry. So the value of section2.key3 is "value5value5.1".
Multi-line values are handled such that in the above example the result is key4=value6_over_multiple_lines.
Vectors are input as comma separated lists, as in section1.key4 above. Leading whitespace is stripped from each component of the vector.

Todo

add handling of += in subsequent files.

should just swith to strict TOML

The command line parser handles both short-opt ("-h -vArg -n Arg") and long-opt ("--help --value=Arg --number=Arg") styles.

Bug: a config=value pair listed in a conf file twice seems to cause a failure, even if they are the same value.

Definition at line 96 of file appConfigurator.hpp.

#include <app/appConfigurator.hpp>

Public Types
typedef std::unordered_map< std::string, configTarget >::iterator	targetIterator
	Iterator for the targets unordered_map.
typedef std::list< configTarget >::iterator	clOnlyTargetIterator
	Iterator for the clOnlyTargets list.

Public Member Functions
void	clear ()
	Clear the containers and free up the associated memory.
void	add (const configTarget &tgt)
	Add a configTarget.
void	add (const std::string &n, const std::string &so, const std::string &lo, int clt, const std::string &s, const std::string &kw, bool isReq=false, const std::string &ht="", const std::string &he="")
	Add a configTarget.
void	parseCommandLine (int argc, char **argv, const std::string &oneTarget="")
	Parse the command line, updating the targets.
int	readConfig (const std::string &fname, bool reportFileNotFound=true)
	Read and parse a config/ini file, updating the targets.
bool	isSet (const std::string &name, std::unordered_map< std::string, configTarget > &targets)
	Check if a target has been set by the configuration.
bool	isSet (const std::string &name)
	Check if a target has been set by the configuration.
int	count (const std::string &name, std::unordered_map< std::string, configTarget > &targets)
	Get the number of different values set for the specified config target.
int	count (const std::string &name)
	Get the number of different values set for the specified config target.
int	verbosity (const std::string &name, std::unordered_map< std::string, configTarget > &targets)
	Get the command line verbosity count for this option.
int	verbosity (const std::string &name)
	Get the command line verbosity count for this option.
template<typename typeT>
int	get (typeT &v, const std::string &name, size_t i, std::unordered_map< std::string, configTarget > &targets)
	Get the i-th value of the target, converted to the specified type.
template<typename typeT>
int	get (typeT &v, const std::string &name, size_t i)
	Get the i-th value of the target from the used set, converted to the specified type.
template<typename typeT>
int	get (typeT &v, const std::string &name, std::unordered_map< std::string, configTarget > &targets)
	Get the final value of the target, converted to the specified type.
template<typename typeT>
int	get (typeT &v, const std::string &name)
	Get the final value of the target from the used set, converted to the specified type.
template<typename typeT>
int	get (std::vector< typeT > &v, const std::string &name, size_t i, std::unordered_map< std::string, configTarget > &targets)
	Get the i-th value of the target, converted to the specified config target.
template<typename typeT>
int	get (std::vector< typeT > &v, const std::string &name, size_t i)
	Get the i-th value of the target, converted to the specified config target.
template<typename typeT>
int	get (std::vector< typeT > &v, const std::string &name, std::unordered_map< std::string, configTarget > &targets)
	Get the i-th value of the target as a vector containing the specified type.
template<typename typeT>
int	get (std::vector< typeT > &v, const std::string &name)
	Get the final value of the target in the used set, as a vector containing the specified type.
template<typename typeT>
int	operator() (typeT &v, const std::string &name)
	Access operator, configures a value by calling get.
template<typename typeT>
int	configUnused (typeT &v, const std::string &key)
	Configure a value from the unused map, using the iniFile key.
template<typename typeT>
int	configUnused (typeT &v, const std::string &section, const std::string &keyword)
	Configure a value from the unused map, using the section and keyword.
int	unusedSections (std::vector< std::string > &sections)
	Get the unique sections in the unused config targets.
int	isSetUnused (const std::string &name)
	Check if a target has been set in the unused configuration.
int	numUnknownOptions ()
	Get the number of unknown options found during config processing.

Public Attributes
std::unordered_map< std::string, configTarget >	m_targets
	The targets are stored in an unordered_map for fast access by key.
std::unordered_map< std::string, configTarget >	m_unusedConfigs
std::list< configTarget >	clOnlyTargets
	Targets which are only for the command line are stored separately in a list.
std::vector< std::string >	nonOptions
	Non-option arguments from the command line.
int	nAdded { 0 }
	Running count of options added, used to track order.
bool	m_sources { false }
	Flag controlling whether or not to record config sources.
void(*	configLog )(const std::string &name, const int &code, const std::string &valueStr, const std::string &source)
	Call an external logging function whenever a config value is accessed by get or operator().

Member Typedef Documentation

◆ clOnlyTargetIterator

typedef std::list<configTarget>::iterator mx::app::appConfigurator::clOnlyTargetIterator

Iterator for the clOnlyTargets list.

Definition at line 102 of file appConfigurator.hpp.

◆ targetIterator

typedef std::unordered_map<std::string,configTarget>::iterator mx::app::appConfigurator::targetIterator

Iterator for the targets unordered_map.

Definition at line 99 of file appConfigurator.hpp.

Member Function Documentation

◆ add() [1/2]

void mx::app::appConfigurator::add ( const configTarget & tgt )

Add a configTarget.

Note that if name is a duplicate but the section and keyword are empty, it is handled as command-line only.

Parameters

[in] tgt The configuration target to add

Definition at line 43 of file appConfigurator.cpp.

References clOnlyTargets, mx::app::configTarget::keyword, m_targets, nAdded, mx::app::configTarget::name, and mx::app::configTarget::section.

Referenced by add(), mx::AO::analysis::aoAtmosphere< _realT >::setupConfig(), mx::AO::analysis::aoSystem< _realT, _inputSpectT, iosT >::setupConfig(), mx::AO::analysis::vonKarmanSpectrum< realT >::setupConfig(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), and unusedSections().

◆ add() [2/2]

void mx::app::appConfigurator::add	(	const std::string &	n,
		const std::string &	so,
		const std::string &	lo,
		int	clt,
		const std::string &	s,
		const std::string &	kw,
		bool	isReq = false,
		const std::string &	ht = "",
		const std::string &	he = "" )

Add a configTarget.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

[in]	n	The name of the target
[in]	so	The command-line short option (e.g. "f" for -f)
[in]	lo	The command-line long option (e.g. "file" for –file)
[in]	clt	The command-line option type, argType::false, argType::true, argType::optional, argType::required
[in]	s	The config file section name, can be empty ""
[in]	kw	The config file keyword, read in a "keyword=value" pair
[in]	isReq	Whether or not this option is required to be set
[in]	ht	The type to display in the help message
[in]	he	The explanation to display in the help message

Definition at line 61 of file appConfigurator.cpp.

References add().

◆ clear()

void mx::app::appConfigurator::clear ( )

Clear the containers and free up the associated memory.

Definition at line 35 of file appConfigurator.cpp.

References clOnlyTargets, m_targets, m_unusedConfigs, and nonOptions.

Referenced by TEST_CASE().

◆ configUnused() [1/2]

template<typename typeT>

int mx::app::appConfigurator::configUnused	(	typeT &	v,
		const std::string &	key )

Configure a value from the unused map, using the iniFile key.

Return values

0	on success
-1	on error

Parameters

[out]	v	the variable to populate (either scalar or vector), will be unaltered if not set.
[in]	key	the iniFile key for this target.

Definition at line 1119 of file appConfigurator.hpp.

References get(), and m_unusedConfigs.

Referenced by configUnused().

◆ configUnused() [2/2]

template<typename typeT>

int mx::app::appConfigurator::configUnused	(	typeT &	v,
		const std::string &	section,
		const std::string &	keyword )

Configure a value from the unused map, using the section and keyword.

Return values

0	on success
-1	on error

Parameters

[out]	v	the variable to populate (either scalar or vector), will be unaltered if not set.
[in]	section	the section name for this target
[in]	keyword	the keyword for this target.

Definition at line 1162 of file appConfigurator.hpp.

References configUnused(), and mx::app::iniFile::makeKey().

◆ count() [1/2]

int mx::app::appConfigurator::count ( const std::string & name )

Get the number of different values set for the specified config target.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Returns: the number of different values set for name.

Parameters

[in] name the target name

Definition at line 242 of file appConfigurator.cpp.

References count(), and m_targets.

◆ count() [2/2]

int mx::app::appConfigurator::count	(	const std::string &	name,
		std::unordered_map< std::string, configTarget > &	targets )

Get the number of different values set for the specified config target.

Returns: the number of different values set for name.

Parameters

[in]	name	the target name
[in]	targets	the map of config targets to use

Definition at line 236 of file appConfigurator.cpp.

Referenced by count(), and TEST_CASE().

◆ get() [1/8]

template<typename typeT>

int mx::app::appConfigurator::get	(	std::vector< typeT > &	v,
		const std::string &	name )

Get the final value of the target in the used set, as a vector containing the specified type.

The vector is only populated if the config target was set. If it is populated, it is cleared first. Thus if a vector filled with default values is passed in, it will only be overwritten if the user specified new values.

Return values

0	on success.
-1	on error.

Parameters

[out]	v	the vector to populate
[in]	name	the config target name.

Definition at line 1027 of file appConfigurator.hpp.

References get(), and m_targets.

◆ get() [2/8]

template<typename typeT>

int mx::app::appConfigurator::get	(	std::vector< typeT > &	v,
		const std::string &	name,
		size_t	i )

Get the i-th value of the target, converted to the specified config target.

The vector is only populated if the config target was set. If it is populated, it is cleared first. Thus if a vector filled with default values is passed in, it will only be overwritten if the user specified new values.

Returns: 0 on success; -1 on error

Parameters

[out]	v	the vector to populate
[in]	name	the config target name.
[in]	i	the number of config specification to get.

Definition at line 881 of file appConfigurator.hpp.

References get(), and m_targets.

◆ get() [3/8]

template<typename typeT>

int mx::app::appConfigurator::get	(	std::vector< typeT > &	v,
		const std::string &	name,
		size_t	i,
		std::unordered_map< std::string, configTarget > &	targets )

Get the i-th value of the target, converted to the specified config target.

The vector is only populated if the config target was set. If it is populated, it is cleared first. Thus if a vector filled with default values is passed in, it will only be overwritten if the user specified new values.

Returns: 0 on success; -1 on error

Parameters

[out]	v	the vector to populate
[in]	name	the config target name.
[in]	i	the number of config specification to get.
[in]	targets	the map of config targets to use

Definition at line 706 of file appConfigurator.hpp.

References mx::meta::typeDescription< T >::code(), configLog, isSet(), m_sources, and mx::ioutils::stoT().

◆ get() [4/8]

template<typename typeT>

int mx::app::appConfigurator::get	(	std::vector< typeT > &	v,
		const std::string &	name,
		std::unordered_map< std::string, configTarget > &	targets )

Get the i-th value of the target as a vector containing the specified type.

The vector is only populated if the config target was set. If it is populated, it is cleared first. Thus if a vector filled with default values is passed in, it will only be overwritten if the user specified new values.

Return values

0	on success.
-1	on error.

Parameters

[out]	v	the vector to populate
[in]	name	the config target name.
[in]	targets	the map of config targets to use

Definition at line 931 of file appConfigurator.hpp.

References mx::meta::typeDescription< T >::code(), configLog, get(), and isSet().

◆ get() [5/8]

template<typename typeT>

int mx::app::appConfigurator::get	(	typeT &	v,
		const std::string &	name )

Get the final value of the target from the used set, converted to the specified type.

The supplied value is only altered if the config target was set, which preserves. default values.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Return values

0	on success.
-1	on error.

Parameters

[out]	v	the variable to store the value in
[in]	name	the config target name

Definition at line 662 of file appConfigurator.hpp.

References get(), and m_targets.

◆ get() [6/8]

template<typename typeT>

int mx::app::appConfigurator::get	(	typeT &	v,
		const std::string &	name,
		size_t	i )

Get the i-th value of the target from the used set, converted to the specified type.

The supplied value is only altered if the config target was set, which preserves. default values.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Return values

0	on success
-1	on error

Parameters

[out]	v	the variable to store the value in
[in]	name	the config target name
[in]	i	the number of config specification to get.

Definition at line 524 of file appConfigurator.hpp.

References get(), and m_targets.

◆ get() [7/8]

template<typename typeT>

int mx::app::appConfigurator::get	(	typeT &	v,
		const std::string &	name,
		size_t	i,
		std::unordered_map< std::string, configTarget > &	targets )

Get the i-th value of the target, converted to the specified type.

The supplied value is only altered if the config target was set, which preserves. default values.

Return values

0	on success
-1	on error

Parameters

[out]	v	the variable to store the value in, unaltered if not set.
[in]	name	the config target name
[in]	i	the number of config specification to get.
[in]	targets	the map of config targets to use

Definition at line 394 of file appConfigurator.hpp.

References mx::meta::typeDescription< T >::code(), configLog, isSet(), m_sources, and mx::ioutils::stoT().

Referenced by configUnused(), get(), get(), get(), get(), get(), get(), operator()(), TEST_CASE(), TEST_CASE(), and TEST_CASE().

◆ get() [8/8]

template<typename typeT>

int mx::app::appConfigurator::get	(	typeT &	v,
		const std::string &	name,
		std::unordered_map< std::string, configTarget > &	targets )

Get the final value of the target, converted to the specified type.

The supplied value is only altered if the config target was set, which preserves. default values.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Return values

0	on success.
-1	on error.

Parameters

[out]	v	the variable to store the value in
[in]	name	the config target name
[in]	targets	the map of config targets to use

Definition at line 570 of file appConfigurator.hpp.

References mx::meta::typeDescription< T >::code(), configLog, get(), and isSet().

◆ isSet() [1/2]

bool mx::app::appConfigurator::isSet ( const std::string & name )

Check if a target has been set by the configuration.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Returns: true if the configuration set at least one value for this target; false if no value was set.

Parameters

[in] name the target name

Definition at line 231 of file appConfigurator.cpp.

References isSet(), and m_targets.

◆ isSet() [2/2]

bool mx::app::appConfigurator::isSet	(	const std::string &	name,
		std::unordered_map< std::string, configTarget > &	targets )

Check if a target has been set by the configuration.

Returns: true if the configuration set at least one value for this target; false if no value was set.

Parameters

[in]	name	the target name
[in]	targets	the map of config targets to use

Definition at line 221 of file appConfigurator.cpp.

Referenced by get(), get(), get(), get(), isSet(), isSetUnused(), mx::AO::analysis::aoAtmosphere< _realT >::loadConfig(), mx::AO::analysis::aoSystem< _realT, _inputSpectT, iosT >::loadConfig(), TEST_CASE(), and TEST_CASE().

◆ isSetUnused()

int mx::app::appConfigurator::isSetUnused ( const std::string & name )

Check if a target has been set in the unused configuration.

Returns: true if the unused configuration set at least one value for this target; false if no value was set.

Parameters

[in] name the target name

Definition at line 888 of file appConfigurator.cpp.

References isSet(), and m_unusedConfigs.

◆ numUnknownOptions()

int mx::app::appConfigurator::numUnknownOptions ( )

Get the number of unknown options found during config processing.

◆ operator()()

template<typename typeT>

template int mx::app::appConfigurator::operator()	(	typeT &	v,
		const std::string &	name )

Access operator, configures a value by calling get.

Return values

0	on success
-1	on error

Parameters

[out]	v	the variable to populate (either scalar or vector), will be unaltered if not set.
[in]	name	the config target name.

Definition at line 1073 of file appConfigurator.hpp.

References get(), and m_targets.

◆ parseCommandLine()

void mx::app::appConfigurator::parseCommandLine	(	int	argc,
		char **	argv,
		const std::string &	oneTarget = "" )

Parse the command line, updating the targets.

Parameters

[in]	argc	standard command line result specifying number of argumetns in argv
[in]	argv	standard command line result containing the arguments.
[in]	oneTarget	[optional] if not empty, then only this target is extracted by the parser.

Definition at line 74 of file appConfigurator.cpp.

References mx::app::clOptions::add(), clOnlyTargets, mx::app::clOptions::count(), mx::app::clOptions::getAll(), m_sources, m_targets, m_unusedConfigs, nonOptions, mx::app::clOptions::nOpts, mx::app::clOptions::numUnknown(), mx::app::clOptions::optSet(), mx::app::clOptions::parse(), and mx::app::clOptions::unknown().

Referenced by TEST_CASE(), TEST_CASE(), and TEST_CASE().

◆ readConfig()

int mx::app::appConfigurator::readConfig	(	const std::string &	fname,
		bool	reportFileNotFound = true )

Read and parse a config/ini file, updating the targets.

Todo: handle += here, by appending to the last value as if a vector.

Todo: update error handling to include >0 (line numer of parse error) and -2 memory allocation error.

Parameters

[in]	fname	the config file name
[in]	reportFileNotFound	[optiona] control whether a file not found is reported.

Definition at line 149 of file appConfigurator.cpp.

References mx::allocerr, mx::app::iniFile::count(), mx::app::iniFile::erase(), mx::filenotfound, m_sources, m_targets, m_unusedConfigs, mx::internal::mxlib_error_report(), mx::app::iniFile::names, mx::app::iniFile::parse(), mx::parseerr, and mx::app::iniFile::parseKey().

Referenced by TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), and TEST_CASE().

◆ unusedSections()

int mx::app::appConfigurator::unusedSections ( std::vector< std::string > & sections )

Get the unique sections in the unused config targets.

Return values

0	on success
-1	on error

Definition at line 859 of file appConfigurator.cpp.

References add(), and m_unusedConfigs.

◆ verbosity() [1/2]

int mx::app::appConfigurator::verbosity ( const std::string & name )

Get the command line verbosity count for this option.

E.g., -v ==> 1, -vv ==> 2, -vvv ==> 3, etc. Note that for this to work properly, this must be of type mx::argType::True.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Returns: the verbosity count.

Parameters

[in] name the target name

Definition at line 253 of file appConfigurator.cpp.

References m_targets, and verbosity().

◆ verbosity() [2/2]

int mx::app::appConfigurator::verbosity	(	const std::string &	name,
		std::unordered_map< std::string, configTarget > &	targets )

Get the command line verbosity count for this option.

E.g., -v ==> 1, -vv ==> 2, -vvv ==> 3, etc. Note that for this to work properly, this must be of type mx::argType::True.

Returns: the verbosity count.

Parameters

[in]	name	the target name
[in]	targets	the map of config targets to use

Definition at line 247 of file appConfigurator.cpp.

Referenced by TEST_CASE(), and verbosity().

Member Data Documentation

◆ clOnlyTargets

std::list<configTarget> mx::app::appConfigurator::clOnlyTargets

Targets which are only for the command line are stored separately in a list.

Definition at line 112 of file appConfigurator.hpp.

Referenced by add(), clear(), parseCommandLine(), TEST_CASE(), and TEST_CASE().

◆ configLog

void(* mx::app::appConfigurator::configLog) (const std::string &name, const int &code, const std::string &valueStr, const std::string &source)

inline

Call an external logging function whenever a config value is accessed by get or operator().

Only called if this is not a nullptr (the default), otherwise no logging or reporting is done.

Definition at line 382 of file appConfigurator.hpp.

Referenced by get(), get(), get(), get(), TEST_CASE(), and TEST_CASE().

◆ m_sources

bool mx::app::appConfigurator::m_sources { false }

Flag controlling whether or not to record config sources.

Definition at line 121 of file appConfigurator.hpp.

Referenced by get(), get(), parseCommandLine(), readConfig(), TEST_CASE(), TEST_CASE(), TEST_CASE(), and TEST_CASE().

◆ m_targets

std::unordered_map<std::string, configTarget> mx::app::appConfigurator::m_targets

The targets are stored in an unordered_map for fast access by key.

Definition at line 105 of file appConfigurator.hpp.

Referenced by add(), clear(), count(), get(), get(), get(), get(), isSet(), operator()(), parseCommandLine(), readConfig(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), TEST_CASE(), and verbosity().

◆ m_unusedConfigs

std::unordered_map<std::string, configTarget> mx::app::appConfigurator::m_unusedConfigs

Config file entries present in the file(s), but not corresponding to a target when parsed. Set aside for possible analysis.

Definition at line 109 of file appConfigurator.hpp.

Referenced by clear(), configUnused(), isSetUnused(), parseCommandLine(), readConfig(), TEST_CASE(), TEST_CASE(), and unusedSections().

◆ nAdded

int mx::app::appConfigurator::nAdded { 0 }

Running count of options added, used to track order.

Definition at line 118 of file appConfigurator.hpp.

Referenced by add(), and TEST_CASE().

◆ nonOptions

std::vector<std::string> mx::app::appConfigurator::nonOptions

Non-option arguments from the command line.

Definition at line 115 of file appConfigurator.hpp.

Referenced by clear(), parseCommandLine(), and TEST_CASE().

The documentation for this struct was generated from the following files:

app/appConfigurator.hpp
/home/jrmales/Source/mxlib/source/app/appConfigurator.cpp

Public Types

Public Member Functions

Public Attributes

Member Typedef Documentation

◆ clOnlyTargetIterator

◆ targetIterator

Member Function Documentation

◆ add() [1/2]

◆ add() [2/2]

◆ clear()

◆ configUnused() [1/2]

◆ configUnused() [2/2]

◆ count() [1/2]

◆ count() [2/2]

◆ get() [1/8]

◆ get() [2/8]

◆ get() [3/8]

◆ get() [4/8]

◆ get() [5/8]

◆ get() [6/8]

◆ get() [7/8]

◆ get() [8/8]

◆ isSet() [1/2]

◆ isSet() [2/2]

◆ isSetUnused()

◆ numUnknownOptions()

◆ operator()()

◆ parseCommandLine()

◆ readConfig()

◆ unusedSections()

◆ verbosity() [1/2]

◆ verbosity() [2/2]

Member Data Documentation

◆ clOnlyTargets

◆ configLog

◆ m_sources

◆ m_targets

◆ m_unusedConfigs

◆ nAdded

◆ nonOptions