S3FC project page S3FC home page
Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members   Related Pages  

s3_config_node Class Reference

This provides an abstraction of a configuration node. More...

#include <s3_config_node.h>

Collaboration diagram for s3_config_node:

Collaboration graph
[legend]
List of all members.

Public Types

typedef std::map< std::string,
std::string > 		map_type

Public Methods

 s3_config_node (const std::string &n_name="", const std::string &n_value="", const s3_config_node *n_parent=&empty_node, const std::map< std::string, std::string > &n_attributes=map_type(), const std::vector< s3_config_node > &n_children=std::vector< s3_config_node >())
 Initialising constructor: create with supplied values. More...

 s3_config_node (const s3_config_node &src)
 Copy constructor: construct as a deep copy of the argument s3_config_node. More...

s3_config_node & operator= (const s3_config_node &src)
 Copy assignment operator. More...

bool empty () const
 Test whether this is an empty node. More...

bool is_rootnode () const
 Return true if this node is a rootnode (a node with no parent). More...

s3_config_node *& parent ()
 Return a reference to the pointer to the parent node. More...

std::string & name ()
 Return a reference to the node name. More...

std::string & value ()
 Return a reference to the node value. More...

std::map< std::string, std::string > & attributes ()
 Return a reference to the attributes. More...

std::vector< s3_config_node > & children ()
 Return a reference to the list of children. More...

s3_config_node * insert_child (const s3_config_node &child=empty_node, const s3_config_node &before=at_end)
 Add a child before the specified child. More...

void remove_child (const s3_config_node &child)
 Remove the specified child from the list of children. More...

const s3_config_node & get_parent () const
 Return a const reference to the parent node. More...

s3_config_node & get_parent ()
 Return a reference to the parent node. More...

void set_parent (s3_config_node &n_parent)
 Set the parent of this node. More...

const std::string & get_name () const
 Return the name of the node. More...

void set_name (const std::string &n_name)
 Set the name of the node. More...

const std::string & get_value () const
 Return raw character data stored in the node. More...

void set_value (const std::string &n_value)
 Set the value of the node. More...

template<typename T> T get_value () const
 Return a copy of the raw character data stored in the node, converted to type T. More...

template<typename T> void set_value (const T &n_value)
 Set the value of the node. More...

const std::map< std::string,
std::string > & 		get_attributes () const
 Return a const reference to the map of all attribute name/value pairs, keyed on name. More...

std::map< std::string, std::string > & get_attributes ()
 Return a reference to the map of all attribute name/value pairs, keyed on name. More...

unsigned int get_num_children () const
 Return the number of child nodes. More...

const s3_config_node & get_child (unsigned int i) const
 Return a const reference to the i 'th child. More...

s3_config_node & get_child (unsigned int i)
 Return a reference to the i 'th child. More...

const std::vector< const s3_config_node * > get_children (const std::string &name_filter="") const
 Return a const list of pointers to const child nodes. More...

std::vector< s3_config_node * > get_children (const std::string &name_filter="")
 Return a list of pointers to child nodes. More...

bool node_exists (const std::string &path) const
 Return a flag indicating whether a specified node exists. More...

const s3_config_node & get_node_at (const std::string &path) const
 Return a const reference to an s3_config_node which resides at a specified position in the tree hierarchy. More...

s3_config_node & get_node_at (const std::string &path)
 Return a reference to an s3_config_node which resides at a specified position in the tree hierarchy. More...

template<typename T> T get_value_at (const std::string &path) const
 Return a copy of the raw character data stored in the node which resides at a specified position in the tree hierarchy, converted to the specified type. More...

template<typename T> T get_attribute_at (const std::string &attr_name) const
 Return a copy of the data stored in the attribute with the given name for the current node, converted to the specified type. More...


Static Public Attributes

s3_config_node empty_node
 Static empty node used to return ref to empty node. More...

s3_config_node at_end
 Static empty node used to indicate insertion of child at end. More...


Protected Methods

std::vector< s3_config_node
>::iterator 		find_child (const s3_config_node &child)
 Search through a_children for the specified child, child and return iterator pointing to it. More...

const s3_config_node * gna_helper (const std::string &path) const

Protected Attributes

std::string a_name
 Name. More...

std::string a_value
 Value. More...

s3_config_node * a_parent
 Parent. More...

std::map< std::string, std::string > a_attributes
 Attributes. More...

std::vector< s3_config_node > a_children
 Children. More...

Detailed Description

This provides an abstraction of a configuration node.

Nodes are structured in a tree and each node has a name which need not be unique. Nodes can optionally contain one or more of the following:

Attributes are simply a collection of name/value string pairs. All data are stored as strings. A node has value, which is a string that, which may include data describing its children, its attributes or just raw character data.

The following tree operations are supported:

An empty node can be constructed and a method is provided to test whether a node is an empty node [empty()]. This allows a "not found" value to be returned by some calls.

A node can be (copy) constructed from another node, in which case the contents of the entire source node (name, value, attributes and children) is recursively deep copied into the new node. The source node is left unchanged by this maneuver. The new node is created as an orphaned node (one containing no parent).

A node can be copy assigned from another node. The behaviour is similar to copy construction in that the entire source node (name, value, attributes and children) is recursively deep copied into the existing node. The children that the destination node has at the invocation of the assignment are first removed (and therefore deallocated to disappear forever as a node owns its children), before the recusive deep copy takes place. The parent of the destination node is left unchanged and copy assignment therefore does not change the location of a node in a tree.

A node owns its children and they are therefore deallocated when they are removed from a node, using remove_child().

Author:
Gerhard Esterhuizen <gesterhuizen@stonethree.com>
Date:
06/06/2001

Definition at line 89 of file s3_config_node.h.

Member Typedef Documentation

typedef std::map<std::string, std::string> s3_config_node::map_type
 

Definition at line 126 of file s3_config_node.h.

Constructor & Destructor Documentation

s3_config_node::s3_config_node (  const std::string &    n_name = "",
const std::string &    n_value = "",
const s3_config_node *    n_parent = &empty_node,
const std::map< std::string, std::string > &    n_attributes = map_type(),
const std::vector< s3_config_node > &    n_children = std::vector< s3_config_node >()
) 
 

Initialising constructor: create with supplied values.

Parameters:
const  std::string& n_name The name of the node.
const  std::string& n_value The value of the node.
const  s3_config_node* n_parent A pointer to the parent node.
const  std::map<std::string,std::string>& n_attributes A reference to a map of all the attributes that you would like to have for the node.
const  std::vector<s3_config_node>& n_children, A reference to a vector of s3_config_nodes that consists of all the children.

Definition at line 53 of file s3_config_node.cc.

References a_children.

s3_config_node::s3_config_node (  const s3_config_node &    src ) 
 

Copy constructor: construct as a deep copy of the argument s3_config_node.

The new instance has NO parent and all the immediate children of it has itself as the parent. This is applied recursively. Therefore, copy constructing a node from another one, creates a completely independent copy of the tree rooted at src, with the newly contructed node as the parent of the new tree.

Note that this affects the way that recursive calls to traverse the tree are made. You must pass a reference to a node in order not to orphan it and thus mess up you traverse. The following code fragment demonstrates a function that locates all nodes in the tree with a particular name 


      void find(const s3_config_node& node,
                            const string& pattern,
                            s3_config_node_list& nl)
      {
         if (node.get_name() == pattern) // Found a match
         {
            nl.push_back(node);
         }

         for (unsigned int i = 0; i < node.get_num_children(); i++)
         {
            find(node.get_child(i), pattern, nl);
         }
      }

Note that the s3_config_node is passed by reference to avoid the copy constructor being called when the function recurses, thus losing its parents.

Parameters:
src  Instance to copy.

Definition at line 74 of file s3_config_node.cc.

References a_children.

Member Function Documentation

std::map< std::string, std::string > & s3_config_node::attributes (    ) 
 

Return a reference to the attributes.

Note: This is deprecated, don't use.

Definition at line 137 of file s3_config_node.cc.

References a_attributes.

std::vector< s3_config_node > & s3_config_node::children (    ) 
 

Return a reference to the list of children.

Note: This is deprecated, don't use.

Definition at line 143 of file s3_config_node.cc.

References a_children.

bool s3_config_node::empty (    )  const
 

Test whether this is an empty node.

Return values:
true  This an empty node.
false  This is not an empty node.

Definition at line 107 of file s3_config_node.cc.

References empty_node.

std::vector< s3_config_node >::iterator s3_config_node::find_child (  const s3_config_node &    child )  [protected]
 

Search through a_children for the specified child, child and return iterator pointing to it.

If it is not found, the past-end iterator is returned.

Returns:
Iterator to child or a_children.end() if not found.

Definition at line 192 of file s3_config_node.cc.

References a_children.

Referenced by insert_child, and remove_child.

template<typename T>
T s3_config_node::get_attribute_at (  const std::string &    attr_name )  const
 

Return a copy of the data stored in the attribute with the given name for the current node, converted to the specified type.

Returns:
The data of the requested attribute. If this attribute is not present, the default object T() is returned.

Definition at line 55 of file s3_config_node.tcc.

References a_attributes.

std::map< std::string, std::string > & s3_config_node::get_attributes (    ) 
 

Return a reference to the map of all attribute name/value pairs, keyed on name.

Returns:
Map of attribute name/value pairs.

Definition at line 261 of file s3_config_node.cc.

References a_attributes.

const std::map< std::string, std::string > & s3_config_node::get_attributes (    )  const
 

Return a const reference to the map of all attribute name/value pairs, keyed on name.

Returns:
Map of attribute name/value pairs.

Definition at line 255 of file s3_config_node.cc.

References a_attributes.

Referenced by s3_xml_config::write_node.

s3_config_node & s3_config_node::get_child (  unsigned int    i ) 
 

Return a reference to the i 'th child.

Parameters:
i  Index of the child to return.
Precondition:
i < get_num_children()

Definition at line 285 of file s3_config_node.cc.

const s3_config_node & s3_config_node::get_child (  unsigned int    i )  const
 

Return a const reference to the i 'th child.

Parameters:
i  Index of the child to return.
Precondition:
i < get_num_children()

Definition at line 273 of file s3_config_node.cc.

References a_children, and get_num_children.

Referenced by s3_xml_config::write_node.

std::vector< s3_config_node * > s3_config_node::get_children (  const std::string &    name_filter = "" ) 
 

Return a list of pointers to child nodes.

An optional argument specifies a name filter to apply: only children with matching names are returned in the list.

Parameters:
name_filter  String indicating the name that a child must have in order to be included. An empty string implies no filtering, i.e. all children are returned (optional - default: empty string)
Returns:
List of children with names matching name_filter.

Definition at line 311 of file s3_config_node.cc.

const std::vector< const s3_config_node * > s3_config_node::get_children (  const std::string &    name_filter = "" )  const
 

Return a const list of pointers to const child nodes.

An optional argument specifies a name filter to apply: only children with matching names are returned in the list.

Parameters:
name_filter  String indicating the name that a child must have in order to be included. An empty string implies no filtering, i.e. all children are returned (optional - default: empty string)
Returns:
List of children with names matching name_filter.

Definition at line 293 of file s3_config_node.cc.

References a_children.

Referenced by gna_helper.

const std::string & s3_config_node::get_name (    )  const
 

Return the name of the node.

Returns:
a_name.

Definition at line 231 of file s3_config_node.cc.

References a_name.

Referenced by s3_xml_config::write_node.

s3_config_node & s3_config_node::get_node_at (  const std::string &    path ) 
 

Return a reference to an s3_config_node which resides at a specified position in the tree hierarchy.

The path to the requested node is specified in the same way as for node_exist().

Parameters:
path  A text string describing the path to a specific node in the config tree.
Returns:
The requested s3_config_node (deep copy).
Precondition:
node_exists(path) == true.

Definition at line 341 of file s3_config_node.cc.

const s3_config_node & s3_config_node::get_node_at (  const std::string &    path )  const
 

Return a const reference to an s3_config_node which resides at a specified position in the tree hierarchy.

The path to the requested node is specified in the same way as for node_exist().

Parameters:
path  A text string describing the path to a specific node in the config tree.
Returns:
The requested s3_config_node (deep copy).
Precondition:
node_exists(path) == true.

Definition at line 327 of file s3_config_node.cc.

References gna_helper.

Referenced by get_value_at.

unsigned int s3_config_node::get_num_children (    )  const
 

Return the number of child nodes.

Returns:
Number of child nodes.

Definition at line 267 of file s3_config_node.cc.

References a_children.

Referenced by get_child, and s3_xml_config::write_node.

s3_config_node & s3_config_node::get_parent (    ) 
 

Return a reference to the parent node.

Returns:
*a_parent.

Definition at line 219 of file s3_config_node.cc.

References a_parent.

const s3_config_node & s3_config_node::get_parent (    )  const
 

Return a const reference to the parent node.

Returns:
*a_parent.

Definition at line 213 of file s3_config_node.cc.

References a_parent.

template<typename T>
T s3_config_node::get_value (    )  const
 

Return a copy of the raw character data stored in the node, converted to type T.

s3_conversion::from_string() is used to perform the conversion.

This call normally only makes sense if the node does not contain any children, as an implementation may return data representing child nodes with this call.

Returns:
Node data formatted according to s3_conversion::from_string()

T s3_config_node::get_value (    )  const
 

Return raw character data stored in the node.

This normally only makes sense if the node does not contain any children, as an implementation may return data representing child nodes with this call. This is used to extract data from a node with no children, storing character data.

Returns:
Node data string.

Definition at line 243 of file s3_config_node.cc.

References a_value.

Referenced by get_value_at, and s3_xml_config::write_node.

template<typename T>
T s3_config_node::get_value_at (  const std::string &    path )  const
 

Return a copy of the raw character data stored in the node which resides at a specified position in the tree hierarchy, converted to the specified type.

This is equivalent to calling get_node_at(path).get_value<T>().

Returns:
The data of the requested s3_config_node, obtained using get_value<T>().
Precondition:
node_exists(path) == true.

Definition at line 46 of file s3_config_node.tcc.

References get_node_at, get_value, and value.

const s3_config_node * s3_config_node::gna_helper (  const std::string &    path )  const [protected]
 

Definition at line 348 of file s3_config_node.cc.

References get_children, and name.

Referenced by get_node_at, and node_exists.

s3_config_node * s3_config_node::insert_child (  const s3_config_node &    child = empty_node,
const s3_config_node &    before = at_end
) 
 

Add a child before the specified child.

Parameters:
child  Node to add to children list.
before  Reference to child before which child should be added: it It is an optional argument and child is added at the end if omitted.
Precondition:
find_child(before) != a_children.end()
Returns:
A pointer to the newly created child node.

Definition at line 149 of file s3_config_node.cc.

References a_children, at_end, and find_child.

bool s3_config_node::is_rootnode (    )  const
 

Return true if this node is a rootnode (a node with no parent).

Return values:
true  This is a rootnode.
false  This is not a rootnode.

Definition at line 113 of file s3_config_node.cc.

References a_parent, and empty_node.

std::string & s3_config_node::name (    ) 
 

Return a reference to the node name.

Definition at line 125 of file s3_config_node.cc.

References a_name.

Referenced by gna_helper.

bool s3_config_node::node_exists (  const std::string &    path )  const
 

Return a flag indicating whether a specified node exists.

The node is specified as a path string with format: "child1:child2:node". In the case of multiple children with the same name, an index may be given, e.g. "child1#1:child2#3:node".

Return values:
c  true The node specified by path exists.
c  false The node specified by path does not exist.

Definition at line 319 of file s3_config_node.cc.

References gna_helper.

s3_config_node & s3_config_node::operator= (  const s3_config_node &    src ) 
 

Copy assignment operator.

Recursively copy the contents of the source node (and all its children) into this node. The following steps are performed:

  • Remove all the children of this node, using remove_children()
  • Copy the name, value and attribute from the source node, using copy assignment.
  • Add each child node from the source to this node, using add_child(). Above copies are all deep. This node retains its original parent node and its position in a tree is threrefore unchanged.
Parameters:
src  Source node.
Returns:
*this

Definition at line 90 of file s3_config_node.cc.

References a_attributes, a_children, a_name, a_parent, a_value, and empty_node.

s3_config_node *& s3_config_node::parent (    ) 
 

Return a reference to the pointer to the parent node.

Returns:

Definition at line 119 of file s3_config_node.cc.

References a_parent.

void s3_config_node::remove_child (  const s3_config_node &    child ) 
 

Remove the specified child from the list of children.

Parameters:
child  Reference to child which should be removed.
Precondition:
find_child(child) != a_children.end()

Definition at line 179 of file s3_config_node.cc.

References a_children, and find_child.

void s3_config_node::set_name (  const std::string &    n_name ) 
 

Set the name of the node.

Parameters:
n_name  New name.

Definition at line 237 of file s3_config_node.cc.

References a_name.

void s3_config_node::set_parent (  s3_config_node &    n_parent ) 
 

Set the parent of this node.

Parameters:
n_parent  New parent

Definition at line 225 of file s3_config_node.cc.

References a_parent.

template<typename T>
void s3_config_node::set_value (  const T &    n_value ) 
 

Set the value of the node.

Parameters:
n_value  New value.

Definition at line 39 of file s3_config_node.tcc.

References a_value.

void s3_config_node::set_value (  const std::string &    n_value ) 
 

Set the value of the node.

Parameters:
n_value  New value.

Definition at line 249 of file s3_config_node.cc.

References a_value.

std::string & s3_config_node::value (    ) 
 

Return a reference to the node value.

Definition at line 131 of file s3_config_node.cc.

References a_value.

Referenced by get_value_at.

Member Data Documentation

std::map<std::string, std::string> s3_config_node::a_attributes [protected]
 

Attributes.

Definition at line 119 of file s3_config_node.h.

Referenced by attributes, get_attribute_at, get_attributes, and operator=.

std::vector<s3_config_node> s3_config_node::a_children [protected]
 

Children.

Definition at line 123 of file s3_config_node.h.

Referenced by children, find_child, get_child, get_children, get_num_children, insert_child, operator=, remove_child, and s3_config_node.

std::string s3_config_node::a_name [protected]
 

Name.

Definition at line 107 of file s3_config_node.h.

Referenced by get_name, name, operator=, and set_name.

s3_config_node* s3_config_node::a_parent [protected]
 

Parent.

Definition at line 115 of file s3_config_node.h.

Referenced by get_parent, is_rootnode, operator=, parent, and set_parent.

std::string s3_config_node::a_value [protected]
 

Value.

Definition at line 111 of file s3_config_node.h.

Referenced by get_value, operator=, set_value, and value.

s3_config_node s3_config_node::at_end [static]
 

Static empty node used to indicate insertion of child at end.

Definition at line 36 of file s3_config_node.cc.

Referenced by insert_child.

s3_config_node s3_config_node::empty_node [static]
 

Static empty node used to return ref to empty node.

Definition at line 35 of file s3_config_node.cc.

Referenced by empty, is_rootnode, and operator=.

The documentation for this class was generated from the following files:
Send comments to: s3fc@stonethree.com SourceForge Logo