Main Page | Namespace List | Class Hierarchy | Alphabetical List | Class List | File List | Namespace Members | Class Members | File Members

Dv::Util::Props Class Reference

A propert list class. More...

#include <props.h>

List of all members.

Public Types

typedef std::map< std::string,
std::string * > 
propmap
 The underlying implementation type.
typedef propmap::const_iterator iterator
 Map iterator, *iterator is a pair<std::string,*std::string>.

Public Member Functions

 Props ()
 Default constructor.
 Props (std::istream &is)
 Reads value=key pairs from istream.
virtual ~Props ()
 Virtual destructor.
Propserase (const std::string &key)
 Erase any value that is associated with key.
Propsclear ()
 Erase all key = value pairs from the property list.
Propsadd (const std::string &key, const std::string &value)
 Add a key = value pair.
Propsappend (const std::string &key, const std::string &value, const std::string &separator=" ")
 Append to a value associated with a key.
const std::string * find (const std::string &key) const
 Try to find value for key, return null if not found.
const std::string * operator() (const std::string &key) const
 Try to find value for key, return null if not found.
iterator begin () const
iterator end () const
unsigned size () const
std::istream & read (std::istream &is, int n=-1)
 Read n key=value pairs from istream, or until eof if n <0.
ConstValue operator>> (const char *key) const
 Return a reference to the key=value pair with the given key.
void substitute (std::istream &sin, std::ostream &sout, std::string(*f)(const std::string &)=0) const throw (std::invalid_argument)
 Recursively substitute variable occurrences in sin to yield sout.
void substitute (const std::string &sin, std::string &sout, std::string(*f)(const std::string &)=0) const throw (std::invalid_argument)
 Recursively substitute variable occurrences in sin to yield sout.
std::string substitute (const std::string &sin, std::string(*f)(const std::string &)=0) const throw (std::invalid_argument)
 Same as above but returns result std::string.
Propsselect (const std::string &scope, Props &target) const
 Insert selected subkey=value pairs of this object into the target.
Propsmerge (const Props &source, const std::string &scope="") throw (PropsException)
 Load all key-value pairs from another props object under a certain scope.
bool operator== (const Props &) const
 Compare two Props objects.
bool operator!= (const Props &p) const
std::ostream & send (std::ostream &os) const
 Send a props object over a stream.
std::istream & receive (std::istream &is)
 Receive a props object from a stream.
 Props (const Props &props) throw (PropsException)
 Copy construction is allowed.
Propsoperator= (const Props &props) throw (PropsException)
 Assignment allowed.
ConstValue operator[] (const std::string &key) const throw (PropsException)
 Key-based ``r-value'' access to properties.
ConstValue operator[] (int key) const throw (PropsException)
 Key-based ``r-value'' access to properties.
ConstValue operator[] (unsigned int key) const throw (PropsException)
 Key-based ``r-value'' access to properties.
ConstValue operator[] (long key) const throw (PropsException)
 Key-based ``r-value'' access to properties.
ConstValue operator[] (unsigned long key) const throw (PropsException)
 Key-based ``r-value'' access to properties.
ConstValue operator[] (short key) const throw (PropsException)
 Key-based ``r-value'' access to properties.
ConstValue operator[] (unsigned short key) const throw (PropsException)
 Key-based ``r-value'' access to properties.
ConstValue operator[] (const double &key) const throw (PropsException)
 Key-based ``r-value'' access to properties.
Value operator[] (const std::string &k)
 Key-based l-value access to properties.
Value operator[] (int k)
 Key-based l-value access to properties.
Value operator[] (unsigned int k)
 Key-based l-value access to properties.
Value operator[] (long k)
 Key-based l-value access to properties.
Value operator[] (unsigned long k)
 Key-based l-value access to properties.
Value operator[] (short k)
 Key-based l-value access to properties.
Value operator[] (unsigned short k)
 Key-based l-value access to properties.
Value operator[] (const double &k)
 Key-based l-value access to properties.

Private Member Functions

std::string * found (const std::string &key)

Private Attributes

propmap props_

Friends

std::ostream & operator<< (std::ostream &, const Props &)
 Write the Props object to the stream, in the format described above.
std::istream & operator>> (std::istream &is, Props &props)
 Read key-value pairs from istream until the end of the stream is reached or a syntax error occurs.


Detailed Description

A propert list class.

A Props object represents a mapping from key strings to value strings. Values can be accessed with Props::operator[], using both strings or integers as a key (the latter will first be converted to strings); the resulting value will be converted to string or int, as required. The result of Props::operator[]} can be assigned to, thus giving a simple way to update.

A Props objects can be read from and written to a stream, in a format that is illustrated below (| indicates the beginning of a line):

   |database=my-database
   |query=select name, semester
   |>from course
   |host=mainserver
   |# a comment
   |age=99
   

Note that

Definition at line 81 of file props.h.


Member Typedef Documentation

typedef std::map<std::string,std::string*> Dv::Util::Props::propmap
 

The underlying implementation type.

Definition at line 282 of file props.h.

typedef propmap::const_iterator Dv::Util::Props::iterator
 

Map iterator, *iterator is a pair<std::string,*std::string>.

Definition at line 446 of file props.h.

Referenced by begin(), and end().


Constructor & Destructor Documentation

Dv::Util::Props::Props  )  [inline]
 

Default constructor.

Definition at line 287 of file props.h.

Dv::Util::Props::Props std::istream &  is  ) 
 

Reads value=key pairs from istream.

Parameters:
is istream from which key=value pairs are are read.
This constructor uses Props::read(istream&, -1) to read the rest of the open istream into a Props object. This constructor is convenient to read in configuration files in a format as described above.
 ifstream ifs("/usr/local/share/z.config");
 Props config(ifs);
 try {
   int max = config["max"];
   }
 catch (PropsException& e) {
   cerr << "Configuration file does not define 'max'" << endl;
   exit(1);
   }
Warning:
Note that this constructor does not work properly with streams that have no clear ``eof'' indication, e.g. simple network connections.
See also:
Props

virtual Dv::Util::Props::~Props  )  [virtual]
 

Virtual destructor.

Dv::Util::Props::Props const Props props  )  throw (PropsException)
 

Copy construction is allowed.


Member Function Documentation

ConstValue Dv::Util::Props::operator[] const std::string &  key  )  const throw (PropsException)
 

Key-based ``r-value'' access to properties.

Parameters:
key value, can be of a variety of types, it will be converted to std::string.
Returns:
a Props::ConstValue which can be converted to a variety of types.
Exceptions:
PropsException if no value for key can be found.
See also:
Props::ConstValue::operator int
This overloaded member functions supports, together with the conversion functions for Props::ConstValue, simple retrieval a value corresponding to a given key, as illustrated in the following example.
 props["name"] = "lisa";
 props[0] = "zero";
 props[10] = 11;
 props["age"] = 21;
  
 int age(props["age"]);
 std::string name(props["name"]);
 int n(props[10]);

ConstValue Dv::Util::Props::operator[] int  key  )  const throw (PropsException)
 

Key-based ``r-value'' access to properties.

Parameters:
key value, can be of a variety of types, it will be converted to std::string.
Returns:
a Props::ConstValue which can be converted to a variety of types.
Exceptions:
PropsException if no value for key can be found.
See also:
Props::ConstValue::operator int
This overloaded member functions supports, together with the conversion functions for Props::ConstValue, simple retrieval a value corresponding to a given key, as illustrated in the following example.
 props["name"] = "lisa";
 props[0] = "zero";
 props[10] = 11;
 props["age"] = 21;
  
 int age(props["age"]);
 std::string name(props["name"]);
 int n(props[10]);

ConstValue Dv::Util::Props::operator[] unsigned int  key  )  const throw (PropsException)
 

Key-based ``r-value'' access to properties.

Parameters:
key value, can be of a variety of types, it will be converted to std::string.
Returns:
a Props::ConstValue which can be converted to a variety of types.
Exceptions:
PropsException if no value for key can be found.
See also:
Props::ConstValue::operator int
This overloaded member functions supports, together with the conversion functions for Props::ConstValue, simple retrieval a value corresponding to a given key, as illustrated in the following example.
 props["name"] = "lisa";
 props[0] = "zero";
 props[10] = 11;
 props["age"] = 21;
  
 int age(props["age"]);
 std::string name(props["name"]);
 int n(props[10]);

ConstValue Dv::Util::Props::operator[] long  key  )  const throw (PropsException)
 

Key-based ``r-value'' access to properties.

Parameters:
key value, can be of a variety of types, it will be converted to std::string.
Returns:
a Props::ConstValue which can be converted to a variety of types.
Exceptions:
PropsException if no value for key can be found.
See also:
Props::ConstValue::operator int
This overloaded member functions supports, together with the conversion functions for Props::ConstValue, simple retrieval a value corresponding to a given key, as illustrated in the following example.
 props["name"] = "lisa";
 props[0] = "zero";
 props[10] = 11;
 props["age"] = 21;
  
 int age(props["age"]);
 std::string name(props["name"]);
 int n(props[10]);

ConstValue Dv::Util::Props::operator[] unsigned long  key  )  const throw (PropsException)
 

Key-based ``r-value'' access to properties.

Parameters:
key value, can be of a variety of types, it will be converted to std::string.
Returns:
a Props::ConstValue which can be converted to a variety of types.
Exceptions:
PropsException if no value for key can be found.
See also:
Props::ConstValue::operator int
This overloaded member functions supports, together with the conversion functions for Props::ConstValue, simple retrieval a value corresponding to a given key, as illustrated in the following example.
 props["name"] = "lisa";
 props[0] = "zero";
 props[10] = 11;
 props["age"] = 21;
  
 int age(props["age"]);
 std::string name(props["name"]);
 int n(props[10]);

ConstValue Dv::Util::Props::operator[] short  key  )  const throw (PropsException)
 

Key-based ``r-value'' access to properties.

Parameters:
key value, can be of a variety of types, it will be converted to std::string.
Returns:
a Props::ConstValue which can be converted to a variety of types.
Exceptions:
PropsException if no value for key can be found.
See also:
Props::ConstValue::operator int
This overloaded member functions supports, together with the conversion functions for Props::ConstValue, simple retrieval a value corresponding to a given key, as illustrated in the following example.
 props["name"] = "lisa";
 props[0] = "zero";
 props[10] = 11;
 props["age"] = 21;
  
 int age(props["age"]);
 std::string name(props["name"]);
 int n(props[10]);

ConstValue Dv::Util::Props::operator[] unsigned short  key  )  const throw (PropsException)
 

Key-based ``r-value'' access to properties.

Parameters:
key value, can be of a variety of types, it will be converted to std::string.
Returns:
a Props::ConstValue which can be converted to a variety of types.
Exceptions:
PropsException if no value for key can be found.
See also:
Props::ConstValue::operator int
This overloaded member functions supports, together with the conversion functions for Props::ConstValue, simple retrieval a value corresponding to a given key, as illustrated in the following example.
 props["name"] = "lisa";
 props[0] = "zero";
 props[10] = 11;
 props["age"] = 21;
  
 int age(props["age"]);
 std::string name(props["name"]);
 int n(props[10]);

ConstValue Dv::Util::Props::operator[] const double &  key  )  const throw (PropsException)
 

Key-based ``r-value'' access to properties.

Parameters:
key value, can be of a variety of types, it will be converted to std::string.
Returns:
a Props::ConstValue which can be converted to a variety of types.
Exceptions:
PropsException if no value for key can be found.
See also:
Props::ConstValue::operator int
This overloaded member functions supports, together with the conversion functions for Props::ConstValue, simple retrieval a value corresponding to a given key, as illustrated in the following example.
 props["name"] = "lisa";
 props[0] = "zero";
 props[10] = 11;
 props["age"] = 21;
  
 int age(props["age"]);
 std::string name(props["name"]);
 int n(props[10]);

Value Dv::Util::Props::operator[] const std::string &  k  ) 
 

Key-based l-value access to properties.

Parameters:
k key value, can be of a variety of types, it will be converted to std::string.
Returns:
a Props::Value object which can be assigned to.
These member functions support, together with the conversion and assignment functions for Props::Value simple retrieval and assignment of a value corresponding to a given key, as illustrated in the following example.

 props["name"] = "lisa";
 props[0] = "zero";
 props[10] = 11;
 props["age"] = 21;
  
 int age(props["age"]);
 std::string name(props["name"]);
 int n(props[10]);

Value Dv::Util::Props::operator[] int  k  ) 
 

Key-based l-value access to properties.

Parameters:
k key value, can be of a variety of types, it will be converted to std::string.
Returns:
a Props::Value object which can be assigned to.
These member functions support, together with the conversion and assignment functions for Props::Value simple retrieval and assignment of a value corresponding to a given key, as illustrated in the following example.

 props["name"] = "lisa";
 props[0] = "zero";
 props[10] = 11;
 props["age"] = 21;
  
 int age(props["age"]);
 std::string name(props["name"]);
 int n(props[10]);

Value Dv::Util::Props::operator[] unsigned int  k  ) 
 

Key-based l-value access to properties.

Parameters:
k key value, can be of a variety of types, it will be converted to std::string.
Returns:
a Props::Value object which can be assigned to.
These member functions support, together with the conversion and assignment functions for Props::Value simple retrieval and assignment of a value corresponding to a given key, as illustrated in the following example.

 props["name"] = "lisa";
 props[0] = "zero";
 props[10] = 11;
 props["age"] = 21;
  
 int age(props["age"]);
 std::string name(props["name"]);
 int n(props[10]);

Value Dv::Util::Props::operator[] long  k  ) 
 

Key-based l-value access to properties.

Parameters:
k key value, can be of a variety of types, it will be converted to std::string.
Returns:
a Props::Value object which can be assigned to.
These member functions support, together with the conversion and assignment functions for Props::Value simple retrieval and assignment of a value corresponding to a given key, as illustrated in the following example.

 props["name"] = "lisa";
 props[0] = "zero";
 props[10] = 11;
 props["age"] = 21;
  
 int age(props["age"]);
 std::string name(props["name"]);
 int n(props[10]);

Value Dv::Util::Props::operator[] unsigned long  k  ) 
 

Key-based l-value access to properties.

Parameters:
k key value, can be of a variety of types, it will be converted to std::string.
Returns:
a Props::Value object which can be assigned to.
These member functions support, together with the conversion and assignment functions for Props::Value simple retrieval and assignment of a value corresponding to a given key, as illustrated in the following example.

 props["name"] = "lisa";
 props[0] = "zero";
 props[10] = 11;
 props["age"] = 21;
  
 int age(props["age"]);
 std::string name(props["name"]);
 int n(props[10]);

Value Dv::Util::Props::operator[] short  k  ) 
 

Key-based l-value access to properties.

Parameters:
k key value, can be of a variety of types, it will be converted to std::string.
Returns:
a Props::Value object which can be assigned to.
These member functions support, together with the conversion and assignment functions for Props::Value simple retrieval and assignment of a value corresponding to a given key, as illustrated in the following example.

 props["name"] = "lisa";
 props[0] = "zero";
 props[10] = 11;
 props["age"] = 21;
  
 int age(props["age"]);
 std::string name(props["name"]);
 int n(props[10]);

Value Dv::Util::Props::operator[] unsigned short  k  ) 
 

Key-based l-value access to properties.

Parameters:
k key value, can be of a variety of types, it will be converted to std::string.
Returns:
a Props::Value object which can be assigned to.
These member functions support, together with the conversion and assignment functions for Props::Value simple retrieval and assignment of a value corresponding to a given key, as illustrated in the following example.

 props["name"] = "lisa";
 props[0] = "zero";
 props[10] = 11;
 props["age"] = 21;
  
 int age(props["age"]);
 std::string name(props["name"]);
 int n(props[10]);

Value Dv::Util::Props::operator[] const double &  k  ) 
 

Key-based l-value access to properties.

Parameters:
k key value, can be of a variety of types, it will be converted to std::string.
Returns:
a Props::Value object which can be assigned to.
These member functions support, together with the conversion and assignment functions for Props::Value simple retrieval and assignment of a value corresponding to a given key, as illustrated in the following example.

 props["name"] = "lisa";
 props[0] = "zero";
 props[10] = 11;
 props["age"] = 21;
  
 int age(props["age"]);
 std::string name(props["name"]);
 int n(props[10]);

Props& Dv::Util::Props::erase const std::string &  key  ) 
 

Erase any value that is associated with key.

Parameters:
key for which the associated key=value pair will be removed.

Props& Dv::Util::Props::clear  )  [inline]
 

Erase all key = value pairs from the property list.

See also:
Props::erase
Definition at line 394 of file props.h.

References props_.

Props& Dv::Util::Props::add const std::string &  key,
const std::string &  value
 

Add a key = value pair.

Use Props::operator[] for automatic type conversion to std::string.

Parameters:
key std::string.
value std::string.
Returns:
reference to *this.
Warning:
The value added overrides any existing value for key.
See also:
Props::operator[]

Props& Dv::Util::Props::append const std::string &  key,
const std::string &  value,
const std::string &  separator = " "
 

Append to a value associated with a key.

The value, preceded by the separator, is appended to the current value associated with key. If there is no current value, Props::append behaves like Props::add.

Parameters:
key for which the value is to be extended
value to append to the current value of key
separator is appended to (*this)[key] before value, if (*this)[key] was not yet defined.
See also:
Props::add

const std::string* Dv::Util::Props::find const std::string &  key  )  const
 

Try to find value for key, return null if not found.

Parameters:
key to search for.
Returns:
pointer to value associated with key or 0 if none found.

Referenced by operator()(), and operator>>().

const std::string* Dv::Util::Props::operator() const std::string &  key  )  const [inline]
 

Try to find value for key, return null if not found.

Parameters:
key to search for.
See also:
Props::find
Definition at line 441 of file props.h.

References find().

iterator Dv::Util::Props::begin  )  const [inline]
 

Returns:
iterator referring to the first key=value pair.
Definition at line 450 of file props.h.

References iterator, and props_.

iterator Dv::Util::Props::end  )  const [inline]
 

Returns:
iterator referring past the last key=value pair.
Definition at line 454 of file props.h.

References iterator, and props_.

unsigned Dv::Util::Props::size  )  const [inline]
 

Returns:
number of key=value pairs in the property list.
Definition at line 458 of file props.h.

References props_.

std::istream& Dv::Util::Props::read std::istream &  is,
int  n = -1
 

Read n key=value pairs from istream, or until eof if n <0.

Note that the Props object is not cleared before reading the key=value pairs, they are simply added or override existing values.

Parameters:
is stream to read from.
n number of key=value pairs to read. If n<0, reading will continue until eof.
Returns:
reference to is.

ConstValue Dv::Util::Props::operator>> const char *  key  )  const [inline]
 

Return a reference to the key=value pair with the given key.

This is an auxiliary function. It supports expressions such as the following.

  int   value;
  Props props;
  props >> "key" >> value;

Parameters:
key to search for.
Returns:
a ConstValue which can be converted to any type using ConstValue::operator>>.
Warning:
The conversion from the Props::ConstValue will throw an exception if there was no value corresponding to key.
See also:
ConstValue::operator>>
Definition at line 503 of file props.h.

References find().

void Dv::Util::Props::substitute std::istream &  sin,
std::ostream &  sout,
std::string(*  f)(const std::string &) = 0
const throw (std::invalid_argument)
 

Recursively substitute variable occurrences in sin to yield sout.

Parameters:
sin stream that is appended to sout.
sout stream that is appended to.
f function that transforms strings. ${name} in sin is replaced by f((*this)[name]).
Exceptions:
invalid_argument is thrown upon a syntax error.
Sin is a stream, the contents which is appended to sout except for variable occurrences of the form ${key} or {key} which are replaced by f((*this)[key]) and (*this)[key], respectively (the ``$'' sign can be escaped using ``\'').

Undefined (in *this) variables are replaced by the empty std::string.

Example:

 std::string query("select * from");
 props.substitute("person where name = '${name}' and age = %{age}",
                query,MySql::escape);

Syntax:

  • Variables start with ``${'' or ``%{'' except if the ``$'' or ``%'' is preceeded by a backslash (``\'').
  • A backslash is a normal character, except if it is immediately followed by a ``$'' or a ``%'', in which case it is not copied.

void Dv::Util::Props::substitute const std::string &  sin,
std::string &  sout,
std::string(*  f)(const std::string &) = 0
const throw (std::invalid_argument)
 

Recursively substitute variable occurrences in sin to yield sout.

Parameters:
sin std::string that is appended to sout.
sout std::string that is appended to.
f function that transforms strings. ${name} in sin is replaced by f((*this)[name]).
Exceptions:
invalid_argument is thrown upon a syntax error.
Sin is a std::string which is appended to sout except for variable occurrences of the form ${key} or {key} which are replaced by f((*this)[key]) and (*this)[key], respectively (the ``$'' sign can be escaped using ``\'').

Undefined (in *this) variables are replaced by the empty std::string.

Syntax:

  • Variables start with ``${'' or ``%{'' except if the ``$'' or ``%'' is preceeded by a backslash (``\'').
  • A backslash is a normal character, except if it is immediately followed by a ``$'' or a ``%'', in which case it is not copied.

std::string Dv::Util::Props::substitute const std::string &  sin,
std::string(*  f)(const std::string &) = 0
const throw (std::invalid_argument)
 

Same as above but returns result std::string.

Parameters:
sin std::string that is appended to return value.
f function that transforms strings. ${name} in sin is replaced by f((*this)[name]).
Returns:
std::string with subsitutions performed.
Exceptions:
invalid_argument is thrown upon a syntax error.
See also:
Props::substitute

Props& Dv::Util::Props::select const std::string &  scope,
Props target
const
 

Insert selected subkey=value pairs of this object into the target.

The selected pairs are those for which the key starts with the scope std::string followed by '::'. The pairs will be inserted with a key consisting of the remainder of the original key, after removing the scope std::string and '::'.

Example.

 Props  config;
 Props  dbconfig;
 config.select("database",dbconfig);

In the example, if config["database::name"] == "admindb" then dbconfig["name"] == "admindb" after the call to select.

The function returns a reference to its second first argument.

Parameters:
target the Props object the selected pairs will be added to.
scope the selected pairs have ``scope::'' as a key.
Returns:
a reference to target.

Props& Dv::Util::Props::merge const Props source,
const std::string &  scope = ""
throw (PropsException)
 

Load all key-value pairs from another props object under a certain scope.

All key-value pairs from source will be added to *this, where the key will be prefixed with scope:: if the size of scope is not zero.

Example usage:

 Props  dbconfig;
 Props  config;
 config.merge(dbconfig,"database");

If dbconfig["name"]=="admindb" then config["database::name"]=="admindb" after the merge.

Parameters:
source the Props object from which key=value pairs will be copied.
scope only key=value pairs where key starts with scope:: will be copied.
Returns:
reference to *this.
Warning:
&source must be different from this.
See also:
Dv::Util::Props::select

bool Dv::Util::Props::operator== const Props  )  const
 

Compare two Props objects.

bool Dv::Util::Props::operator!= const Props p  )  const [inline]
 

Definition at line 634 of file props.h.

std::ostream& Dv::Util::Props::send std::ostream &  os  )  const
 

Send a props object over a stream.

The difference with e.g.

 ostream& operator<<(ostream&,const Props::Value&);
is that Props::send also works over network connections where the end of the input is not indicated by EOF. An object sent by Props::send() should be received by Props::receive().
Parameters:
os stream to write Props object to.
See also:
Dv::Util::Props::receive

std::istream& Dv::Util::Props::receive std::istream &  is  ) 
 

Receive a props object from a stream.

The difference with e.g.

 Props(istream&); 
is that Props::receive also works over network connections where the end of the input is not indicated by EOF. An object received by Props::receive() should have been sent by Props::send().

Parameters:
is stream from which to read the Props object.
Warning:
Note that the object is not cleared before receiving new key=value pairs.
See also:
Dv::Util::Props::send

Props& Dv::Util::Props::operator= const Props props  )  throw (PropsException)
 

Assignment allowed.

std::string* Dv::Util::Props::found const std::string &  key  )  [private]
 


Friends And Related Function Documentation

std::ostream& operator<< std::ostream &  ,
const Props
[friend]
 

Write the Props object to the stream, in the format described above.

std::istream& operator>> std::istream &  is,
Props props
[friend]
 

Read key-value pairs from istream until the end of the stream is reached or a syntax error occurs.

Parameters:
is stream to read from.
props property object to update.
Returns:
reference to is.
Warning:
Existing key values will be overriden.
See also:
Props::read


Member Data Documentation

propmap Dv::Util::Props::props_ [private]
 

Definition at line 683 of file props.h.

Referenced by begin(), clear(), end(), and size().


The documentation for this class was generated from the following file:
dvutil-0.13.15 [30 December, 2004]