base::ConfigFile Class Reference

///
/// Overview:
/// ---------
/// This class is for storing and reading a program's configuration to a file
/// (and it could be used as a simple database in lieue of DB or GDBM).
/// The configuration data consisting of type/key/value tuples similar in concept
/// to GNOME's gnome_config*().  A tuple's value has a type (int, float, string).
///
/// NOTE/WARNING: If auto-flush is disabled (for speed), client must periodically call Flush().
/// Write() just updates a STL map, it doesn't write to the configuration file!
///
/// How to use:
/// -----------
/// The configuration file is opened by the constructor and closed by the destructor.
/// Example of opening the configuration file:
///
///    ConfigFile config( "ProgramName" );
///    if ( config.IfEmpty() ) return;          // configuration is new (ok)
///    if ( ! config.IfValid() ) { Error(); }   // error
///
/// Each tuple consists of a key (name), its value, and its value's type.
/// To store a tuple, call Write().
/// To retrieve a tuple, call Read().
/// To remove a tuple, call Remove().
///
///    config.Write( "highscore", (int)    536000  );
///    config.Write( "game",      (string) "PacMan" );
///    config.Write( "offset",    (double) 0.123   );
///    config.Read(  "highscore", highscore );
///    config.Remove( "highscore" );
///
/// Access() is provided in order to write a a common function that
/// stores and retrieves tuples depending on a variable:
///
///    (don't write "access" as it's in unistd.h)
///
///    int acc = ConfigFile::eAccess_READ;
///    int acc = ConfigFile::eAccess_WRITE;
///    config.Access( acc, "highscore", &highscore );
///
/// Methods that modify the configuration will automatically update (flush)
/// changes to the configuration file.  But optionally for speed, autoflush
/// can be disabled by a constructor arg.  Disabling autoflush is faster but
/// then the user is responsible for calling Flush() or else changes will be lost!
///
/// Restrictions/limitations:
/// -------------------------
/// o Keys must not contain any whitespace (but string values can).
/// o If the end-user writes comments to the configuration file
///   (or does any change for that matter), they'll be discarded/overwritten
///   when the program modifies the configuration.
///
/// Implementation notes:
/// ---------------------
/// The configuration file consists of a set of lines containing tuples.
/// A tuple consists of a key, its value, its value's type (int,double,string).
///
/// For example, starting with a new configuration file, this code...
///
///    Write( "game",      "PacMan"        );
///    Write( "highscore", (int)    536000 );
///    Write( "offset",    (double) 0.123  );
///
/// ...would produce these lines:
///
/// string game 6 PacMan
/// int highscore 536000
/// double offset 0.123
/// END
///
/// String values have a length field, hence the 6 for "PacMan".
///
/// "END" may indeed appear more than once.  The tuples after the first "END"
/// are removed tuples.  This will happen if the configuration file once had
/// more tuples than it currently does.
///
///

base::ConfigFile::ConfigFile	(	const string &	programName,
		const string &	fname = `""`,
		bool	autoflush = `true`
	)

ctor

Parameters:

	programName	Required.
	fname	Optional, default is empty string, specify name of configuration file.
	autoflush	Optional, default is true, control flushing of configuration changes.

NOTE/WARNING: If auto-flush is disabled (for speed), client must periodically call Flush(). Write() just updates a STL map, it doesn't write to the configuration file!

Optionally, the constructor can be told which file to use for the configuration, and whether to auto-flush changes to the configuration. Setting auto-flush to false is faster (lazy-writes) but then the client becomes responsible for calling Flush() (actually writes to the file) or changes will be lost!


Public Types
enum	eAccess { eAccess_WRITE, eAccess_READ }
Public Member Functions
	ConfigFile (const string &programName, const string &fname="", bool autoflush=true)
	~ConfigFile ()
bool	IfValid (void)
bool	IfEmpty (void)
bool	Write (const string &key, const int &val)
bool	Write (const string &key, const double &val)
bool	Write (const string &key, const string &val)
bool	Read (const string &key, int &val)
bool	Read (const string &key, double &val)
bool	Read (const string &key, string &val)
bool	Access (ConfigFile::eAccess acc, const string &key, int &val)
bool	Access (ConfigFile::eAccess acc, const string &key, double &val)
bool	Access (ConfigFile::eAccess acc, const string &key, string &val)
bool	Remove (const string &key)
bool	Flush (void)
Private Member Functions
bool	Parse (void)
Private Attributes
bool	mValid
	if configuration is OK
bool	mAutoflush
	if false the user must call Flush()
string	mProgramName
	might determine name of configuration file
fstream	mStream
	configuration file
map< string, ConfigTuple >	mTupleMap
	map of tuples
Friends
bool	CompareTuples (const ConfigFile::ConfigTuple &t1, const ConfigFile::ConfigTuple &t2)
Classes
class	ConfigTuple
	Defines a configuration item value and type (int/double/string). More...

bool base::ConfigFile::Write	(	const string &	key,
		const int &	val
	)

bool base::ConfigFile::Write	(	const string &	key,
		const double &	val
	)

bool base::ConfigFile::Write	(	const string &	key,
		const string &	val
	)

bool base::ConfigFile::Read	(	const string &	key,
		int &	val
	)

base::ConfigFile Class Reference

Public Types

Public Member Functions

Private Member Functions

Private Attributes

Friends

Classes

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation

bool base::ConfigFile::Access	(	ConfigFile::eAccess	acc,
		const string &	key,
		int &	val
	)

bool CompareTuples	(	const ConfigFile::ConfigTuple &	t1,
		const ConfigFile::ConfigTuple &	t2
	)			`[friend]`

eAccess_WRITE
eAccess_READ