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 86 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. More...

typedef std::list< configTarget >::iterator	clOnlyTargetIterator
	Iterator for the clOnlyTargets list. More...

Public Member Functions
void	clear ()
	Clear the containers and free up the associated memory. More...

void	add (const configTarget &tgt)
	Add a configTarget. More...

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

void	parseCommandLine (int argc, char **argv, const std::string &oneTarget="")
	Parse the command line, updating the targets. More...

int	readConfig (const std::string &fname, bool reportFileNotFound=true)
	Read and parse a config/ini file, updating the targets. More...

bool	isSet (const std::string &name, std::unordered_map< std::string, configTarget > &targets)
	Check if a target has been set by the configuration. More...

bool	isSet (const std::string &name)
	Check if a target has been set by the configuration. More...

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

int	count (const std::string &name)
	Get the number of different values set for the specified config target. More...

int	verbosity (const std::string &name, std::unordered_map< std::string, configTarget > &targets)
	Get the command line verbosity count for this option. More...

int	verbosity (const std::string &name)
	Get the command line verbosity count for this option. More...

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

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

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

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

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

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

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

template<typename typeT >
int	get (std::vector< typeT > &v, const std::string &name)
	Get the i-th value of the target in the used set, as a vector containing the specified type. More...

template<typename typeT >
int	operator() (typeT &v, const std::string &name)
	Access operator, configures a value by calling get. More...

template<typename typeT >
int	configUnused (typeT &v, const std::string &key)
	Configure a value from the unused map, using the iniFile key. More...

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

int	unusedSections (std::vector< std::string > &sections)
	Get the unique sections in the unused config targets. More...

int	isSetUnused (const std::string &name)
	Check if a target has been set in the unused configuration. More...

int	numUnknownOptions ()
	Get the number of unknown options found during config processing. More...

Public Attributes
std::unordered_map< std::string, configTarget >	m_targets
	The targets are stored in an unordered_map for fast access by key. More...

std::unordered_map< std::string, configTarget >	m_unusedConfigs
	Config file entries present in the file(s), but not corresponding to a target when parsed. Set aside for possible analysis. More...

std::list< configTarget >	clOnlyTargets
	Targets which are only for the command line are stored separately in a list. More...

std::vector< std::string >	nonOptions
	Non-option arguments from the command line. More...

int	nAdded {0}
	Running count of options added, used to track order. More...

bool	m_sources {false}
	Flag controlling whether or not to record config sources. More...

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(). More...

Member Typedef Documentation

◆ clOnlyTargetIterator

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

Iterator for the clOnlyTargets list.

Definition at line 92 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 89 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::vonKarmanSpectrum< realT >::setupConfig(), mx::AO::analysis::aoSystem< _realT, _inputSpectT, iosT >::setupConfig(), mx::app::application::setupStandardConfig(), mx::app::application::setupStandardHelp(), 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 62 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 mx::app::application::main().

◆ 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 1173 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 1244 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 243 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 235 of file appConfigurator.cpp.

Referenced by count().

◆ get() [1/8]

template<typename typeT >

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

Get the i-th 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 1026 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 864 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 715 of file appConfigurator.hpp.

References configLog, isSet(), and m_sources.

◆ 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 938 of file appConfigurator.hpp.

References 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 644 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 480 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 377 of file appConfigurator.hpp.

References configLog, mx::ioutils::convertToString(), isSet(), and m_sources.

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

◆ 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 554 of file appConfigurator.hpp.

References configLog, mx::ioutils::convertToString(), 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 230 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 219 of file appConfigurator.cpp.

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

◆ 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 995 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 1099 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 75 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 mx::app::application::reReadConfig(), and mx::app::application::setup().

◆ 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::app::iniFile::count(), mx::app::iniFile::erase(), m_sources, m_targets, m_unusedConfigs, mx::app::iniFile::names, mx::app::iniFile::parse(), and mx::app::iniFile::parseKey().

Referenced by mx::app::application::reReadConfig(), SCENARIO(), and mx::app::application::setup().

◆ 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 967 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 256 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 248 of file appConfigurator.cpp.

Referenced by 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 101 of file appConfigurator.hpp.

Referenced by add(), clear(), mx::app::application::help(), and parseCommandLine().

◆ 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 366 of file appConfigurator.hpp.

Referenced by get().

◆ m_sources

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

Flag controlling whether or not to record config sources.

Definition at line 110 of file appConfigurator.hpp.

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

◆ 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 95 of file appConfigurator.hpp.

Referenced by add(), clear(), count(), get(), mx::app::application::help(), isSet(), operator()(), parseCommandLine(), readConfig(), 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 98 of file appConfigurator.hpp.

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

◆ nAdded

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

Running count of options added, used to track order.

Definition at line 107 of file appConfigurator.hpp.

Referenced by add().

◆ nonOptions

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

Non-option arguments from the command line.

Definition at line 104 of file appConfigurator.hpp.

Referenced by clear(), and parseCommandLine().

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