Settings Class Reference

#include <Pt/Settings.h>

Store application settings. More...

Inherits SerializationInfo.

Classes
class	ConstEntry
	Constant settings entry. More...
class	Entry
	Modifiable settings entry. More...

Public Member Functions
	Settings ()
	Default constructor.
void	clear ()
	Clears the settings.
bool	isEmpty () const
	Returns true if settings are empty.
void	setName (const char *name)
	Sets the name of the settings root.
ConstEntry	begin () const
	Begin of entries.
ConstEntry	end () const
	End of entries.
ConstEntry	root () const
	Returns the root entry.
Entry	begin ()
	Begin of entries.
Entry	end ()
	End of entries.
Entry	root ()
	Returns the root entry.
void	load (std::basic_istream< Pt::Char > &is)
	Loads settings from a input stream.
void	load (Pt::Formatter &formatter)
	Loads settings using a formatter.
void	save (std::basic_ostream< Pt::Char > &os) const
	Saves settings to a output stream.
void	save (Pt::Formatter &formatter) const
	Saves settings using a formatter.
ConstEntry	entry (const std::string &name) const
	Returns a top level entry.
ConstEntry	entry (const char *name) const
	Returns a top level entry.
ConstEntry	operator[] (const std::string &name) const
	Returns a top level entry.
ConstEntry	operator[] (const char *name) const
	Returns a top level entry.
Entry	entry (const std::string &name)
	Returns a top level entry.
Entry	entry (const char *name)
	Returns a top level entry.
Entry	addEntry (const char *name)
	Adds a top level entry.
Entry	addEntry (const std::string &name)
	Adds a top level entry.
Entry	makeEntry (const char *name)
	Makes a top level entry.
Entry	makeEntry (const std::string &name)
	Makes a top level entry.
void	removeEntry (const char *name)
	Removes a top level entry.
void	removeEntry (const std::string &name)
	Removes a top level entry.
Entry	operator[] (const std::string &name)
	Returns a top level entry.
Entry	operator[] (const char *name)
	Returns a top level entry.

Private Member Functions
void	setName (const std::string &name)
	Sets the instance name.
void	setName (const char *type, std::size_t len)
	Sets the instance name.
void	setName (const LiteralPtr< char > &type)
	Sets the instance name.

Detailed Description

Many programs need to be able to restore its settings from a persistent location, such as a file. The Settings class provides an hierachical organisation of settings entries and an API to read and write them in a text format. The following example illustrates how settings can be read from a file:

std::ifstream ifs("app.settings");
Pt::TextIStream tis(ifs, new Pt::Utf8codec);
 
Pt::Settings settings;
settings.load(tis);

Settings can be loaded from any input stream, so the API is not limited to files. In this example, a file stream is opened and a text input stream is used to read UTF-8 encoded text. Another interesting use-case is to load settings from a string stream, which can greatly simplify unit testing. Writing settings to a file is just as easy:

std::ofstream ofs("app.settings", std::ios::out|std::ios::trunc);
Pt::TextOStream tos(ofs, new Pt::Utf8codec);
 
Pt::Settings settings;
settings.save(tos);

Any output stream can be used to save the settings, in this case UTF-8 encoded text is written to a file. Note, that the file is truncated when opened, so the content is replaced.

Settings are saved in a compact text format, which supports integers, floats, strings and booleans as scalar value types and arrays and structs as compound types. The next example shows some possibilities:

a = 1
b = 3.14
c = "Hello World!"
d = true
e = [ 1, 2, 3 ]
f = { red = 255, green = 0, blue = 0 }

The entry values for a, b, c and d are of type integer, float, string and bool, respectively. The entries e and f demonstrate the syntax for arrays and structs. The following example shows how such a settings file can be loaded and how the entries are accessed:

std::ifstream ifs("app.settings");
Pt::TextIStream tis(ifs, new Pt::Utf8codec);
 
Pt::Settings settings;
settings.load(tis);
 
int a = 0;
bool ok = settings["a"].get(a);
 
float b = 0;
ok = settings.entry("b").get(b);
 
Pt::String c;
ok = settings.entry("c").get(c);
 
bool d = false;
ok = settings.entry("d").get(d);
 
std::vector<int> e;
ok = settings.entry("e").get(e);
 
Color f;
ok = settings.entry("f").get(f);

The entry() method or alternatively, the index operator can be used, to access entries and subentries by name. If a subentry does not exist, an empty entry object will be returned. Values can be retrieved with the get() method, which returns false, if the value does not exist. The data type, which is stored in the settings must be serializable i.e. the serialization operators must be defined. The framework defines the serialization operators for STL containers, so these work out of the box. The set() function can be used to set an entry to a new value, before the modified settings are saved. New subentries can be added using the addEntry() function.

Settings can be split into sections, to improve the readability of the file, using the following syntax:

[animals]
a = "dog"
b = "cat"
 
[plants]
a = "tulip"
b = "rose"

When such a settings file is loaded, it will contain two entries named "animals" and "plants". Both entries will have two subentries named "a" and "b".