Detailed Description

A class that reads a key/value file. These files (typically named *.ini) follow the INI file format standard (see http://en.wikipedia.org/wiki/INI_file) and have the following structure:

they consist of 0 or more explicitly indicated sections, which start with a sectionname enclosed in square brackets e.g. [General] or [Filter]
within each section there are 0 or more key value pairs defined: KEY = VALUE
in this implementation each key is unique within its section
lines that start with a semicolon ';' or a hash sign '#' are ignored (regarded as comments)
empty lines are ignored
if there is no section name given in a file, the default section called "GENERAL" is assumed
a VALUE for a KEY can consist of multiple whitespace separated values (e.g. MYNUMBERS = 17.77 -18.55 8888 99.99)
special values: there is a special syntax to refer to environment variables, to other keys or to evaluate arithmetic expressions:
- environment variables are called by using the following syntax: ${env:my_env_var};
- refering to another key (it only needs to be defined at some point in the ini file, even in an included file is enough): ${other_key} or ${section::other_key} (make sure to prefix the key with its section if it refers to another section!)
- evaluating an arithmetic expression: ${{arithm. expression}}

Note: The arithemic expressions are evaluated thanks to the tinyexpr math library (under the zlib license) and can use standard operators (including "^"), standard functions (such as "sin", "sqrt", "ln", "log", "exp", "floor"...) as well as the "pi" and "e" constants.

Imports

It is possible to import another ini file, by specifying as many of the keys listed below as necessary. Please note that there is a check to prevent circular dependencies.

IMPORT_BEFORE = {file and path to import}. This must take place before any non-import key or section header. This imports the specified file before processing the current file, allowing to overwrite the imported parameters in the current configuration file.
IMPORT_AFTER = {file and path to import}. This can occur anywhere and imports the specified file after processing the current file, allowing to overwrite the local parameters by the imported parameters.

Exemples

[Input]                                 ; this defines a section
InputFile = ./input/myfile.dat          ; this defines a key "InputFile" with the associated value "./input/myfile.dat"
#oldInput = ./test/test.dat             ; this is commented out
smart_read = false                      ; this defines the boolean key "smart_read"
fast_read = T                           ; this defines another boolean key, "fast_read"
 
user = ${env:LOGNAME}                   ; this uses the value of the environment variable "LOGNAME" for the key "user"
output_log = ${env:LOGNAME}_output.log  ; we can even concatenate environment variables with other elements
 
ConfigBackup = ${Input::user}_${smart_read}.bak ; using other keys to build a value (the section reference can be omitted within the same section)
Target_rate = ${{24*3600}}              ; arithmetic expression that will be evaluated when reading the key

#include <Config.h>

Public Member Functions
	Config ()
	Empty constructor. The user MUST later one fill the internal key/value map object. More...

	Config (const std::string &filename_in)
	Main constructor. The file is parsed and a key/value map object is internally created. More...

void	write (const std::string &filename) const
	Write the Config object to a file. More...

void	addFile (const std::string &filename_in)
	Add the content of a file to the internal key/value map object. More...

void	addKey (std::string key, std::string section, const std::string &value)
	Add a specific key/value pair to the internal key/value map object. key and section are case insensitive. More...

void	deleteKey (std::string key, std::string section)
	Delete a specific key/value pair from the internal map object, key/section are case insensitive. More...

void	deleteKeys (std::string keymatch, std::string section, const bool &anywhere=false)
	Delete keys matching a specific pattern from the internal map object, key/section are case insensitive. More...

std::string	getSourceName () const
	Returns the filename that the Config object was constructed with. More...

std::string	getConfigRootDir () const
	Returns the directory where the root configuration file is (needed to resolv relative paths). More...

bool	keyExists (std::string key, std::string section) const
	Return if a given key exists in a given section. More...

bool	sectionExists (std::string section) const
	Return if a given section exists in the Config object. More...

const std::string	toString () const
	Print the content of the Config object (useful for debugging) The Config is bound by "<Config>" and "</Config>" on separate lines. More...

template<typename T >
std::vector< T >	getValue (const std::string &key, std::string &section, const IOUtils::ThrowOptions &opt=IOUtils::dothrow) const

template<typename T >
void	getValue (const std::string &key, std::vector< T > &vecT, const IOUtils::ThrowOptions &opt=IOUtils::dothrow) const
	Template function to retrieve a vector of values of class T for a certain key. More...

template<typename T >
void	getValue (std::string key, std::string section, std::vector< T > &vecT, const IOUtils::ThrowOptions &opt=IOUtils::dothrow) const
	Template function to retrieve a vector of values of class T for a certain key. More...

const ConfigProxy	get (const std::string &key, const std::string &section) const
	A function that allows to retrieve a value for a key as return parameter (vectors of values too). More...

template<typename T >
T	get (const std::string &key, const std::string &section, const T &dflt) const
	A function that allows to retrieve a value for a key as return parameter (vectors of values too). More...

std::string	get (const std::string &key, const std::string &section, const std::string &dflt) const
	A function that allows to retrieve a value for a key as return parameter (vectors of values too). More...

std::string	get (const std::string &key, const std::string &section, const char dflt[]) const

double	get (const std::string &key, const std::string &section, const double &dflt) const

bool	get (const std::string &key, const std::string &section, const bool &dflt) const

template<typename T >
void	getValue (const std::string &key, T &t, const IOUtils::ThrowOptions &opt=IOUtils::dothrow) const
	Template function to retrieve a value of class T for a certain key. More...

template<typename T >
void	getValue (std::string key, std::string section, T &t, const IOUtils::ThrowOptions &opt=IOUtils::dothrow) const
	Template function to retrieve a value of class T for a certain key. More...

void	getValue (std::string key, std::string section, Date &t, const double &time_zone, const IOUtils::ThrowOptions &opt=IOUtils::dothrow) const
	Function to retrieve a Date value for a certain key. More...

template<typename T >
void	getValues (std::string keymatch, std::string section, std::vector< T > &vecT) const
	Template function to retrieve a vector of values of class T for a certain key pattern. More...

template<typename T >
void	getValues (std::string keymatch, std::string section, std::vector< T > &vecT, std::vector< std::string > &vecKeys) const

std::vector< std::pair< std::string, std::string > >	getValues (std::string keymatch, std::string section, const bool &anywhere=false) const
	Function that searches for a given string within the keys of a given section (default: GENERAL) it returns all the <keys,value> pairs that match (partial matches are considered) into a vector. More...

std::vector< std::pair< std::string, std::string > >	getValuesRegex (const std::string &regex_str, std::string section) const

std::vector< std::string >	getKeys (std::string keymatch, std::string section, const bool &anywhere=false) const
	Function that searches for a given string within the keys of a given section (default: GENERAL) it returns all the keys that match (partial matches are considered) into a vector<string>. More...

std::vector< std::string >	getKeysRegex (const std::string &regex_str, std::string section) const

std::set< std::string >	getSections () const
	Returns all the sections that are present in the config object. More...

void	moveSection (std::string org, std::string dest, const bool &overwrite)
	Move all keys of the org section to the dest section. More...

std::vector< std::pair< std::string, std::string > >	parseArgs (const std::string &section, const std::string &cmd_id, const unsigned int &cmd_nr, const std::string &arg_pattern) const
	Extract the arguments for a given command and store them into a vector of key / value pairs. More...

std::vector< std::pair< std::string, std::string > >	getArgumentsForAlgorithm (const std::string &parname, const std::string &algorithm, const std::string &section="Interpolations1d") const
	retrieve the resampling algorithm to be used for the 1D interpolation of meteo parameters. The potential arguments are also extracted. More...

Static Public Member Functions
static unsigned int	getCommandNr (const std::string &section, const std::string &cmd_pattern, const std::string &cmd_key)
	Extract the command number from a given command string, given the command pattern. More...

Friends
std::ostream &	operator<< (std::ostream &os, const Config &cfg)

std::istream &	operator>> (std::istream &is, Config &cfg)

Constructor & Destructor Documentation

◆ Config() [1/2]

mio::Config::Config ( )

Empty constructor. The user MUST later one fill the internal key/value map object.

◆ Config() [2/2]

mio::Config::Config ( const std::string & filename_in )

Main constructor. The file is parsed and a key/value map object is internally created.

Parameters

[in] filename_in string representing the absolute filename of the key/value file

Member Function Documentation

◆ addFile()

void mio::Config::addFile ( const std::string & filename_in )

Add the content of a file to the internal key/value map object.

Parameters

[in] filename_in string representing the absolute filename of the key/value file

◆ addKey()

void mio::Config::addKey	(	std::string	key,
		std::string	section,
		const std::string &	value
	)

Add a specific key/value pair to the internal key/value map object. key and section are case insensitive.

Parameters

[in]	key	string representing the key to be added
[in]	section	std::string representing a section name; the key has to be part of this section
[in]	value	string representing the matching value to be added

◆ deleteKey()

void mio::Config::deleteKey	(	std::string	key,
		std::string	section
	)

Delete a specific key/value pair from the internal map object, key/section are case insensitive.

Parameters

[in]	key	string representing the key to be added
[in]	section	std::string representing a section name; the key has to be part of this section

◆ deleteKeys()

void mio::Config::deleteKeys	(	std::string	keymatch,
		std::string	section,
		const bool &	anywhere = `false`
	)

Delete keys matching a specific pattern from the internal map object, key/section are case insensitive.

Parameters

[in]	keymatch	A string representing the beginning of a key to search for
[in]	section	A string defining which section to search through (default: GENERAL)
[in]	anywhere	Match substring anywhere in the key string (default=false, ie at the beginning only) Config cfg("io.ini"); cfg.deleteKeys("STATION", "Input"); mio::Config A class that reads a key/value file. These files (typically named .ini) follow the INI file format s... Definition:* Config.h:79

◆ get() [1/6]

const ConfigProxy mio::Config::get	(	const std::string &	key,
		const std::string &	section
	)		const

A function that allows to retrieve a value for a key as return parameter (vectors of values too).

If the key is not found, an exception is thrown.

Parameters

[in]	key	std::string representing a KEY in the key/value file
[in]	section	std::string representing a section name; the key has to be part of this section

Returns: A value of type T

Example Usage:

Config cfg("io.ini");
vector<int> = cfg.get("DEPTHS", "INPUT");
string mystr = cfg.get("PATH", "OUTPUT");

◆ get() [2/6]

bool mio::Config::get	(	const std::string &	key,
		const std::string &	section,
		const bool &	dflt
	)		const

◆ get() [3/6]

std::string mio::Config::get	(	const std::string &	key,
		const std::string &	section,
		const char	dflt[]
	)		const

◆ get() [4/6]

double mio::Config::get	(	const std::string &	key,
		const std::string &	section,
		const double &	dflt
	)		const

◆ get() [5/6]

std::string mio::Config::get	(	const std::string &	key,
		const std::string &	section,
		const std::string &	dflt
	)		const

A function that allows to retrieve a value for a key as return parameter (vectors of values too).

If the key is not found, the provided default value is returned.

Parameters

[in]	key	std::string representing a KEY in the key/value file
[in]	section	std::string representing a section name; the key has to be part of this section
[in]	dflt	default value, if the key is not found

Returns: A value of type T

Example Usage:

Config cfg("io.ini");

const std::string factor = cfg.get("model", "Input", "default");

Note: this is a specialized version of the template method, since strings are tricky: they can be initialized with "" but this needs casting (since this is either a char or a char[]), therefore template argument deduction would fail.

◆ get() [6/6]

template<typename T >

T mio::Config::get	(	const std::string &	key,
		const std::string &	section,
		const T &	dflt
	)		const

A function that allows to retrieve a value for a key as return parameter (vectors of values too).

If the key is not found, the provided default value is returned.

Parameters

[in]	key	std::string representing a KEY in the key/value file
[in]	section	std::string representing a section name; the key has to be part of this section
[in]	dflt	default value, if the key is not found

Returns: A value of type T

Example Usage:

Config cfg("io.ini");

const double factor = cfg.get("factor", "Input", 1.);

◆ getArgumentsForAlgorithm()

std::vector< std::pair< std::string, std::string > > mio::Config::getArgumentsForAlgorithm	(	const std::string &	parname,
		const std::string &	algorithm,
		const std::string &	section = `"Interpolations1d"`
	)		const

retrieve the resampling algorithm to be used for the 1D interpolation of meteo parameters. The potential arguments are also extracted.

Parameters

parname	meteo parameter to deal with
algorithm	algorithm name
section	INI section to look into

Returns: vector of named arguments

◆ getCommandNr()

unsigned int mio::Config::getCommandNr	(	const std::string &	section,
		const std::string &	cmd_pattern,
		const std::string &	cmd_key
	)

static

Extract the command number from a given command string, given the command pattern.

Each new command is defined as {cmd_id}::{cmd_pattern}# = {value} and this call extracts the command number out of a given "{cmd_id}::{cmd_pattern}#" string.

For example, a filter command will have as command pattern "TA::FILTER", as command key "TA::FILTER3" and this call will return 3.

Parameters

[in]	section	The section this command belongs to (for error messages)
[in]	cmd_pattern	Pattern used to build the stack of commands, such as "TA::FILTER" or even just "::FILTER"
[in]	cmd_key	the base command key, such as "TA::FILTER3" that will be parsed as {cmd_id}::{cmd_pattern}# to extract the command number

Returns: the key index contained in the cmd_key or IOUtils::unodata if a number could not be extracted

◆ getConfigRootDir()

std::string mio::Config::getConfigRootDir ( ) const

inline

Returns the directory where the root configuration file is (needed to resolv relative paths).

Returns: The absolute path to the root config file (resolved for symlinks, relative paths, etc).

◆ getKeys()

std::vector< std::string > mio::Config::getKeys	(	std::string	keymatch,
		std::string	section,
		const bool &	anywhere = `false`
	)		const

Function that searches for a given string within the keys of a given section (default: GENERAL) it returns all the keys that match (partial matches are considered) into a vector<string>.

Parameters

[in]	keymatch	A string representing the beginning of a key to search for
[in]	section	A string defining which section to search through (default: GENERAL)
[in]	anywhere	Match substring anywhere in the key string (default=false, ie at the beginning only)

Returns: a vector that holds all keys that partially match keymatch
const std::vector<std::string> myVec( cfg.getKeys("TA::", "Filters") );

◆ getKeysRegex()

std::vector< std::string > mio::Config::getKeysRegex	(	const std::string &	regex_str,
		std::string	section
	)		const

◆ getSections()

std::set< std::string > mio::Config::getSections ( ) const

inline

Returns all the sections that are present in the config object.

Returns: a set that holds all the sections names

◆ getSourceName()

std::string mio::Config::getSourceName ( ) const

inline

Returns the filename that the Config object was constructed with.

Returns: The absolute filename of the key/value file.

◆ getValue() [1/6]

template<typename T >

std::vector< T > mio::Config::getValue	(	const std::string &	key,
		std::string &	section,
		const IOUtils::ThrowOptions &	opt = `IOUtils::dothrow`
	)		const

inline

◆ getValue() [2/6]

template<typename T >

void mio::Config::getValue	(	const std::string &	key,
		std::vector< T > &	vecT,
		const IOUtils::ThrowOptions &	opt = `IOUtils::dothrow`
	)		const

inline

Template function to retrieve a vector of values of class T for a certain key.

algorithms = lsm linregres idw_kriging\n

MYNUMBERS = 17.87 19.89 -19.89 +7777.007

Parameters

[in]	key	std::string representing a KEY in the key/value file (default section "GENERAL" is assumed)
[out]	vecT	a variable of class vector<T> into which the values for the corresponding key are saved
[in]	opt	indicating whether an exception should be raised, when key is not present

◆ getValue() [3/6]

template<typename T >

void mio::Config::getValue	(	const std::string &	key,
		T &	t,
		const IOUtils::ThrowOptions &	opt = `IOUtils::dothrow`
	)		const

inline

Template function to retrieve a value of class T for a certain key.

Parameters

[in]	key	std::string representing a KEY in the key/value file (default section "GENERAL" is assumed)
[out]	t	a variable of class T into which the value for the corresponding key is saved (e.g. double, int, std::string)
[in]	opt	indicating whether an exception should be raised, when key is not present

◆ getValue() [4/6]

void mio::Config::getValue	(	std::string	key,
		std::string	section,
		Date &	t,
		const double &	time_zone,
		const IOUtils::ThrowOptions &	opt = `IOUtils::dothrow`
	)		const

inline

Function to retrieve a Date value for a certain key.

Parameters

[in]	key	std::string representing a KEY in the key/value file
[in]	section	std::string representing a section name; the key has to be part of this section
[out]	t	a variable of class Date into which the value for the corresponding key is saved
[out]	time_zone	timezone for the date (if the date provides its own timezone, it will be ignored)
[in]	opt	indicating whether an exception should be raised, when key is not present

◆ getValue() [5/6]

template<typename T >

void mio::Config::getValue	(	std::string	key,
		std::string	section,
		std::vector< T > &	vecT,
		const IOUtils::ThrowOptions &	opt = `IOUtils::dothrow`
	)		const

inline

Template function to retrieve a vector of values of class T for a certain key.

algorithms = lsm linregres idw_kriging\n

MYNUMBERS = 17.87 19.89 -19.89 +7777.007

Parameters

[in]	key	std::string representing a KEY in the key/value file
[in]	section	std::string representing a section name; the key has to be part of this section
[out]	vecT	a variable of class vector<T> into which the values for the corresponding key are saved
[in]	opt	indicating whether an exception should be raised, when key is not present

◆ getValue() [6/6]

template<typename T >

void mio::Config::getValue	(	std::string	key,
		std::string	section,
		T &	t,
		const IOUtils::ThrowOptions &	opt = `IOUtils::dothrow`
	)		const

inline

Template function to retrieve a value of class T for a certain key.

Parameters

[in]	key	std::string representing a KEY in the key/value file
[in]	section	std::string representing a section name; the key has to be part of this section
[out]	t	a variable of class T into which the value for the corresponding key is saved (e.g. double, int, std::string)
[in]	opt	indicating whether an exception should be raised, when key is not present

◆ getValues() [1/3]

std::vector< std::pair< std::string, std::string > > mio::Config::getValues	(	std::string	keymatch,
		std::string	section,
		const bool &	anywhere = `false`
	)		const

Function that searches for a given string within the keys of a given section (default: GENERAL) it returns all the <keys,value> pairs that match (partial matches are considered) into a vector.

Parameters

[in]	keymatch	A string representing the beginning of a key to search for
[in]	section	A string defining which section to search through (default: GENERAL)
[in]	anywhere	Match substring anywhere in the key string (default=false, ie at the beginning only)

Returns: a vector of all <keys,value> pairs that partially match keymatch
const std::vector< std::pair<std::string, std::string> > myVec( cfg.getValues("TA::", "Filters") );

◆ getValues() [2/3]

template<typename T >

void mio::Config::getValues	(	std::string	keymatch,
		std::string	section,
		std::vector< T > &	vecT
	)		const

inline

Template function to retrieve a vector of values of class T for a certain key pattern.

Please not that if the keys are postfixed by integral numbers (ie build as {common string}{integral number}, such as STATION12) then the keys will be sorted in ascending order based on this integral number. As soon as a key does not fit this pattern, the sort will be purely alphabetical (therefore STATION11_a would appear before STATION2_a).

Parameters

[in]	keymatch	std::string representing a pattern for the key in the key/value file
[in]	section	std::string representing a section name; the key has to be part of this section
[out]	vecT	a vector of class T into which the values for the corresponding keys are saved

◆ getValues() [3/3]

template<typename T >

void mio::Config::getValues	(	std::string	keymatch,
		std::string	section,
		std::vector< T > &	vecT,
		std::vector< std::string > &	vecKeys
	)		const

inline

◆ getValuesRegex()

std::vector< std::pair< std::string, std::string > > mio::Config::getValuesRegex	(	const std::string &	regex_str,
		std::string	section
	)		const

◆ keyExists()

bool mio::Config::keyExists	(	std::string	key,
		std::string	section
	)		const

Return if a given key exists in a given section.

Parameters

[in]	key	string representing the key to be searched
[in]	section	std::string representing a section name; the key has to be part of this section

Returns: true if the key exists

◆ moveSection()

void mio::Config::moveSection	(	std::string	org,
		std::string	dest,
		const bool &	overwrite
	)

Move all keys of the org section to the dest section.

Parameters

[in]	org	Section of origin
[in]	dest	Section of destination
[in]	overwrite	if true, all keys in the destination section are erased before creating the new keys

◆ parseArgs()

std::vector< std::pair< std::string, std::string > > mio::Config::parseArgs	(	const std::string &	section,
		const std::string &	cmd_id,
		const unsigned int &	cmd_nr,
		const std::string &	arg_pattern
	)		const

Extract the arguments for a given command and store them into a vector of key / value pairs.

The goal of this call is to provide an algorithm with easy to parse arguments, independent of the entry syntax. The syntax that is supported here is the following:

each new command is defined as {cmd_id}::{cmd_pattern}# = {value}
each argument for this command is defined as {cmd_id}::{arg_pattern}#::{argument_name} = {value} From the command definition, the command number will be retrieved by a call to getCommandNr(). Then all its arguments will be extracted by the current call and saved into a vector of pairs {argument_name} / {value}.

Parameters

[in]	section	The section where to look for this command
[in]	cmd_id	the command ID to process
[in]	cmd_nr	the command number to process (most probably provided by a call to getCommandNr())
[in]	arg_pattern	as part of the argument definition

Returns: All arguments for this command, as vector of key / value pairs, {argument_name} / {value}

◆ sectionExists()

bool mio::Config::sectionExists ( std::string section ) const

Return if a given section exists in the Config object.

Parameters

[in] section std::string representing a section name

Returns: true if the section exists

◆ toString()

const std::string mio::Config::toString ( ) const

Print the content of the Config object (useful for debugging) The Config is bound by "<Config>" and "</Config>" on separate lines.

◆ write()

void mio::Config::write ( const std::string & filename ) const

Write the Config object to a file.

Parameters

filename The filename including the path, e.g. "/tmp/test.ini"

Friends And Related Function Documentation

◆ operator<<

std::ostream & operator<<	(	std::ostream &	os,
		const Config &	cfg
	)

friend

◆ operator>>

std::istream & operator>>	(	std::istream &	is,
		Config &	cfg
	)

friend

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

Detailed Description

Imports

Exemples

Public Member Functions

Static Public Member Functions

Friends

Constructor & Destructor Documentation

◆ Config() [1/2]

◆ Config() [2/2]

Member Function Documentation

◆ addFile()

◆ addKey()

◆ deleteKey()

◆ deleteKeys()

◆ get() [1/6]

◆ get() [2/6]

◆ get() [3/6]

◆ get() [4/6]

◆ get() [5/6]

◆ get() [6/6]

◆ getArgumentsForAlgorithm()

◆ getCommandNr()

◆ getConfigRootDir()

◆ getKeys()

◆ getKeysRegex()

◆ getSections()

◆ getSourceName()

◆ getValue() [1/6]

◆ getValue() [2/6]

◆ getValue() [3/6]

◆ getValue() [4/6]

◆ getValue() [5/6]

◆ getValue() [6/6]

◆ getValues() [1/3]

◆ getValues() [2/3]

◆ getValues() [3/3]

◆ getValuesRegex()

◆ keyExists()

◆ moveSection()

◆ parseArgs()

◆ sectionExists()

◆ toString()

◆ write()

Friends And Related Function Documentation

◆ operator<<

◆ operator>>