MeteoIODoc  MeteoIODoc-2.9.0
mio::Config Class Reference

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

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_instring 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_instring 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]keystring representing the key to be added
[in]sectionstd::string representing a section name; the key has to be part of this section
[in]valuestring 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]keystring representing the key to be added
[in]sectionstd::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]keymatchA string representing the beginning of a key to search for
[in]sectionA string defining which section to search through (default: GENERAL)
[in]anywhereMatch substring anywhere in the key string (default=false, ie at the beginning only)
Config cfg("io.ini");
cfg.deleteKeys("STATION", "Input");

◆ get() [1/5]

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]keystd::string representing a KEY in the key/value file
[in]sectionstd::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/5]

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]keystd::string representing a KEY in the key/value file
[in]sectionstd::string representing a section name; the key has to be part of this section
[in]dfltdefault 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.);

◆ get() [3/5]

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]keystd::string representing a KEY in the key/value file
[in]sectionstd::string representing a section name; the key has to be part of this section
[in]dfltdefault 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() [4/5]

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

◆ get() [5/5]

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

◆ 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]keymatchA string representing the beginning of a key to search for
[in]sectionA string defining which section to search through (default: GENERAL)
[in]anywhereMatch 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.findKeys("TA::", "Filters") );

◆ 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]keystd::string representing a KEY in the key/value file (default section "GENERAL" is assumed)
[out]vecTa variable of class vector<T> into which the values for the corresponding key are saved
[in]optindicating whether an exception should be raised, when key is not present

◆ getValue() [3/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]keystd::string representing a KEY in the key/value file
[in]sectionstd::string representing a section name; the key has to be part of this section
[out]vecTa variable of class vector<T> into which the values for the corresponding key are saved
[in]optindicating whether an exception should be raised, when key is not present

◆ getValue() [4/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]keystd::string representing a KEY in the key/value file (default section "GENERAL" is assumed)
[out]ta variable of class T into which the value for the corresponding key is saved (e.g. double, int, std::string)
[in]optindicating 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,
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]keystd::string representing a KEY in the key/value file
[in]sectionstd::string representing a section name; the key has to be part of this section
[out]ta variable of class T into which the value for the corresponding key is saved (e.g. double, int, std::string)
[in]optindicating whether an exception should be raised, when key is not present

◆ getValue() [6/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]keystd::string representing a KEY in the key/value file
[in]sectionstd::string representing a section name; the key has to be part of this section
[out]ta variable of class Date into which the value for the corresponding key is saved
[out]time_zonetimezone for the date (if the date provides its own timezone, it will be ignored)
[in]optindicating whether an exception should be raised, when key is not present

◆ getValues() [1/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.

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

◆ getValues() [2/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

◆ getValues() [3/3]

std::vector< std::pair< std::string, std::string > > mio::Config::getValues ( std::string  keymatch,
std::string  section,
const bool &  anywhere = false 
) 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]keystring representing the key to be searched
[in]sectionstd::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]orgSection of origin
[in]destSection of destination
[in]overwriteif true, all keys in the destination section are erased before creating the new keys

◆ sectionExists()

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

Return if a given section exists in the Config object.

Parameters
[in]sectionstd::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
filenameThe 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: