Async::Config Class Reference

A class for reading INI-formatted configuration files. More...

#include <AsyncConfig.h>

Public Member Functions
	Config (void)
	Default constuctor.
	~Config (void)
	Destructor.
bool	open (const std::string &name)
	Open the given config file.
const std::string &	getValue (const std::string &section, const std::string &tag) const
	Return the string value of the given configuration variable.
bool	getValue (const std::string &section, const std::string &tag, std::string &value, bool missing_ok=false) const
	Get the string value of the given configuration variable.
template<typename Rsp >
bool	getValue (const std::string &section, const std::string &tag, Rsp &rsp, bool missing_ok=false) const
	Get the value of the given configuration variable.
template<template< typename, typename > class Container, typename Value >
bool	getValue (const std::string &section, const std::string &tag, Container< Value, std::allocator< Value > > &c, bool missing_ok=false) const
	Get the value of the given config variable into container.
template<template< typename, typename, typename > class Container, typename Key >
bool	getValue (const std::string &section, const std::string &tag, Container< Key, std::less< Key >, std::allocator< Key > > &c, bool missing_ok=false) const
	Get the value of the given config variable into keyed container.
template<template< typename, typename, typename, typename > class Container, class Key , class T , class Compare = std::less<Key>, class Allocator = std::allocator<std::pair<const Key, T>>>
bool	getValue (const std::string &section, const std::string &tag, Container< Key, T, Compare, Allocator > &c, char sep=':', bool missing_ok=false) const
	Get value of given config variable into associative container.
template<typename Rsp >
bool	getValue (const std::string &section, const std::string &tag, const Rsp &min, const Rsp &max, Rsp &rsp, bool missing_ok=false) const
	Get a range checked variable value.
template<typename F = std::function<void(const char*)>>
void	subscribeValue (const std::string &section, const std::string &tag, const char *def, F func)
	Subscribe to the given configuration variable (char*)
template<typename Rsp , typename F = std::function<void(const Rsp&)>>
void	subscribeValue (const std::string &section, const std::string &tag, const Rsp &def, F func)
	Subscribe to the given configuration variable.
template<template< typename, typename > class Container, typename Rsp , typename F = std::function<void(const Rsp&)>>
void	subscribeValue (const std::string &section, const std::string &tag, const Container< Rsp, std::allocator< Rsp > > &def, F func)
	Subscribe to the given configuration variable (sequence)
std::list< std::string >	listSections (void)
	Return the name of all configuration sections.
std::list< std::string >	listSection (const std::string &section)
	Return the name of all the tags in the given section.
void	setValue (const std::string &section, const std::string &tag, const std::string &value)
	Set the value of a configuration variable.
template<typename Rsp >
void	setValue (const std::string &section, const std::string &tag, const Rsp &value)
	Set the value of a configuration variable (generic type)
template<template< typename, typename > class Container, typename Rsp >
void	setValue (const std::string &section, const std::string &tag, const Container< Rsp, std::allocator< Rsp > > &c)
	Set the value of a configuration variable (sequence container)

Public Attributes
sigc::signal< void, const std::string &, const std::string & >	valueUpdated
	A signal that is emitted when a config value is updated.

Detailed Description

A class for reading INI-formatted configuration files.

Author

Tobias Blomberg

Date

2004-03-17

This class is used to read configuration files that is in the famous MS Windows INI file format. An example of a configuration file and how to use the class is shown below.

[SECTION1]
VALUE1=The value
VALUE2="Hello, "
       "multi line "
       "value!"
 
[SECTION2]
VALUE1="Whatever you want"
MY_INT=42
MY_FLOAT=3.14159

#include <iostream>
#include <string>
#include <vector>
#include <cstdlib>
#include <iterator>
 
#include <AsyncConfig.h>
 
using namespace std;
using namespace Async;
 
int main(int argc, char **argv)
{
  Config cfg;
  if (!cfg.open("test.cfg"))
  {
    cerr << "*** Error: Could not open config file test.cfg\n";
    exit(1);
  }
 
    // Read the string value without checking if it exists or not.
  cout << "value=" << cfg.getValue("SECTION1", "VALUE1") << endl;
  
    // Read the string value, returning it in a variable.
    // The return value will indicate if the variable was found or not.
  string str_val;
  if (cfg.getValue("SECTION1", "VALUE2", str_val))
  {
    cout << "str_val=" << str_val << endl;
  }
  else
  {
    cerr << "*** ERROR: Config variable SECTION1/VALUE2 not found.\n";
  }
  
    // Read an integer value.
  int int_val = 0;
  if (cfg.getValue("SECTION2", "MY_INT", int_val))
  {
    cout << "int_val=" << int_val << endl;
  }
  else
  {
    cerr << "*** ERROR: Config variable SECTION2/MY_INT malformed or "
            "not found.\n";
  }
  
    // Read a char value. Missing value is OK.
  char char_val = 'Q';
  if (cfg.getValue("SECTION1", "NO_VALUE", char_val, true))
  {
    cout << "char_val=" << char_val << endl;
  }
  else
  {
    cerr << "*** ERROR: Config variable SECTION1/NO_VALUE malformed.\n";
  }
  
    // Read a float with min and max limits.
  float float_val = 0.0;
  if (cfg.getValue("SECTION2", "MY_FLOAT", 3.0f, 4.0f, float_val))
  {
    cout << "float_val=" << float_val << endl;
  }
  else
  {
    cerr << "*** ERROR: Config variable SECTION2/MY_FLOAT malformed, "
            "not found or out of range.\n";
  }
 
  cfg.subscribeValue("SECTION1", "VALUE1", "",
      [](const std::string& val)
      {
        cout << "SECTION1/VALUE1=" << val << endl;
      });
  cfg.setValue("SECTION1", "VALUE1", "A subscribed string value");
 
  cfg.subscribeValue("SECTION2", "MY_INT", -1,
      [](int val)
      {
        cout << "SECTION2/MY_INT=" << val << endl;
      });
  cfg.setValue("SECTION2", "MY_INT", 4711);
 
  cfg.subscribeValue("SECTION1", "VEC", std::vector<int>{1,2,3},
      [=](const std::vector<int>& vec)
      {
        std::copy(vec.begin(), vec.end(),
          std::ostream_iterator<int>(std::cout, " "));
        std::cout << std::endl;
      });
  cfg.setValue("SECTION1", "VEC", std::vector<int>{42,43,44});
 
  return 0;
}

Examples

AsyncConfig_demo.cpp.

Definition at line 138 of file AsyncConfig.h.

Constructor & Destructor Documentation

Config()

Async::Config::Config ( void )

inline

Default constuctor.

Definition at line 144 of file AsyncConfig.h.

~Config()

Async::Config::~Config

(

void

)

Destructor.

Member Function Documentation

getValue() [1/7]

const std::string & Async::Config::getValue	(	const std::string &	section,
		const std::string &	tag ) const

Return the string value of the given configuration variable.

Parameters

section	The name of the section where the configuration variable is located
tag	The name of the configuration variable to get

Returns

Returns String with content of the configuration variable. If no variable is found an empty string is returned

This function will return the string value corresponding to the given configuration variable. If the configuration variable is unset, an empty sting is returned.

Examples

AsyncConfig_demo.cpp.

Referenced by getValue(), getValue(), getValue(), getValue(), and getValue().

getValue() [2/7]

template<typename Rsp >

bool Async::Config::getValue ( const std::string & section, const std::string & tag, const Rsp & min, const Rsp & max, Rsp & rsp, bool missing_ok = false ) const

inline

Get a range checked variable value.

Parameters

section	The name of the section where the configuration variable is located
tag	The name of the configuration variable to get.
min	Smallest valid value.
max	Largest valid value.
rsp	The value is returned in this argument. Successful completion overwites prevoius contents.
missing_ok	If set to true, return true if the configuration variable is missing

Returns

Returns true if value is within range otherwise false.

This function is used to get the value of the given configuration variable, checking if it is within the given range (min <= value <= max). Requires operators >>, < and > to be defined in the value object. Normally a missing configuration variable is seen as an error and the function returns false. If the missing_ok parameter is set to true, this function returns true for a missing variable but till returns false if an illegal value is specified.

Definition at line 440 of file AsyncConfig.h.

References getValue().

getValue() [3/7]

template<template< typename, typename, typename > class Container, typename Key >

bool Async::Config::getValue ( const std::string & section, const std::string & tag, Container< Key, std::less< Key >, std::allocator< Key > > & c, bool missing_ok = false ) const

inline

Get the value of the given config variable into keyed container.

Parameters

section	The name of the section where the configuration variable is located
tag	The name of the configuration variable to get
c	The value is returned in this argument. Successful completion overwrites previous contents
missing_ok	If set to true, return true if the configuration variable is missing

Returns

Returns true on success or else false on failure.

This function is used to get the value of a configuraiton variable. The config variable is read into a keyed container (e.g. set, multiset etc). It's a template function meaning that it can take any key type that supports the operator>> function. Normally a missing configuration variable is seen as an error and the function returns false. If the missing_ok parameter is set to true, this function returns true for a missing variable but still returns false if an illegal value is specified.

Definition at line 314 of file AsyncConfig.h.

References getValue().

getValue() [4/7]

template<template< typename, typename, typename, typename > class Container, class Key , class T , class Compare = std::less<Key>, class Allocator = std::allocator<std::pair<const Key, T>>>

bool Async::Config::getValue ( const std::string & section, const std::string & tag, Container< Key, T, Compare, Allocator > & c, char sep = ':', bool missing_ok = false ) const

inline

Get value of given config variable into associative container.

Parameters

section	The name of the section where the configuration variable is located
tag	The name of the configuration variable to get
c	The value is returned in this argument. Successful completion overwrites previous contents
sep	The character used to separate key and value
missing_ok	If set to true, return true if the configuration variable is missing

Returns

Returns true on success or else false on failure.

This function is used to get the value of a configuraiton variable. The config variable is read into an associative container (e.g. std::map or std::multimap). It's a template function meaning that it can take any key and value type that supports the operator>> function. Normally a missing configuration variable is seen as an error and the function returns false. If the missing_ok parameter is set to true, this function returns true for a missing variable but still returns false if an illegal value is specified.

Definition at line 371 of file AsyncConfig.h.

References getValue().

getValue() [5/7]

template<template< typename, typename > class Container, typename Value >

bool Async::Config::getValue ( const std::string & section, const std::string & tag, Container< Value, std::allocator< Value > > & c, bool missing_ok = false ) const

inline

Get the value of the given config variable into container.

Parameters

section	The name of the section where the configuration variable is located
tag	The name of the configuration variable to get
c	The value is returned in this argument. Successful completion overwrites previous contents
missing_ok	If set to true, return true if the configuration variable is missing

Returns

Returns true on success or else false on failure.

This function is used to get the value of a configuraiton variable. The config variable is read into a container (e.g. vector, list etc). It's a template function meaning that it can take any value type that supports the operator>> function. Normally a missing configuration variable is seen as an error and the function returns false. If the missing_ok parameter is set to true, this function returns true for a missing variable but still returns false if an illegal value is specified.

Definition at line 258 of file AsyncConfig.h.

References getValue().

getValue() [6/7]

template<typename Rsp >

bool Async::Config::getValue ( const std::string & section, const std::string & tag, Rsp & rsp, bool missing_ok = false ) const

inline

Get the value of the given configuration variable.

Parameters

section	The name of the section where the configuration variable is located
tag	The name of the configuration variable to get
rsp	The value is returned in this argument. Successful completion overwrites previous contents
missing_ok	If set to true, return true if the configuration variable is missing

Returns

Returns true on success or else false on failure.

This function is used to get the value of a configuraiton variable. It's a template function meaning that it can take any value type that supports the operator>> function. Note that when the value is of type string, the overloaded getValue is used rather than this function. Normally a missing configuration variable is seen as an error and the function returns false. If the missing_ok parameter is set to true, this function returns true for a missing variable but still returns false if an illegal value is specified.

Definition at line 213 of file AsyncConfig.h.

References getValue().

getValue() [7/7]

bool Async::Config::getValue	(	const std::string &	section,
		const std::string &	tag,
		std::string &	value,
		bool	missing_ok = false ) const

Get the string value of the given configuration variable.

Parameters

section	The name of the section where the configuration variable is located
tag	The name of the configuration variable to get
value	The value is returned in this argument. Any previous contents is wiped

Returns

Returns true on success or else false on failure

This function is used to get the value for a configuration variable of type "string".

listSection()

std::list< std::string > Async::Config::listSection

(

const std::string &

section

)

Return the name of all the tags in the given section.

Parameters

section

The name of the section where the configuration variables are located

Returns

Returns the list of tags in the given section

listSections()

std::list< std::string > Async::Config::listSections

(

void

)

Return the name of all configuration sections.

Returns

Returns a list of all existing section names

open()

bool Async::Config::open

(

const std::string &

name

)

Open the given config file.

Parameters

name	The name of the configuration file to open

Returns

Returns true on success or else false.

This function will read the given configuration file into memory. If this function return false and errno != 0, the errno variable may give a hint what the problem was.

Examples

AsyncConfig_demo.cpp.

setValue() [1/3]

template<template< typename, typename > class Container, typename Rsp >

void Async::Config::setValue ( const std::string & section, const std::string & tag, const Container< Rsp, std::allocator< Rsp > > & c )

inline

Set the value of a configuration variable (sequence container)

Parameters

section	The name of the section where the configuration variable is located
tag	The name of the configuration variable to set.
c	The sequence to set

This function is used to set the value of a configuration variable that holds a sequence container (e.g. std::vector, std::list etc). The type of the elements of the container may be any type that support streaming to string. If the given configuration section or variable does not exist, it is created. Note that this function will not write anything back to the associated configuration file. It will only set the value in memory.

The valueUpdated signal will be emitted so that subscribers can get notified when the value of a configuration variable is changed.

Definition at line 651 of file AsyncConfig.h.

References setValue().

setValue() [2/3]

template<typename Rsp >

void Async::Config::setValue ( const std::string & section, const std::string & tag, const Rsp & value )

inline

Set the value of a configuration variable (generic type)

Parameters

section	The name of the section where the configuration variable is located
tag	The name of the configuration variable to set.
value	The value to set

This function is used to set the value of a configuration variable. The type of the value may be any type that support streaming to string. If the given configuration section or variable does not exist, it is created. Note that this function will not write anything back to the associated configuration file. It will only set the value in memory.

The valueUpdated signal will be emitted so that subscribers can get notified when the value of a configuration variable is changed.

Definition at line 622 of file AsyncConfig.h.

References setValue().

setValue() [3/3]

void Async::Config::setValue	(	const std::string &	section,
		const std::string &	tag,
		const std::string &	value )

Set the value of a configuration variable.

Parameters

section	The name of the section where the configuration variable is located
tag	The name of the configuration variable to set.
value	The value to set

This function is used to set the value of a configuration variable. If the given configuration section or variable does not exist, it is created. Note that this function will not write anything back to the associated configuration file. It will only set the value in memory.

The valueUpdated signal will be emitted so that subscribers can get notified when the value of a configuration variable is changed.

Examples

AsyncConfig_demo.cpp.

Referenced by setValue(), and setValue().

subscribeValue() [1/3]

template<typename F = std::function<void(const char*)>>

void Async::Config::subscribeValue ( const std::string & section, const std::string & tag, const char * def, F func )

inline

Subscribe to the given configuration variable (char*)

Parameters

section	The name of the section where the configuration variable is located
tag	The name of the configuration variable to get
def	Default value if the config var does not exist
func	The function to call when the config var changes

This function is used to subscribe to the changes of the specified configuration variable. The given function will be called when the value changes. If the configuration variable is not set, it will be set to the given default value.

This version of the function is called when the default value is a C string (char*).

Examples

AsyncConfig_demo.cpp.

Definition at line 481 of file AsyncConfig.h.

References subscribeValue().

Referenced by subscribeValue().

subscribeValue() [2/3]

template<template< typename, typename > class Container, typename Rsp , typename F = std::function<void(const Rsp&)>>

void Async::Config::subscribeValue ( const std::string & section, const std::string & tag, const Container< Rsp, std::allocator< Rsp > > & def, F func )

inline

Subscribe to the given configuration variable (sequence)

Parameters

section	The name of the section where the configuration variable is located
tag	The name of the configuration variable to get
def	Default value if the config var does not exist
func	The function to call when the config var changes

This function is used to subscribe to the changes of the specified configuration variable. The given function will be called when the value changes. If the configuration variable is not set, it will be set to the given default value.

This version of the function is called when the default value is a sequence container (e.g. std::vector, std::list etc).

Definition at line 542 of file AsyncConfig.h.

subscribeValue() [3/3]

template<typename Rsp , typename F = std::function<void(const Rsp&)>>

void Async::Config::subscribeValue ( const std::string & section, const std::string & tag, const Rsp & def, F func )

inline

Subscribe to the given configuration variable.

Parameters

section	The name of the section where the configuration variable is located
tag	The name of the configuration variable to get
def	Default value if the config var does not exist
func	The function to call when the config var changes

This function is used to subscribe to the changes of the specified configuration variable. The given function will be called when the value changes. If the configuration variable is not set, it will be set to the given default value.

This version of the function is called when the default value is of a non-container type (e.g. std::string, int, bool etc).

Definition at line 508 of file AsyncConfig.h.

Member Data Documentation

valueUpdated

sigc::signal<void, const std::string&, const std::string&> Async::Config::valueUpdated

A signal that is emitted when a config value is updated.

Parameters

section	The config section of the update
tag	The tag (variable name) of the update

This signal is emitted whenever a configuration variable is changed by calling the setValue function. It will only be emitted if the value actually changes.

Definition at line 677 of file AsyncConfig.h.

---

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

• AsyncConfig.h