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

SerializationInfoaddDictElement ()
 Add a dict element.
 
SerializationInfoaddDictKey ()
 Add a dict key.
 
SerializationInfoaddDictValue ()
 Add a dict value.
 
SerializationInfoaddElement ()
 Add a sequence element.
 
SerializationInfoaddMember (const std::string &name)
 Add a struct member.
 
SerializationInfoaddMember (const char *name)
 Add a struct member.
 
SerializationInfoaddMember (const char *name, std::size_t len)
 Add a struct member.
 
SerializationInfoaddMember (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.
 
SerializationContextcontext () 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 SerializationInfofindMember (const std::string &name) const
 Find a struct member. More...
 
const SerializationInfofindMember (const char *name) const
 Find a struct member. More...
 
SerializationInfofindMember (const std::string &name)
 Find a struct member. More...
 
SerializationInfofindMember (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 SerializationInfogetMember (const std::string &name) const
 Get a struct member.
 
const SerializationInfogetMember (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.
 
SerializationInfoparent ()
 Returns the parent node.
 
const SerializationInfoparent () 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 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);
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".