Image Component Library (ICL)
Classes | Public Types | Public Member Functions | Static Public Member Functions | Private Member Functions | Static Private Member Functions | Private Attributes | Static Private Attributes | Friends | List of all members
icl::utils::ConfigFile Class Reference

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

#include <ConfigFile.h>

Inheritance diagram for icl::utils::ConfigFile:
icl::utils::Lockable

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) throw (FileNotFoundException,InvalidFileFormatException,UnregisteredTypeException)
 Creates a ConfigFile instance with given filename. More...
 
 ConfigFile (pugi::xml_document *handle) throw (UnregisteredTypeException)
 Creates a ConfigFile from given handle instance. More...
 
 ConfigFile (std::istream &stream) throw (FileNotFoundException,InvalidFileFormatException,UnregisteredTypeException)
 creates a ConfigFile instance from given istream. More...
 
void load (const std::string &filename) throw (FileNotFoundException,InvalidFileFormatException,UnregisteredTypeException)
 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 throw (EntryNotFoundException)
 main access function to datastore entries (const) More...
 
std::vector< Datafind (const std::string &regex)
 returns all data entries, that match the given regex More...
 
const std::vector< Datafind (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) throw (UnregisteredTypeException)
 sets or updates a new data element to the ConfigFile More...
 
template<class T >
get (const std::string &idIn) const throw (EntryNotFoundException,InvalidTypeException,UnregisteredTypeException)
 returns a given value from the internal string based representation (un const) More...
 
template<class T >
get (const std::string &idIn, const T &def) const throw (InvalidTypeException,UnregisteredTypeException)
 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) throw (EntryNotFoundException)
 defined the range for given number-type-valued key More...
 
const KeyRestrictiongetRestriction (const std::string &id) const throw (EntryNotFoundException)
 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...
 
Lockableoperator= (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...
 
MutexgetMutex () 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 ConfigFilegetConfig ()
 returns the global ConfigFile More...
 
template<class T >
static T sget (const std::string &id) throw (EntryNotFoundException,InvalidTypeException)
 applies get on the static config instances More...
 
template<class T >
static T sget (const std::string &id, const T &def) throw (InvalidTypeException)
 applies get on the static config instances (with default) More...
 

Private Member Functions

template<class T >
bool check_type (const std::string &id) const throw (EntryNotFoundException,UnregisteredTypeException)
 internally used utitlity function (id must be given without prefix) More...
 
bool check_type_internal (const std::string &id, const std::string &rttiTypeID) const throw (EntryNotFoundException,UnregisteredTypeException)
 internally used utitlity function More...
 
void load_internal ()
 internal utitlity function to parse existing XMLDocument More...
 
Entryget_entry_internal (const std::string &id) throw (EntryNotFoundException)
 internal utility function More...
 
const Entryget_entry_internal (const std::string &id) const throw (EntryNotFoundException)
 internal utility function More...
 
void set_internal (const std::string &id, const std::string &val, const std::string &type) throw (UnregisteredTypeException)
 internal utility function More...
 

Static Private Member Functions

static MapsgetMapsInstance ()
 returns a singelton instance of type Maps More...
 
static MapsgetMapsInstanceRef ()
 returns a singelton instance of type Maps as reference More...
 
template<class T >
static const std::string & get_type_name () throw (UnregisteredTypeException)
 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, Entrym_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. <b>Currently
    data ranges are only used for int- and float- typed data elements</b>. If a range property is defined like this

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

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

    <b>Value lists are only supported for string-typed entries!</b> value lists must be defined like this:
    <pre>
    \<data id="grabber-type" type="string" values="[pwc,dc,file,unicap]"\>dc\</data\>
    </pre>
    (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.

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
ConfigFile config("myConfig.xml"); // myConfig.xml shall contain the contents above
string fn = config["general.params.filename"];

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:
ConfigFile config("myConfig.xml");
string fn = config.get<string>("general.params.filename","defaultpath.xml");

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

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");

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)

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

iterator type to run through all entries (const only)

Constructor & Destructor Documentation

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>
icl::utils::ConfigFile::ConfigFile ( const std::string &  filename)
throw (FileNotFoundException,
InvalidFileFormatException,
UnregisteredTypeException
)

Creates a ConfigFile instance with given filename.

Parameters
filenameif 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.
icl::utils::ConfigFile::ConfigFile ( pugi::xml_document *  handle)
throw (UnregisteredTypeException
)

Creates a ConfigFile from given handle instance.

Note: Ownership is passed to this ConfigFile instance here

icl::utils::ConfigFile::ConfigFile ( std::istream &  stream)
throw (FileNotFoundException,
InvalidFileFormatException,
UnregisteredTypeException
)

creates a ConfigFile instance from given istream.

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

Member Function Documentation

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

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

all-entry iterator begin

template<class T >
bool icl::utils::ConfigFile::check_type ( const std::string &  id) const
throw (EntryNotFoundException,
UnregisteredTypeException
)
inlineprivate

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

bool icl::utils::ConfigFile::check_type_internal ( const std::string &  id,
const std::string &  rttiTypeID 
) const
throw (EntryNotFoundException,
UnregisteredTypeException
)
private

internally used utitlity function

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

removes all contents (except config and title node)

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

returns whether an entry with given ID is contained

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

all-entry iterator end

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

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

template<class T >
T icl::utils::ConfigFile::get ( const std::string &  idIn) const
throw (EntryNotFoundException,
InvalidTypeException,
UnregisteredTypeException
)
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:

  1. given key id is not contained in the config file -> throws and EntryNotFoundException
  2. given key is found, but internal type is not the type associated with template parameter T -> throws and InvalidTypeException
  3. type associated with template parameter T is not registered at the data store -> throws an instance of UnregisteredTypeException
template<class T >
T icl::utils::ConfigFile::get ( const std::string &  idIn,
const T &  def 
) const
throw (InvalidTypeException,
UnregisteredTypeException
)
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

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

internal utility function

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

internal utility function

template<class T >
static const std::string& icl::utils::ConfigFile::get_rtti_type_id ( )
inlinestaticprivate

internally used utitlity function

template<class T >
static const std::string& icl::utils::ConfigFile::get_type_name ( )
throw (UnregisteredTypeException
)
inlinestaticprivate

internally used utitlity function

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

returns the global ConfigFile

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

returns all entries as vector<const Entry*>

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

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

returns a singelton instance of type Maps

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

returns a singelton instance of type Maps as reference

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

Returns given default prefix.

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

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

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

lists whole datastore contents

void icl::utils::ConfigFile::load ( const std::string &  filename)
throw (FileNotFoundException,
InvalidFileFormatException,
UnregisteredTypeException
)

loads the ConfigFile from given filename and updates internal filename variable

Warning: old data content is lost!

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

internal utitlity function to parse existing XMLDocument

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

loads the global ConfigFile from given filename

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

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

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

main access function to datastore entries (unconst)

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

main access function to datastore entries (const)

As above, but only for reading ...

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:

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

Writes data to disk using given filename.

template<class T >
void icl::utils::ConfigFile::set ( const std::string &  id,
const T &  val 
)
throw (UnregisteredTypeException
)
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.

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:

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

or an explicit string argument:

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:

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

internal utility function

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

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

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

defined the range for given number-type-valued key

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

template<class T >
static T icl::utils::ConfigFile::sget ( const std::string &  id)
throw (EntryNotFoundException,
InvalidTypeException
)
inlinestatic

applies get on the static config instances

template<class T >
static T icl::utils::ConfigFile::sget ( const std::string &  id,
const T &  def 
)
throw (InvalidTypeException
)
inlinestatic

applies get on the static config instances (with default)

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

internally used utitlity function

Friends And Related Function Documentation

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

ostream operator is allowed to access privat members

Member Data Documentation

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

shallow copyable smart pointer of the document handle

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

DataStore contents.

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

current string prefix contents

ConfigFile icl::utils::ConfigFile::s_oConfig
staticprivate

global ConfigFile instance


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