MCIniFile Class Reference

Implementation of an initialization file (ini file for short). More...

#include <mcllib/MCIniFile.h>

Inheritance diagram for MCIniFile:

List of all members.

Public Member Functions
bool	exists (const MCString &sectionName, const MCString &key)
	Check to see if a key exists in a section of the ini file.
bool	exists (const MCString &sectionName)
	Check to see if a section exists in the ini file.
MCString	expand (const MCString &str)
	Expand a string containing variable references.
MCString	get (const MCString &sectionKey)
	Get a value from a section of the ini file.
MCString	get (const MCString &sectionName, const MCString &key)
	Get a value from a section of the ini file.
bool	isOpen () const
	Check to see if the ini file is open.
	MCIniFile (const MCString &fileName, bool readOnly=true)
	Initialize the ini file from a file in the filesystem.
	MCIniFile ()
	Default constructor.
void	open (const MCString &fileName, bool readOnly=true)
	Initialize the ini file from a file in the filesystem.
MCIniSection &	operator[] (const MCString &sectionName)
	Get a section in the ini file.
void	sync (bool clear=false)
	Synchronize the contents of the ini file with filesystem.

---

Detailed Description

Implementation of an initialization file (ini file for short).

An ini file is a structured text file used to provide configuration information for an application. The format of the file is

    [section]
     var1=value1
     var2=value2
     ...

The file may contain multiple sections where the open and close square brackets are literal text that must be included. A section will only be recognized if the open square bracket appears at the beginning of a line. All the text between the open and close square brackets is used as the name of the section (except any leading and trailing white space). If there is more than one section with the same name (ignoring case) all the contents from the like-named sections are merged together as if the ini file contained a single section with all contents in it. The closing square bracket may be optionally followed by trailing white space which is ignored.

Each section may contain multiple variable assignments. A variable assignment consists of a variable name followed by an equals sign followed optionally by a value. Only the value part may be empty. All the text up to the equals sign (except any leading and trailing white space) is used as the name of the variable. All the text after the equals sign (including any leading and trailing white space) is used as the value of the variable. A variable may be repeated multiple times, only the last value will be used. The preceding values are discarded.

The file can be commented using lines which begin with semi-colon (;) or hash (#). Comments and blank lines are ignored.

This class is intentionally not thread safe for performance reasons. To be thread safe, lock a mutex before accessing its member functions.

---

Constructor & Destructor Documentation

MCIniFile (   )

Default constructor. The open method can specify the ini file to use.

MCIniFile (  const MCString &  fileName, bool  readOnly = true )

Initialize the ini file from a file in the filesystem. Parameters: fileName  the name of the file to open. readOnly  if true modifications to the ini file will not be written back to the file on sync().

---

Member Function Documentation

bool exists (  const MCString &  sectionName, const MCString &  key )

Check to see if a key exists in a section of the ini file. The check is case insensitive. Parameters: sectionName  name of the section to check for. key  name of the key to check for in the section. Returns: true if the section exists and the key exists within the section.

bool exists (  const MCString &  sectionName  )

Check to see if a section exists in the ini file. The check is case insensitive. Parameters: sectionName  name of the section to check for. Returns: true if the section exists

MCString expand (  const MCString &  str  )

Expand a string containing variable references. Takes a string which may contain variable references and looks up the variable references in the ini file, replacing them with the value found in the ini file. Variable references use the following syntax ${section.key} where section and key are passed to the get() method. Variable expansion using expand is recursive. This means that if the referenced strings contains variable references, these are in turn expanded. There is a limit on the level of nesting of variable references to detect infinite recursion. The limit is sufficiently large for all practical purposes. Parameters: str  the section/key pair to get a value for and expand Returns: the value of the key if the section exists and the key exists within it, with variables replaced by their corresponding value.

MCString get (  const MCString &  sectionKey  )

Get a value from a section of the ini file. The check for section and key is case insensitive. Parameters: sectionKey  a section/key pair separated by the '.' (dot) character. Returns: the value of the key if the section exists and the key exists within it. Otherwise an empty string is returned. Get the value for the section/key pair (ignoring case).

MCString get (  const MCString &  sectionName, const MCString &  key )

Get a value from a section of the ini file. The check for section and key is case insensitive. Parameters: sectionName  name of the section to search. key  name of the key within the section to obtain a value for. Returns: the value of the key if the section exists and the key exists within it. Otherwise an empty string is returned.

bool isOpen (   )  const

Check to see if the ini file is open. Returns: true if the ini file has had open called on it successfully.

void open (  const MCString &  fileName, bool  readOnly = true )

Initialize the ini file from a file in the filesystem. Parameters: fileName  is the name of the file to open. readOnly  if true modifications to the ini file will not be written back to the file on sync().

MCIniSection& operator[] (  const MCString &  sectionName  )

Get a section in the ini file. Parameters: sectionName  the name of the section to get. If the section does not already exist in the ini file, it will be created. If the ini file was opened read-only then the next call to sync() with clear set to true will cause all such modifications to be discarded. If the ini file was opened read-write then the next call to sync() will cause the contents to over-write the filesystem version of the ini file.

void sync (  bool  clear = false  )

Synchronize the contents of the ini file with filesystem. If the ini file was open()-ed read-only then the modification time of the file in the filesystem is checked and (if it has changed) the file is re-read. If the ini file was open()-ed read-write then the contents of the ini file are written to the filesystem. Todo: writing the contents back to the file Parameters: clear  if true any information already in the in-memory ini file is discarded before reading from the filesystem. If clear is false the information in the filesystem is merged with whatever is already in the in-memory ini file. This flag only applies if the ini file is read-only.

---