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.
Entry	addEntry (const char *name)
	Adds a top level entry.
Entry	addEntry (const std::string &name)
	Adds a top level entry.
ConstEntry	begin () const
	Begin of entries.
Entry	begin ()
	Begin of entries.
ConstEntry	end () const
	End of entries.
Entry	end ()
	End of entries.
ConstEntry	entry (const std::string &name) const
	Returns a top level entry.
ConstEntry	entry (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.
void	load (std::basic_istream< Pt::Char > &is)
	Loads settings from a input stream.
Entry	makeEntry (const char *name)
	Makes a top level entry.
Entry	makeEntry (const std::string &name)
	Makes 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	operator[] (const std::string &name)
	Returns a top level entry.
Entry	operator[] (const char *name)
	Returns 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.
ConstEntry	root () const
	Returns the root entry.
Entry	root ()
	Returns the root entry.
void	save (std::basic_ostream< Pt::Char > &os) const
	Saves settings to a output stream.

Private Types
enum	Type {   Void = 0,   Context = 1,   Reference = 2,   Boolean = 3,   Char = 4,   Str = 5,   Int8 = 6,   Int16 = 7,   Int32 = 8,   Int64 = 9,   UInt8 = 10,   UInt16 = 11,   UInt32 = 12,   UInt64 = 13,   Float = 14,   Double = 15,   LongDouble = 16,   Binary = 17,   Struct = 18,   Sequence = 19,   Dict = 20,   DictElement = 21 }
	Type identifier. More...

Private Member Functions
SerializationInfo &	addDictElement ()
	Add a dict element.
SerializationInfo &	addDictKey ()
	Add a dict key.
SerializationInfo &	addDictValue ()
	Add a dict value.
SerializationInfo &	addElement ()
	Add a sequence element.
SerializationInfo &	addMember (const std::string &name)
	Add a struct member.
SerializationInfo &	addMember (const char *name)
	Add a struct member.
SerializationInfo &	addMember (const char *name, std::size_t len)
	Add a struct member.
SerializationInfo &	addMember (const LiteralPtr< char > &name)
	Add a struct member.
Iterator	beginFormat (Formatter &formatter)
	Begin formatting.
void	beginLoad (void *p, const std::type_info &ti) const
	Begin loading.
bool	beginSave (const void *p)
	Begin saving.
template<typename T >
bool	compose (T &type) const
	Returns true if the type could be composed with a surrogate.
SerializationContext *	context () const
	Returns the used context.
template<typename T >
bool	decompose (const T &type)
	Returns true if the type could be decomposed with a surrogate.
void	endFormat (Formatter &formatter)
	End formatting.
const SerializationInfo *	findMember (const std::string &name) const
	Find a struct member. More...
const SerializationInfo *	findMember (const char *name) const
	Find a struct member. More...
SerializationInfo *	findMember (const std::string &name)
	Find a struct member. More...
SerializationInfo *	findMember (const char *name)
	Find a struct member. More...
void	finishLoad () const
	Finish loading.
void	finishSave ()
	Finish saving.
void	format (Formatter &formatter) const
	Format complete value or all members.
const char *	getBinary (std::size_t &length) const
	Get value as a binary object.
void	getBool (bool &b) const
	Get value as a bool.
void	getChar (char c) const
	Get value as a character.
void	getChar (Pt::Char &c) const
	Get value as a character.
void	getDouble (double &f) const
	Get value as a double.
void	getFloat (float &f) const
	Get value as a float.
void	getInt16 (Pt::int16_t &n) const
	Get value as a 16-bit integer.
void	getInt32 (Pt::int32_t &i) const
	Get value as a 32-bit integer.
void	getInt64 (Pt::int64_t &l) const
	Get value as a 64-bit integer.
void	getInt8 (Pt::int8_t &n) const
	Get value as a 8-bit integer.
void	getLongDouble (long double &d) const
	Get value as a long double.
const SerializationInfo &	getMember (const std::string &name) const
	Get a struct member.
const SerializationInfo &	getMember (const char *name) const
	Get a struct member.
void	getString (std::string &s, const TextCodec< Pt::Char, char > &codec) const
	Get value as a string.
void	getString (std::string &s) const
	Get value as a string.
void	getString (Pt::String &s) const
	Get value as a string.
void	getUInt16 (Pt::uint16_t &n) const
	Get value as a 16-bit unsigned integer.
void	getUInt32 (Pt::uint32_t &n) const
	Get value as a 32-bit unsigned integer.
void	getUInt64 (Pt::uint64_t &n) const
	Get value as a 64-bit unsigned integer.
void	getUInt8 (Pt::uint8_t &n) const
	Get value as a 8-bit unsigned integer.
const char *	id () const
	Returns the reference ID.
bool	isDict () const
	Returns true if dictionary type.
bool	isReference () const
	Returns true if reference.
bool	isScalar () const
	Returns true if scalar type.
bool	isSequence () const
	Returns true if sequence type.
bool	isStruct () const
	Returns true if struct type.
bool	isVoid () const
	Returns true if not set to a type.
template<typename T >
void	loadPointer (T *&fixme, unsigned mid=0) const
	Load a reference during deserialization.
template<typename T >
void	loadReference (T &fixme, unsigned mid=0) const
	Load a reference during deserialization.
std::size_t	memberCount () const
	Returns the number of members.
const char *	name () const
	Returns the instance name.
template<typename T >
void	operator<<= (SerializationInfo &si, const T *ptr)
	Serializes a pointer reference.
void	operator<<= (SerializationInfo &si, bool n)
	Serializes a bool.
void	operator<<= (SerializationInfo &si, Pt::int8_t n)
	Serializes a 8-bit integer.
void	operator<<= (SerializationInfo &si, Pt::int16_t n)
	Serializes a 16-bit integer.
void	operator<<= (SerializationInfo &si, Pt::int32_t n)
	Serializes a 32-bit integer.
void	operator<<= (SerializationInfo &si, Pt::int64_t n)
	Serializes a 64-bit integer.
void	operator<<= (SerializationInfo &si, Pt::uint8_t n)
	Serializes a 8-bit unsigned integer.
void	operator<<= (SerializationInfo &si, Pt::uint16_t n)
	Serializes a 16-bit unsigned integer.
void	operator<<= (SerializationInfo &si, Pt::uint32_t n)
	Serializes a 32-bit unsigned integer.
void	operator<<= (SerializationInfo &si, Pt::uint64_t n)
	Serializes a 64-bit unsigned integer.
void	operator<<= (SerializationInfo &si, float n)
	Serializes a float value.
void	operator<<= (SerializationInfo &si, double n)
	Serializes a double value.
void	operator<<= (SerializationInfo &si, long double n)
	Serializes a long double value.
void	operator<<= (SerializationInfo &si, char ch)
	Serializes a character value.
void	operator<<= (SerializationInfo &si, const char *str)
	Serializes a string.
void	operator<<= (SerializationInfo &si, const std::string &str)
	Serializes a std::string.
void	operator<<= (SerializationInfo &si, const Pt::String &str)
	Serializes a string.
template<typename T , typename A >
void	operator<<= (SerializationInfo &si, const std::vector< T, A > &vec)
	Serializes a std::vector.
template<typename T , typename A >
void	operator<<= (SerializationInfo &si, const std::list< T, A > &list)
	Serializes a std::list.
template<typename T , typename A >
void	operator<<= (SerializationInfo &si, const std::deque< T, A > &deque)
	Serializes a std::deque.
template<typename T , typename C , typename A >
void	operator<<= (SerializationInfo &si, const std::set< T, C, A > &set)
	Serializes a std::set.
template<typename T , typename C , typename A >
void	operator<<= (SerializationInfo &si, const std::multiset< T, C, A > &multiset)
	Serializes a std::multiset.
template<typename K , typename V , typename P , typename A >
void	operator<<= (SerializationInfo &si, const std::map< K, V, P, A > &map)
	Serializes a std::map.
template<typename T , typename C , typename P , typename A >
void	operator<<= (SerializationInfo &si, const std::multimap< T, C, P, A > &multimap)
	Serializes a std::multimap.
template<typename T >
void	operator>>= (const SerializationInfo &si, T *&ptr)
	Deserializes a pointer reference.
void	operator>>= (const SerializationInfo &si, bool &n)
	Deserializes a bool.
void	operator>>= (const SerializationInfo &si, Pt::int8_t &n)
	Deserializes an 8-bit integer.
void	operator>>= (const SerializationInfo &si, Pt::int16_t &n)
	Deserializes a 16-bit integer.
void	operator>>= (const SerializationInfo &si, Pt::int32_t &n)
	Deserializes a 32-bit integer.
void	operator>>= (const SerializationInfo &si, Pt::int64_t &n)
	Deserializes a 64-bit integer.
void	operator>>= (const SerializationInfo &si, Pt::uint8_t &n)
	Deserializes a 8-bit unsigned integer.
void	operator>>= (const SerializationInfo &si, Pt::uint16_t &n)
	Deserializes a 16-bit unsigned integer.
void	operator>>= (const SerializationInfo &si, Pt::uint32_t &n)
	Deserializes a 32-bit unsigned integer.
void	operator>>= (const SerializationInfo &si, Pt::uint64_t &n)
	Deserializes a 64-bit unsigned integer.
void	operator>>= (const SerializationInfo &si, float &n)
	Deserializes a float value.
void	operator>>= (const SerializationInfo &si, double &n)
	Deserializes a double value.
void	operator>>= (const SerializationInfo &si, long double &n)
	Deserializes a long double value.
void	operator>>= (const SerializationInfo &si, char &ch)
	Deserializes a character value.
void	operator>>= (const SerializationInfo &si, std::string &str)
	Deserializes a std::string.
void	operator>>= (const SerializationInfo &si, Pt::String &str)
	Deserializes a string.
template<typename T , typename A >
void	operator>>= (const SerializationInfo &si, std::vector< T, A > &vec)
	Deserializes a std::vector.
template<typename T , typename A >
void	operator>>= (const SerializationInfo &si, std::list< T, A > &list)
	Deserializes a std::list.
template<typename T , typename A >
void	operator>>= (const SerializationInfo &si, std::deque< T, A > &deque)
	Deserializes a std::deque.
template<typename T , typename C , typename A >
void	operator>>= (const SerializationInfo &si, std::set< T, C, A > &set)
	Deserializes a std::set. More...
template<typename T , typename C , typename A >
void	operator>>= (const SerializationInfo &si, std::multiset< T, C, A > &multiset)
	Deserializes a std::multiset. More...
template<typename K , typename V , typename P , typename A >
void	operator>>= (const SerializationInfo &si, std::map< K, V, P, A > &map)
	Deserializes a std::map.
template<typename K , typename V , typename P , typename A >
void	operator>>= (const SerializationInfo &si, std::multimap< K, V, P, A > &multimap)
	Deserializes a std::multimap.
SerializationInfo *	parent ()
	Returns the parent node.
const SerializationInfo *	parent () const
	Returns the parent node.
void	rebind (void *obj) const
	Rebind to new address.
void	rebindFixup (void *obj) const
	Rebind to new fixup address.
void	removeMember (const std::string &name)
	Remove a struct member.
void	removeMember (const char *name)
	Remove a struct member.
void	setBinary (const char *data, std::size_t length)
	Set to binary value.
void	setBool (bool b)
	Set to bool value.
void	setChar (char c)
	Set to character value.
void	setChar (const Pt::Char &c)
	Set to character value.
void	setDict ()
	Set to dictionary type.
void	setDouble (double f)
	Set to double value.
void	setFloat (float f)
	Set to float value.
void	setId (const std::string &id)
	Sets the reference ID.
void	setId (const char *id)
	Sets the reference ID.
void	setId (const char *id, std::size_t len)
	Sets the reference ID.
void	setInt16 (Pt::int16_t n)
	Set to 16-bit integer value.
void	setInt32 (Pt::int32_t n)
	Set to 32-bit integer value.
void	setInt64 (Pt::int64_t l)
	Set to 64-bit integer value.
void	setInt8 (Pt::int8_t n)
	Set to 8-bit integer value.
void	setLongDouble (long double d)
	Set to long double value.
void	setName (const std::string &name)
	Sets the instance name.
void	setName (const char *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.
void	setReference (const void *ref)
	Set to reference for which to create an ID.
void	setReference (const std::string &id)
	Set to reference with ID to fixup.
void	setReference (const char *id, std::size_t idlen)
	Set to reference with ID to fixup.
void	setSequence ()
	Set to sequence type.
void	setString (const char *s)
	Set to string value.
void	setString (const char *s, std::size_t len, const TextCodec< Pt::Char, char > &codec)
	Set to string value.
void	setString (const std::string &s)
	Set to string value.
void	setString (const std::string &str, const TextCodec< Pt::Char, char > &codec)
	Set to string value.
void	setString (const Pt::String &s)
	Set to string value.
void	setString (const Pt::Char *s, std::size_t len)
	Set to string value.
void	setStruct ()
	Set to struct type.
void	setTypeName (const std::string &type)
	Sets the type name.
void	setTypeName (const char *type)
	Sets the type name.
void	setTypeName (const char *type, std::size_t len)
	Sets the type name.
void	setTypeName (const LiteralPtr< char > &type)
	Sets the type name.
void	setUInt16 (Pt::uint16_t n)
	Set to 16-bit unsigned integer value.
void	setUInt32 (Pt::uint32_t n)
	Set to 32-bit unsigned integer value.
void	setUInt64 (Pt::uint64_t n)
	Set to 64-bit unsigned integer value.
void	setUInt8 (Pt::uint8_t n)
	Set to 8-bit unsigned integer value.
void	setVoid ()
	Set to void type.
Type	type () const
	Returns the type identifier.
const char *	typeName () const
	Returns the type 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".