Utility class for creating and reading XML-based hierarchical configuration files. More...

#include <ConfigFile.h>

Inheritance diagram for icl::utils::ConfigFile:

Classes
class	Data
	Data- type used for the []-operator of ConfigFile instances. More...

struct	Entry
	internal utility structure for contained data More...

struct	EntryNotFoundException
	Internal exception type, thrown if an entry was not found. More...

struct	InvalidTypeException
	Internal exception type, thrown if an entry type missmatch occurs. More...

struct	KeyRestriction
	Utility Type for restriction of type values. More...

struct	Maps
	internally used type map class More...

struct	UnregisteredTypeException
	thrown if unregistered types are used More...

Public Types
typedef std::map< std::string, Entry >::const_iterator	const_iterator
	iterator type to run through all entries (const only) More...

Public Member Functions
	ConfigFile ()
	Default constructor creating an empty ConfigFile instance. More...

	ConfigFile (const std::string &filename)
	Creates a ConfigFile instance with given filename. More...

	ConfigFile (pugi::xml_document *handle)
	Creates a ConfigFile from given handle instance. More...

	ConfigFile (std::istream &stream)
	creates a ConfigFile instance from given istream. More...

void	load (const std::string &filename)
	loads the ConfigFile from given filename and updates internal filename variable More...

void	save (const std::string &filename) const
	Writes data to disk using given filename. More...

void	setPrefix (const std::string &defaultPrefix) const
	Sets up a default prefix automatically put before each given key. More...

const std::string &	getPrefix () const
	Returns given default prefix. More...

Data	operator [] (const std::string &id)
	main access function to datastore entries (unconst) More...

const Data	operator[] (const std::string &id) const
	main access function to datastore entries (const) More...

std::vector< Data >	find (const std::string &regex)
	returns all data entries, that match the given regex More...

const std::vector< Data >	find (const std::string &regex) const
	returns all data entries, that match the given regex (const); More...

template<class T >
void	set (const std::string &id, const T &val)
	sets or updates a new data element to the ConfigFile More...

template<class T >
T	get (const std::string &idIn) const
	returns a given value from the internal string based representation (un const) More...

template<class T >
T	get (const std::string &idIn, const T &def) const
	returns a given value from the internal string based representation More...

void	listContents () const
	lists whole datastore contents More...

bool	contains (const std::string &id) const
	returns whether an entry with given ID is contained More...

void	setRestriction (const std::string &id, const KeyRestriction &r)
	defined the range for given number-type-valued key More...

const KeyRestriction *	getRestriction (const std::string &id) const
	returns predefined range for given id (or 0 if no range was defined for this key) More...

const_iterator	begin () const
	all-entry iterator begin More...

const_iterator	end () const
	all-entry iterator end More...

const std::vector< const Entry * >	getEntryList (bool relToPrefix=false) const
	returns all entries as vector<const Entry*> More...

void	clear ()
	removes all contents (except config and title node) More...

const pugi::xml_document *	getHandle () const
	returns internal document handle (forward declared here) (const only) More...

Public Member Functions inherited from icl::utils::Lockable
	Lockable (bool recursive=false)
	Default constructor. More...

	Lockable (const Lockable &l)
	copy constructor (does not copy the source mutex) More...

Lockable &	operator= (const Lockable &l)
	assignment operator (does not copy the source mutex) More...

	~Lockable ()
	Destructor. More...

void	lock () const
	lock object More...

void	unlock () const
	unlock object More...

Mutex &	getMutex () const
	returns mutex of this object More...

Static Public Member Functions
template<class T >
static void	register_type (const std::string &id)
	registers a new type in the data store parsing engine More...

static void	loadConfig (const std::string &filename)
	loads the global ConfigFile from given filename More...

static void	loadConfig (const ConfigFile &configFile)
	loads a ConfigFile object into the global config file (shallowly copied!) More...

static const ConfigFile &	getConfig ()
	returns the global ConfigFile More...

template<class T >
static T	sget (const std::string &id)
	applies get on the static config instances More...

template<class T >
static T	sget (const std::string &id, const T &def)
	applies get on the static config instances (with default) More...

Private Member Functions
template<class T >
bool	check_type (const std::string &id) const
	internally used utitlity function (id must be given without prefix) More...

bool	check_type_internal (const std::string &id, const std::string &rttiTypeID) const
	internally used utitlity function More...

void	load_internal ()
	internal utitlity function to parse existing XMLDocument More...

Entry &	get_entry_internal (const std::string &id)
	internal utility function More...

const Entry &	get_entry_internal (const std::string &id) const
	internal utility function More...

void	set_internal (const std::string &id, const std::string &val, const std::string &type)
	internal utility function More...

Static Private Member Functions
static Maps *	getMapsInstance ()
	returns a singelton instance of type Maps More...

static Maps &	getMapsInstanceRef ()
	returns a singelton instance of type Maps as reference More...

template<class T >
static const std::string &	get_type_name ()
	internally used utitlity function More...

template<class T >
static const std::string &	get_rtti_type_id ()
	internally used utitlity function More...

static bool	type_registered_by_rtti (const std::string &rttiID)
	internally used utitlity function More...

static void	add_to_doc (pugi::xml_document &h, const std::string &id, const std::string &type, const std::string &value, const KeyRestriction *restr=0)
	internally synchronized an add- or a set call More...

Private Attributes
SmartPtrBase< pugi::xml_document, XMLDocumentDelOp >	m_doc
	shallow copyable smart pointer of the document handle More...

std::string	m_sDefaultPrefix
	current string prefix contents More...

std::map< std::string, Entry >	m_entries
	DataStore contents. More...

Static Private Attributes
static ConfigFile	s_oConfig
	global ConfigFile instance More...

Friends
class	ConfigFileGUI

ICLUtils_API std::ostream &	operator<< (std::ostream &, const ConfigFile &)
	ostream operator is allowed to access privat members More...

Detailed Description

Utility class for creating and reading XML-based hierarchical configuration files.

ConfigFile class can be used in object based as well as in static manner.

ConfigFile objects can e.g. be used, to locally read a configuration file or to create a configuration file. Besides a static singleton ConfigFile object accessible via ConfigFile::getConfig can be used as a global configuration for applications.
Furthermore a powerful runtime-editor called ConfigFileGUI is available in the ICLQt package.

ConfigFiles are XML-based (using ICL's XML environment for parsing and creating XML structure). The document is hierarchical as the following example demonstrates

        <?xml version='1.0' encoding='ISO-8859-1'?>
        <config>
          <title>This is the new title</title>
          <section id="general" >
            <section id="params" >
              <data type="int" id="threshold" >7</data>
              <data type="double" id="value" >6.450000</data>
              <data type="string" id="filename" >./notHallo.txt</data>
            </section>
          </section>
          <section id="special" >
            <data type="char" id="hint" >a</data>
            <data type="char" id="no-hint" >b</data>
          </section>
        </config>

Data Ranges and Value lists

In addition to the syntax above, each data-tag can be set up with a range property or a value list. Currently data ranges are only used for int- and float- typed data elements. If a range property is defined like this

        <data id="threshold" type="int" range="[0,255]">127</data>

the ConfigFileGUI editor will automatically create an integer slider with given range for this entry. (As mentioned above, this feature is also available for float-typed entries).

Value lists are only supported for string-typed entries! value lists must be defined like this:

        <data id="grabber-type" type="string" values="[pwc,dc,file,unicap]">dc</data>

(Don't forget enclosing brackets). Value lists are translated to a combobox containing all given entries. It's self-evident. that the initial value must be within the value list (otherwise an error is shown, and the combo-box value is out of date until the combo-box is use for the first time. The same is true for ranged float- or int-entry restriction.

    \section OTHERS Other Information

    When accessing ConfigFile data members, each hierarchy level must be
    separated using the '.' character. So e.g. the entry 'filename' of the example above can
    be accessed using

    \code
    ConfigFile config("myConfig.xml"); // myConfig.xml shall contain the contents above
    string fn = config["general.params.filename"];
    \endcode

    Note, that config["general.params.filename"] can only be assigned to std::string instances
    as it's type is xmlfile type is 'string'. Here we use a special C++ technique, which overloads
    the implicit cast operator for the ConfigFile::Data class (with is returned by the operator[])
    by using a template.


    To avoid errors there's also a "get"-function which can be called with a default return value:
    \code
    ConfigFile config("myConfig.xml");
    string fn = config.get<string>("general.params.filename","defaultpath.xml");
    \endcode

    In the same manner, ConfigFile entries can be generated: The example file above
    was generated with the following code (<b>Note: the "config"-prefix is
    compulsory!</b>)

    \code
    ConfigFile a;
    a["config.general.params.threshold"] = 7;
    a["config.general.params.value"] = 6.45f;
    a["config.general.params.filename"] = std::string("./hallo.txt");
    a["config.general.params.filename"] = std::string("./notHallo.txt");
    a["config.special.hint"] = 'a';
    a["config.special.no-hint"] = 'b';
    a.save("config.xml");
    \endcode

    \section TPS Types

    Functions for data access and data definition are implemented as non-inline templates,
    which are instantiated for the following types:
    - char
    - unsigned char
    - short
    - unsigned short
    - int
    - unsigned int
    - float
    - double
    - string
    - Size
    - Point
    - Rect
    - Range32s
    - Range32f

additionally we need a fixed matrix type (e.g. color)

    \section PERF Performance

    Internally data is stored in the parent classes (DataStore) hash maps to optimize
    data access. ConfigFile data key is the the '.'-concatenated identifier.

Member Typedef Documentation

◆ const_iterator

typedef std::map<std::string,Entry>::const_iterator icl::utils::ConfigFile::const_iterator

iterator type to run through all entries (const only)

Constructor & Destructor Documentation

◆ ConfigFile() [1/4]

icl::utils::ConfigFile::ConfigFile ( )

Default constructor creating an empty ConfigFile instance.

The empty ConfigFile has the following string representation:

<?xml version='1.0' encoding='ISO-8859-1'?>
<config>
  <title>no title defined"</title>
</config>

◆ ConfigFile() [2/4]

icl::utils::ConfigFile::ConfigFile ( const std::string & filename )

Creates a ConfigFile instance with given filename.

Parameters

filename if filename is found and it contains a valid ConfigFile structure, it is read into the ConfigFile instance. Otherwise, filename is stored internally for later use if load(void) or save(void) is called.

◆ ConfigFile() [3/4]

icl::utils::ConfigFile::ConfigFile ( pugi::xml_document * handle )

Creates a ConfigFile from given handle instance.

Note: Ownership is passed to this ConfigFile instance here

◆ ConfigFile() [4/4]

icl::utils::ConfigFile::ConfigFile ( std::istream & stream )

creates a ConfigFile instance from given istream.

The constructor will only read the stream until the first opening tag is closed

Member Function Documentation

◆ add_to_doc()

static void icl::utils::ConfigFile::add_to_doc	(	pugi::xml_document &	h,
		const std::string &	id,
		const std::string &	type,
		const std::string &	value,
		const KeyRestriction *	restr = `0`
	)

staticprivate

internally synchronized an add- or a set call

◆ begin()

const_iterator icl::utils::ConfigFile::begin ( ) const

inline

all-entry iterator begin

◆ check_type()

template<class T >

bool icl::utils::ConfigFile::check_type ( const std::string & id ) const

inlineprivate

internally used utitlity function (id must be given without prefix)

◆ check_type_internal()

bool icl::utils::ConfigFile::check_type_internal	(	const std::string &	id,
		const std::string &	rttiTypeID
	)		const

private

internally used utitlity function

◆ clear()

void icl::utils::ConfigFile::clear ( )

removes all contents (except config and title node)

◆ contains()

bool icl::utils::ConfigFile::contains ( const std::string & id ) const

returns whether an entry with given ID is contained

◆ end()

const_iterator icl::utils::ConfigFile::end ( ) const

inline

all-entry iterator end

◆ find() [1/2]

std::vector<Data> icl::utils::ConfigFile::find ( const std::string & regex )

returns all data entries, that match the given regex

note, the current default prefix is not used here

◆ find() [2/2]

const std::vector<Data> icl::utils::ConfigFile::find ( const std::string & regex ) const

inline

returns all data entries, that match the given regex (const);

note, the current default prefix is not used here.
note2: const-concept not implemented properly

◆ get() [1/2]

template<class T >

T icl::utils::ConfigFile::get ( const std::string & idIn ) const

inline

returns a given value from the internal string based representation (un const)

Internally, the string to T conversion is performed during this function call, so it might increase system performance to extract ConfigFile entries not in loops or something like that.
Three errors can occur:

given key id is not contained in the config file -> throws and EntryNotFoundException
given key is found, but internal type is not the type associated with template parameter T -> throws and InvalidTypeException
type associated with template parameter T is not registered at the data store -> throws an instance of UnregisteredTypeException

◆ get() [2/2]

template<class T >

T icl::utils::ConfigFile::get	(	const std::string &	idIn,
		const T &	def
	)		const

inline

returns a given value from the internal string based representation

Like the function above, except it uses a default value if given key cannot be found

◆ get_entry_internal() [1/2]

Entry& icl::utils::ConfigFile::get_entry_internal ( const std::string & id )

private

internal utility function

◆ get_entry_internal() [2/2]

const Entry& icl::utils::ConfigFile::get_entry_internal ( const std::string & id ) const

private

internal utility function

◆ get_rtti_type_id()

template<class T >

static const std::string& icl::utils::ConfigFile::get_rtti_type_id ( )

inlinestaticprivate

internally used utitlity function

◆ get_type_name()

template<class T >

static const std::string& icl::utils::ConfigFile::get_type_name ( )

inlinestaticprivate

internally used utitlity function

◆ getConfig()

static const ConfigFile& icl::utils::ConfigFile::getConfig ( )

inlinestatic

returns the global ConfigFile

◆ getEntryList()

const std::vector<const Entry*> icl::utils::ConfigFile::getEntryList ( bool relToPrefix = false ) const

inline

returns all entries as vector<const Entry*>

◆ getHandle()

const pugi::xml_document* icl::utils::ConfigFile::getHandle ( ) const

inline

returns internal document handle (forward declared here) (const only)

this function is not available in un-const manner, to avoid that users change the document structure somehow, what would cause inconsistencies between the internal XMLDocument structure and the ConfigFile data-base

◆ getMapsInstance()

static Maps* icl::utils::ConfigFile::getMapsInstance ( )

staticprivate

returns a singelton instance of type Maps

◆ getMapsInstanceRef()

static Maps& icl::utils::ConfigFile::getMapsInstanceRef ( )

inlinestaticprivate

returns a singelton instance of type Maps as reference

◆ getPrefix()

const std::string& icl::utils::ConfigFile::getPrefix ( ) const

Returns given default prefix.

◆ getRestriction()

const KeyRestriction* icl::utils::ConfigFile::getRestriction ( const std::string & id ) const

returns predefined range for given id (or 0 if no range was defined for this key)

This feature is only used by the config file GUI

◆ listContents()

void icl::utils::ConfigFile::listContents ( ) const

lists whole datastore contents

◆ load()

void icl::utils::ConfigFile::load ( const std::string & filename )

loads the ConfigFile from given filename and updates internal filename variable

Warning: old data content is lost!

◆ load_internal()

void icl::utils::ConfigFile::load_internal ( )

private

internal utitlity function to parse existing XMLDocument

◆ loadConfig() [1/2]

static void icl::utils::ConfigFile::loadConfig ( const std::string & filename )

static

loads the global ConfigFile from given filename

◆ loadConfig() [2/2]

static void icl::utils::ConfigFile::loadConfig ( const ConfigFile & configFile )

static

loads a ConfigFile object into the global config file (shallowly copied!)

◆ operator []()

Data icl::utils::ConfigFile::operator [] ( const std::string & id )

main access function to datastore entries (unconst)

◆ operator[]()

const Data icl::utils::ConfigFile::operator[] ( const std::string & id ) const

main access function to datastore entries (const)

As above, but only for reading ...

◆ register_type()

template<class T >

static void icl::utils::ConfigFile::register_type ( const std::string & id )

inlinestatic

registers a new type in the data store parsing engine

the macro REGISTER_CONFIG_FILE_TYPE(T) can be used to register new types to the data store. This macro is defined as ::icl::utils::ConfigFile::register_type<T>(T)

Note: only registered types can be loaded from an xml-file currently, the following types are registered automatically:

POD Types:

char
unsigned char
short
unsigned short
int
unsigned int
float
double
string
long int
bool

Other ICL Types:

Size
Point
Rect
Size32f
Point32f
Rect32f
Range32s
Range32f

◆ save()

void icl::utils::ConfigFile::save ( const std::string & filename ) const

Writes data to disk using given filename.

◆ set()

template<class T >

void icl::utils::ConfigFile::set	(	const std::string &	id,
		const T &	val
	)

inline

sets or updates a new data element to the ConfigFile

Warning: if not unique decidable, an explicit information about the value type T is compulsory.

e.g.

ConfigFile f;

f.set("config.filename","myText.txt");

Causes an error because the template type T is resolved as const char* which is not supported yet. Better versions use an explicit template:

ConfigFile f;

f.set<std::string>("config.filename","myText.txt");

or an explicit string argument:

ConfigFile f;

f.set("config.filename",std::string("myText.txt"));

to avoid these errors.
Note: Integer constants are of type "int" by default, and floating point constants are of type "double" by default:

◆ set_internal()

void icl::utils::ConfigFile::set_internal	(	const std::string &	id,
		const std::string &	val,
		const std::string &	type
	)

private

internal utility function

◆ setPrefix()

void icl::utils::ConfigFile::setPrefix ( const std::string & defaultPrefix ) const

Sets up a default prefix automatically put before each given key.

◆ setRestriction()

void icl::utils::ConfigFile::setRestriction	(	const std::string &	id,
		const KeyRestriction &	r
	)

defined the range for given number-type-valued key

This feature is used by the ConfigFileGUI to create appropriate slider ranges if requested

◆ sget() [1/2]

template<class T >

static T icl::utils::ConfigFile::sget ( const std::string & id )

inlinestatic

applies get on the static config instances

◆ sget() [2/2]

template<class T >

static T icl::utils::ConfigFile::sget	(	const std::string &	id,
		const T &	def
	)

inlinestatic

applies get on the static config instances (with default)

◆ type_registered_by_rtti()

static bool icl::utils::ConfigFile::type_registered_by_rtti ( const std::string & rttiID )

inlinestaticprivate

internally used utitlity function

Friends And Related Function Documentation

◆ ConfigFileGUI

friend class ConfigFileGUI

friend

◆ operator<<

ICLUtils_API std::ostream& operator<<	(	std::ostream &	,
		const ConfigFile &
	)

friend

ostream operator is allowed to access privat members

Member Data Documentation

◆ m_doc

SmartPtrBase<pugi::xml_document,XMLDocumentDelOp> icl::utils::ConfigFile::m_doc

mutableprivate

shallow copyable smart pointer of the document handle

◆ m_entries

std::map<std::string,Entry> icl::utils::ConfigFile::m_entries

private

DataStore contents.

◆ m_sDefaultPrefix

std::string icl::utils::ConfigFile::m_sDefaultPrefix

mutableprivate

current string prefix contents

◆ s_oConfig

ConfigFile icl::utils::ConfigFile::s_oConfig

staticprivate

global ConfigFile instance

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

/Users/alneuman/vm/icl/ICLUtils/src/ICLUtils/ConfigFile.h

Classes

Public Types

Public Member Functions

Static Public Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Static Private Attributes

Friends

Detailed Description

Data Ranges and Value lists

Member Typedef Documentation

◆ const_iterator

Constructor & Destructor Documentation

◆ ConfigFile() [1/4]

◆ ConfigFile() [2/4]

◆ ConfigFile() [3/4]

◆ ConfigFile() [4/4]

Member Function Documentation

◆ add_to_doc()

◆ begin()

◆ check_type()

◆ check_type_internal()

◆ clear()

◆ contains()

◆ end()

◆ find() [1/2]

◆ find() [2/2]

◆ get() [1/2]

◆ get() [2/2]

◆ get_entry_internal() [1/2]

◆ get_entry_internal() [2/2]

◆ get_rtti_type_id()

◆ get_type_name()

◆ getConfig()

◆ getEntryList()

◆ getHandle()

◆ getMapsInstance()

◆ getMapsInstanceRef()

◆ getPrefix()

◆ getRestriction()

◆ listContents()

◆ load()

◆ load_internal()

◆ loadConfig() [1/2]

◆ loadConfig() [2/2]

◆ operator []()

◆ operator[]()

◆ register_type()

◆ save()

◆ set()

◆ set_internal()

◆ setPrefix()

◆ setRestriction()

◆ sget() [1/2]

◆ sget() [2/2]

◆ type_registered_by_rtti()

Friends And Related Function Documentation

◆ ConfigFileGUI

◆ operator<<

Member Data Documentation

◆ m_doc

◆ m_entries

◆ m_sDefaultPrefix

◆ s_oConfig