#include <Pt/Settings.h>

Hierarchical application settings loaded from text. More...

Classes
class	Entry
	Modifiable settings entry. More...
class	ConstEntry
	Constant 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

Settings is a tree of named entries that a program can load, change, and save. The unit of persistence is the whole tree. load() replaces it from a std::basic_istream of Pt::Char or from a Formatter. save() writes it the same way. A file is a typical source, but a string stream is equally valid, which is useful in tests.

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

The text format stores scalars, arrays, and structs. Integers, floating-point values, strings, and booleans are scalars. An array is a bracketed list. A struct is a brace-delimited list of named members. A [section] line is a top-level struct: the names that follow become its members until the next section.

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

After a load, that file has top-level entries a through f and a top-level entry animals with subentries a and b. entry() and operator[] return a ConstEntry or Entry by name. A missing name yields an empty entry. Empty entries are false in boolean context. get() extracts a serializable value and returns false when the entry is empty. set() replaces the value of an existing entry. addEntry() and makeEntry() create members; makeEntry() returns the member if it already exists. removeEntry() drops a member.

The stored type must have serialization operators. STL containers already do. A user type needs operator<<= and operator>>= for SerializationInfo, the same operators the rest of the serialization framework uses. Settings privately inherits SerializationInfo; do not use that base as a public API.

int a = 0;
bool ok = settings["a"].get(a);
 
std::vector<int> e;
ok = settings.entry("e").get(e);
 
settings.makeEntry("port").set(8080);
settings.save(tos);

load() from malformed text throws SettingsError, which reports the line of the failure. Saving truncates nothing by itself; open the destination stream with ios::trunc when the file should be replaced. Entry iterates like a sibling walk: begin() / end() and operator++ move to the next member of the same parent.

Classes

Public Member Functions

Private Member Functions

Detailed Description