---

Dv::Util::Env Class Reference

An Env object represents an extended ``environment''. More...

#include <env.h>

List of all members.

Public Types
enum	Type { NIL, STRING, MAP, ARRAY }
	Type of Box. More...
Public Methods
	Env ()
	Create a NIL environment.
	Env (const Env &e)
	Create a deep copy of its argument.
	Env (std::istream &is) throw (Exception)
	Convenience constructor.
	Env (const std::string &fn) throw (Exception)
	Convenience constructor.
	~Env ()
	Destructor.
const std::string &	svalue () const throw (Exception)
	Return string from an underlying SBox.
std::string &	slvalue () throw (Exception)
	Return non-const reference to string from an underlying SBox.
template<typename T>	operator T () const throw (Exception)
	Convert to any non-pointer type T for which operator>>(std::istream&,T&) is defined.
template<typename T>	operator T * () const throw (Exception)
	We refuse to convert to T*, except if T = const char.
	operator const char * () const throw (Exception)
	The exception about converting to pointers.
	operator const std::string & () const throw (Exception)
	Attempt to convert an Env to a string.
	operator std::string & () throw (Exception)
	Attempt to convert an Env to a non-const reference to a string.
bool	defined () const
	Check whether this environment has an associated Box.
Type	type () const
	Return type of underlying box.
bool	is_string () const
	Is this environment associated with a string box?
bool	is_array () const
	Is this environment associated with an array box?
bool	is_map () const
	Is this environment associated with a map box?
Env &	operator[] (int i) throw (Exception)
	Return lvalue environment associated with index i.
const Env &	operator() (int i) const throw (Exception)
	Return (const reference to) environment associated with index i.
Env &	operator[] (const std::string &s) throw (Exception)
	Return lvalue environment associated with key string s.
const Env &	operator() (const std::string &s) const throw (Exception)
	Return environment associated with key string s.
template<typename T> Env &	operator= (const T &t)
	Assign a T object to en environment.
Env &	operator= (const std::string &s)
	Specialization of assignment for string.
Env &	operator= (const Env &e)
	Specialization of assignment for Env.
Env &	clear ()
	Clear an environment.
Env &	merge (const Env &e)
	Merge an environment into the current one.
size_t	size () const
	Return number of top-level entries in underlying structure.
template<typename T> bool	operator== (const T &t) const
	Compare after converting *this to T.
bool	operator== (const std::string &s) const
	Specialization of operator==(const T &) for string.
bool	operator== (const Env &e) const
	Specialization of operator==(const T &) for Env.
template<typename T> bool	operator!= (const T &t) const
const Env &	substitute (std::ostream &os, std::istream &is) const throw (Exception)
	Copy is to os, recursively replacing variables by their value in *this.
const Env &	substitute (std::string &out, const std::string &ins) const throw (Exception)
	Copy ins to out, recursively replacing variables by their value in *this.
std::ostream &	print (std::ostream &os, const std::string &prefix="") const
	Auxiliary function for operator<<.
Env &	read_key (const std::string &s) throw (Exception)
const Env *	access (const std::string &key) const
	Return child environment corresponding with key.
Env &	read (std::istream &is) throw (Dv::Util::Env::Exception)
	Merge environment data from is with this environment.
iterator	begin () const
iterator	end () const
Static Public Methods
const char *	type_s (Type t)
const Env &	nil ()
	Return reference to a fixed constant environment without a box.
bool	explode (const std::string &index, std::vector< std::string > &keys)
	Decompose index of form "a::b::c" into vector [a,b,c].

---

Detailed Description

An Env object represents an extended ``environment''.

Here, ``extended environment'' means either a string or a finite mapping from string (or int) to string (or other environments). An Env object e corresponds to either

• a string
• a map from strings to environments
• a vector of environments

Access is supported using conversions and index operators:

 Env es, em, ev, e;
 es = "value"; // a string environment
 em["key"] = "value"; // a string environment
 ev[1] = "value";
 e["es"] = es; // nesting
 e["key"] = em;
 e["vec"] = ev;
 cout << e["vec"][1]; // will print "value"

Note however, that en environment is one of the above, combinations are not allowed.

 Env e;
 e["key"] = "value";
 e[1] = "error"; // will throw exception

For maps and vectors, read-only access is supported through operator().

 cout << e("key"); // throw exception if not defined
 e("key") = "value"; // will not compile

In general the following expressions are supported (we only show three occurrences of [i] or (i) but any number of them is allowed):

 e[i][i][i]
 e[i][i][i] = t
 lt = e(i)(i)(i)
 if (e(i)(i)(i).defined()) ...
 if (e(i)(i)(i).is_array()) ...
 if (e(i)(i)(i).is_map()) ...
 if (e(i)(i)(i).is_string()) ...

where

• i is either a string or an integer
• t is any value of a type T for which Dv::Util::tostring(t) is defined
• lt is an lvalue of type T for which Dv::Util::fromstring(t, s) is defined

Internally, an Env object is just a pointer to a Box.

See also:

Box

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

 |database::name=my-database
 |query=select name, semester
 |>from course
 |answer::0::field-1=f1
 |answer::1::field-2=f2
 |host=mainserver
 |# a comment
 |age=99

The format of a single entry is

 entry = index '=' value \n

where value is any string which is copied literally except fo newline (
) characters that are translated as "
>".

Note that

• Empty lines (with only white space chars) are ignored.
• Lines starting with '#' are ignored (useful for comments).
• An index has the sytax

   index = simple-index
           | index '::' simple-index
           ;
   simple-index = name
                | number
                  ;
   name = [a-zA-Z_-][a-zA-Z_-0-9]*
   number = [0-9]+
  

Warning:

The actual input function operator>>(istream&,Env&) is much more liberal than the above specification, but this may change in future versions.

---

Member Enumeration Documentation

enum Dv::Util::Env::Type

Type of Box. Enumeration values: NIL  corresponds to ``no box'' STRING  box contains a string MAP  box contains key_string -> box map ARRAY  box contains [0..n[ -> box map

---

Constructor & Destructor Documentation

Dv::Util::Env::Env (    )

Create a NIL environment.

Dv::Util::Env::Env (  const Env &    e )

Create a deep copy of its argument. Parameters: e  environment to be copied.

Dv::Util::Env::Env (  std::istream &    is )  throw (Exception)

Convenience constructor. Read a fresh environment from a stream. Parameters: is  stream from which environment will be read. Exceptions: Exception  if bad syntax.

Dv::Util::Env::Env (  const std::string &    fn )  throw (Exception)

Convenience constructor. Read a fresh environment from a file stream. Parameters: fn  name of file containing environment. Exceptions: Exception  if bad syntax.

Dv::Util::Env::~Env (    )

Destructor.

---

Member Function Documentation

const std::string& Dv::Util::Env::svalue (    )  const throw (Exception)

Return string from an underlying SBox. Returns: string associated with SBox. Exceptions: Exception  if the box underlying the environment is not an SBox.

std::string& Dv::Util::Env::slvalue (    )  throw (Exception)

Return non-const reference to string from an underlying SBox. If there is no underlying box, an SBox will be created. Returns: non-const reference string associated with SBox. Exceptions: Exception  if the box underlying the environment is not an SBox or NIL.

template<typename T> Dv::Util::Env::operator T (    )  const throw (Exception) [inline]

Convert to any non-pointer type T for which operator>>(std::istream&,T&) is defined. Returns: object of type T Exceptions: Exception  if svalue() cannot be converted to T object.

template<typename T> Dv::Util::Env::operator T * (    )  const throw (Exception) [inline]

We refuse to convert to T*, except if T = const char. Exceptions: Exception  always thrown.

Dv::Util::Env::operator const char * (    )  const throw (Exception) [inline]

The exception about converting to pointers.

Dv::Util::Env::operator const std::string & (    )  const throw (Exception) [inline]

Attempt to convert an Env to a string. Calls Env::Slvalue(). Returns: string of associated SBox. Exceptions: Exception  if underlying box is not an SBox. See also: Env::slvalue()

Dv::Util::Env::operator std::string & (    )  throw (Exception) [inline]

Attempt to convert an Env to a non-const reference to a string. Calls Env::Slvalue(). Returns: non-const reference to string of associated SBox. Exceptions: Exception  if underlying box is not an SBox. See also: Env::slvalue()

bool Dv::Util::Env::defined (    )  const [inline]

Check whether this environment has an associated Box. Returns: true iff there is an underlying box.

Type Dv::Util::Env::type (    )  const

Return type of underlying box. Returns: type of underlying box, NIL if no box is associated with this environment.

const char* Dv::Util::Env::type_s (  Type    t )  [static]

bool Dv::Util::Env::is_string (    )  const [inline]

Is this environment associated with a string box? Returns: true iff underlying box is SBox

bool Dv::Util::Env::is_array (    )  const [inline]

Is this environment associated with an array box? Returns: true iff underlying box is ABox

bool Dv::Util::Env::is_map (    )  const [inline]

Is this environment associated with a map box? Returns: true iff underlying box is MBox

const Env& Dv::Util::Env::nil (    )  [static]

Return reference to a fixed constant environment without a box. Returns: reference to an environment without a box.

Env& Dv::Util::Env::operator[] (  int    i )  throw (Exception)

Return lvalue environment associated with index i. If the there is no box, an ABox will be created. Returns: lvalue environment associated with index i. Exceptions: Exception  is underlying box is not an ABox or nil.

const Env& Dv::Util::Env::operator() (  int    i )  const throw (Exception)

Return (const reference to) environment associated with index i. Returns: (const reference to) environment associated with index i. Exceptions: Exception  is underlying box is not an ABox.

Env& Dv::Util::Env::operator[] (  const std::string &    s )  throw (Exception)

Return lvalue environment associated with key string s. If the there is no box, an MBox will be created. Returns: reference to environment associated with key s. Exceptions: Exception  is underlying box is not an MBox or nil.

const Env& Dv::Util::Env::operator() (  const std::string &    s )  const throw (Exception)

Return environment associated with key string s. Returns: (const reference to) environment associated with key s. Exceptions: Exception  is underlying box is not an MBox.

template<typename T> Env& Dv::Util::Env::operator= (  const T &    t )  [inline]

Assign a T object to en environment. Parameters: t  object of type T. Returns: reference to *this. See also: Env::slvalue() \warnning is a no-op on Env::nil().

Env& Dv::Util::Env::operator= (  const std::string &    s )

Specialization of assignment for string. Parameters: s  string to assign. Returns: reference to *this. See also: Env::slvalue() \warnning is a no-op on Env::nil().

Env& Dv::Util::Env::operator= (  const Env &    e )

Specialization of assignment for Env. Parameters: e  environment to assign. Returns: reference to *this. See also: Env::merge() \warnning is a no-op on Env::nil().

Env& Dv::Util::Env::clear (    )  [inline]

Clear an environment. Returns: reference to *this.

Env& Dv::Util::Env::merge (  const Env &    e )

Merge an environment into the current one. The merging proceeds as follows: if the box underlying the target is nil, the source is simply copied. otherwise, if the boxes underlying the source and target are of different * non-nil type, nothing is done. otherwise, if the target and source box is of type string, nothing is done, otherwise, if the target and source box are of type array, the target values are appended to the source values. E.g. if the targets has i entries, e[0..] will be put in (*this)[i..] otherwise, if the target and source box are of type map, (*this)[key]=e[key] iff only if (*this)[key] is undefined. Parameters: e  environment to copy to *this. Returns: reference to *this.

size_t Dv::Util::Env::size (    )  const

Return number of top-level entries in underlying structure. Returns: nr of entries in MAP or ARRAY, 1 if STRING, 0 if NIL

template<typename T> bool Dv::Util::Env::operator== (  const T &    t )  const [inline]

Compare after converting *this to T. Parameters: t  object to compare with. Returns: true iff static_cast<T>(*this)==t. See also: Env::operator T()

bool Dv::Util::Env::operator== (  const std::string &    s )  const [inline]

Specialization of operator==(const T &) for string. Parameters: s  string to compare with. Returns: true iff svalue()==s. See also: Env::svalue()

bool Dv::Util::Env::operator== (  const Env &    e )  const

Specialization of operator==(const T &) for Env. Does a ``deep'' comparison. Parameters: e  environment to compare with. Returns: true iff all components of the environments are equal.

template<typename T> bool Dv::Util::Env::operator!= (  const T &    t )  const [inline]

const Env& Dv::Util::Env::substitute (  std::ostream &    os, std::istream &    is )  const throw (Exception)

Copy is to os, recursively replacing variables by their value in *this. A variable reference is of the form like ${k} ('$' can be escaped by preceding it with '\') where k is of the form i [ :: i ]+ where each i is either an integer, or a string not containing any of the special character sequences '}', '*' or '::', or the special character '*' which stands for ``all integer indices''. If '*' occurs, it must be the last i in k. The following illustrates its use ${i::*}{blabla ${a::b} more text} In the above code, if ${i} is an array, then the output will contain the result of blabla ${i::0::a::b} more text .. blabla ${i::n::a::b} more text where 0..n are the valid indexes in env(i). Parameters: os  output stream to which text will be written. is  input stream from which text to be transformed will be read. Returns: a reference to *this. Exceptions: Exception  if there is a syntax error. An illegal access on *this will be caught. Warning: undefined variables will be left untouched. This, way one can do another substitution on the result, from a differen environment.

const Env& Dv::Util::Env::substitute (  std::string &    out, const std::string &    ins )  const throw (Exception)

Copy ins to out, recursively replacing variables by their value in *this. A variable reference is of the form like ${k} ('$' can be escaped by preceding it with '\') where k is of the form i [ :: i ]+ where each i is either an integer, or a string not containing any of the special character sequences '}', '*' or '::', or the special character '*' which stands for ``all integer indices''. If '*' occurs, it must be the last i in k. The following illustrates its use ${i::*}{blabla ${a::b} more text} In the above code, if ${i} is an array, then the output will contain the result of blabla ${i::0::a::b} more text .. blabla ${i::n::a::b} more text where 0..n are the valid indexes in env(i). Parameters: out  output string to which text will be written. ins  input string from which text to be transformed will be read. Returns: a reference to *this. Exceptions: Exception  if there is a syntax error. An illegal access on *this will be caught. Warning: undefined variables will be left untouched. This, way one can do another substitution on the result, from a differen environment.

std::ostream& Dv::Util::Env::print (  std::ostream &    os, const std::string &    prefix = "" )  const

Auxiliary function for operator<<. Print *this in the format prefix key=value .. Parameters: os  stream to print to. prefix  will be prefixed before each key

Env& Dv::Util::Env::read_key (  const std::string &    s )  throw (Exception)

bool Dv::Util::Env::explode (  const std::string &    index, std::vector< std::string > &    keys )  [static]

Decompose index of form "a::b::c" into vector [a,b,c]. Parameters: index  string to decompose keys  components will be appended to this vector. Returns: true iff last component equals "*" Warning: Empty components are ignored, e.g. a::::b will yield [a,b].

const Env* Dv::Util::Env::access (  const std::string &    key )  const

Return child environment corresponding with key. Parameters: key  int of string to use as key in *this. Returns: e(key) if it exists or 0.

Env& Dv::Util::Env::read (  std::istream &    is )  throw (Dv::Util::Env::Exception)

Merge environment data from is with this environment. Environments written with operator<<(ostream&,const Env&) can be read with this function. Parameters: is  stream to read environment data from. Exceptions: Exception  , e.g. due to incompatibility of data with e or due to syntax error. See also: operator<<(ostream&,const Env&);

iterator Dv::Util::Env::begin (    )  const

iterator Dv::Util::Env::end (    )  const

---

The documentation for this class was generated from the following file:

• env.h

---

dvenv-0.2.2

[20 October, 2002]