node.h

Go to the documentation of this file.

#ifndef DVXML_NODE_H
#define DVXML_NODE_H
// $Id: node.h,v 1.31 2008/01/07 14:45:20 dvermeir Exp $
#include <stdexcept>
#include <iostream>
#include <iterator>
#include <dvutil/tostring.h>
#include <xmlwrapp/xmlwrapp.h>
#include <dvxml/tohtml.h>
#include <dvxml/exception.h>
#include <dvxml/noconst.h>
#include <dvxml/dv_forward_iterator.h>

namespace Dv {
  namespace Xml {

    /** Convenience interface to xml::node.
     * There are two classes:
     *  - Dv::Xml::Node which is publicly derived from xml::node. All it
     *  adds to xml::node are constructors using std::string insteaf of
     *  const char*.
     *  - Dv::Xml::Node::Ref which encapsulates a xml::node::iterator
     *  (there is no version for xml::node::const_iterator). Thus a
     *  Dv::Xml::Node::Ref object can be thought of as a pointer into
     *  an XML tree.
     *
     * The intention is that Dv::Xml::Node is only used for "roots" in
     * XML tree structures, as in
     * \code
     * Dv::Xml::Node node("rootlabel");
     * \endcode
     *
     * For all other operations, Dv::Xml::Node::Ref should be used.
     * A strange feature is that Dv::Xml::Node::Ref::operator*
     * returns a reference to itself. The reason is that returning
     * a reference to a Dv::Xml::Node would involve copying the
     * underlying xml::node. On the other hand, returning a reference
     * to the underlying xml::node would imply that the convenient member
     * functions of Dv::Xml::Node::Ref would not be available on the
     * result of Dv::Xml::Node::Ref::operator* .
     *
     * For convenience, some Dv::Xml::Node::Ref operations are also
     * available on Dv::Xml::Node, either by direct delegation (e.g.
     * Dv::Xml::Node::operator[], Dv::Xml::Node::operator()) or
     * via a user-defined convertor that converst a Dv::Xml::Node to
     * a Dv::Xml::Node::Ref referring to this node.
     *
     * The main difference with the underlying xmlwrapp interface  is that
     * many operations are available through expressions. E.g. \a
     * (n/"login"/"name")("first_name"), with \a n a Dv::Xml::Node of
     * Dv::Xml::Node::Ref object, * refers to the \a first_name attribute of
     * the node obtained from \a n by taking the first "login" child and then
     * the first "name" child.
     *
     * Intuitively, for a Dv::Xml::Node::Ref \a n, \a n/"label" returns
     * a Dv::Xml::Node::Ref referring to the first child node with \a "label"
     * as name. The increment operator returns the next child with the
     * same name. E.g.
     * \code
     * Dv::Xml::Node::Ref n;
     * ..
     * Dv::Xml::Node::Ref c(n/"label");
     * ++c // refer to 2nd child of n with name "label"
     * \endcode
     * 
     * The \a > operator can be used to create new child nodes.
     * E.g. \a n>"label" returns a new child of \a n with name \a "label".
     * The same operator also works with a Dv::Xml::Node argument.
     * \code
     * Dv::Xml::Node::Ref n;
     * Dv::Xml::Node::Ref c;
     * (n >> c) // attach a copy of c as a child to n
     * \endcode
     *
     * Attributes can be set and accessed using \a operator[] and
     * \a operator() respectively.
     * \code
     * Dv::Xml::Node::Ref n;
     * n["first_name"] = "blabla"; // set attribute
     * if (n("first_name") != "blabla") // obtain attribute value
     *   throw std::logic_error("BUG");
     * \endcode
     *
     * The text content of a Dv::Xml::Node::Ref can be obtained by a conversion
     * (to std::string) operator. Assigning a std::string to a
     * Dv::Xml::Node::Ref has the same effect as xml::node::set_content().
     *
     */
    class Node: public xml::node {
    public:
      class Ref;
    
      /** Auxiliary class for attribute access. 
       * Dv::Xml::Node::Ref::operator[](const std::string) returns an
       * AttributeReference object.
       */
      class AttributeReference {
        friend class Ref;
        public:
          /** Set attribute referred to by this reference.
           * @warning The value will be automatically converted to
           * legal XML text (i.e. '&' will become '&amp;').
           * @param value to assign to attribute.
           * @return value
           */
          const std::string& operator=(const std::string& value);
      
          /** Set attribute referred to by this reference, after converting
           * the parameter object to a std::string. The conversion is done
           * using Dv::Util::tostring<T>.
           * @param t value to assign, after conversion, to attribute.
           * @return value
           */
          template <typename T>
          const std::string& operator=(const T& t) {
            return this->operator=(Dv::Util::tostring<T>(t));
          }
      
          /** Retrieve value of attribute referred to by this reference.
           * @return value of attribute referred to by this reference, or
           *  empty string if there is no attribute value associated with
           *  this reference.
           */
          std::string str() const;
      
          /** Retrieve value of attribute referred to by this reference.
           * @return value of attribute referred to by this reference, or
           *  empty string if there is no attribute value associated with
           *  this reference.
           */
          operator std::string() const { return str(); }
      
          /** Explicit conversion to any type that can be converted by
           *  Dv::Util::fromstring.
           * @param t lvalue referring to object resulting from the conversion
           * @return reference to first parameter (t).
           */
          template<typename T>
          T& conv(T& t) const {
            if (! Dv::Util::fromstring(t, str()) )
              throw Exception("Cannot convert AttributeReference to T");
            return t;
            }
        
          /** Template user-defined conversion function.
           * @warning This will not work for std::string (and others), unless
           *   the "assignment" syntax is used for explicit initializtion,
           *   as illustrated by the following example.
           * \code
           * Dv::Xml::Node::Ref n;
           * std::string s1(n["a"]); // error
           * std::string s2 = n["a"]; // OK
           * \endcode
           * The initialization of @a s1 is ambiguous: \a n["a"] may be converted
           * to a (single) paramater for a  std::string ctor using at least two
           * instantiations of the user-defined conversion template below:
           * - std::string(const char*)
           * - std::string(const std::string&)
           */
          template<typename T>
          operator T() const {
            typename noconst<T>::mutable_type t;
            conv(t);
            return t;
            }
      
      
        private:
          /** Constructor 
           * @param n reference to xml::node for which the attribute is
           * considered
           * @param name of the attribute
           */
          AttributeReference(const xml::node::iterator n, const std::string& name);
      
          const std::string name;
          xml::node::iterator node;
      };
    
      /** A reference to an xml::node object. */
      class Ref: public dv_forward_iterator<Node::Ref> {
        friend class Node;
        friend class Document;
        public:
        
          /** Construct a Dv::Xml::Node::Ref out of a (copy of a) xml::node object.
           * @param node xml::node which will be reference by the new Dv::Xml::Node::Ref object.
           */
          Ref(xml::node& node);
        
          /** @return name of underlying xml::node 
           * @exception Dv::Xml::Exception if this Dv::Xml::Node::Ref 
           *   does not refer to a valid xml::node.
           * @sa Dv::Xml::Node::Ref::nil
           */
          std::string name() const throw (Dv::Xml::Exception);
        
          /** Set name of underlying xml::node 
           * @param nm new name of node
           * @return *this
           * @exception Dv::Xml::Exception if this Dv::Xml::Node::Ref does not refer
           *   to a valid xml::node.
           * @sa Dv::Xml::Node::Ref::nil
           */
          Node::Ref& name(const std::string& nm) throw (Exception);
        
          /** Is this a "non-null" Dv::Xml::Node::Ref, i.e. does it refer to a valid
           *   xml::node?
           * @return true iff this Dv::Xml::Node::Ref does not refer to a valid xml::node.
           */
          bool nil() const { return nil_; }
        
          /** Is this not a valid Dv::Xml::Node::Ref, i.e. does it not refer to a valid
           *   xml::node?
           * @return true iff this Dv::Xml::Node::Ref does not refer to a valid xml::node.
           * @sa Dv::Xml::Node::Ref::nil
           */
          bool operator!() const { return nil(); }

          /** Equality test. 
           * @param m Dv::Xml::Node::Ref to compare this reference with.
           * @return true iff both nodes are nil or they refer to the same xml::node.
           */
          bool equals(const Node::Ref& m) const;
        
          /** Retrieve underlying xml::node for this Dv::Xml::Node::Ref.
           * This function can also be used to check whether this is a nil node.
           * \code
           * Dv::Xml::Node::Ref n(root/"child"/"grandchild");
           * if (n) {
           *   ..
           *   }
           * \endcode
           * @return pointer to xml::node to which this Dv::Xml::Node::Ref
           *   refers, or 0 if it is a "nil" node.
           * @sa Dv::Xml::Node::Ref::nil
           */
          operator const xml::node*() const;
          operator xml::node*();
        
          /** Retrieve child node (of this node) with matching name 
           * @param name to match in returned child node
           * @return Dv::Xml::Node::Ref referring to first child of this node that
           *  has name or nil.
           * @exception Dv::Xml::Exception if this Dv::Xml::Node::Ref does not refer to a valid
           *   xml::node.
           * @sa Dv::Xml::Node::Ref::nil
           */
          Node::Ref find(const std::string& name) const throw (Exception); 
        
          /** Return Ref that points past the last child of this node.
           * @return nil Dv::Xml::Node::Ref.
           * @exception Dv::Xml::Exception if this Dv::Xml::Node::Ref does not refer to a valid 
           *  xml::node.
           */
          Ref end() const throw (Exception);
        
          /** Return next child of parent with same name 
           * @return Dv::Xml::Node::Ref referring to next sibling of this node that
           *  has the same name.
           * @exception Dv::Xml::Exception if this Dv::Xml::Node::Ref
           *   does not refer to a valid xml::node.
           */
          Ref operator++() throw (Exception);
        
          /** Dummy dereference operator, const version.
           * This member function is needed to support forward iterator interface.
           * @return reference to self. 
           */
          const Node::Ref& operator*() const { return *this; }
        
          /** Dummy dereference operator, non-const version.
           * This member function is needed to support forward iterator interface.
           * @return reference to self. 
           */
          Node::Ref& operator*() { return *this; }
        
          /** Append a new text node to the list of children of this node.
           * @param name of the new node
           * @param contents of the new node
           * @return Dv::Xml::Node::Ref referring to the new child of this node.
           * @exception Dv::Xml::Exception if the target does not refer to a 
           *  valid xml::node.
           */
          Node::Ref add(const std::string& name, const std::string& contents) 
            throw (Dv::Xml::Exception);

          /** Append a new node to the list of children of this node.
           * @param name of the new node
           * @return Dv::Xml::Node::Ref referring to the new child of this node.
           * @exception Dv::Xml::Exception if the target does not refer to a 
           *  valid xml::node.
           */
          Node::Ref add(const char* name) throw (Exception);

          /** Append a new node to the list of children of this node.
           * @param name of the new node
           * @return Dv::Xml::Node::Ref referring to the new child of this node.
           * @exception Dv::Xml::Exception if the target does not refer to a 
           *  valid xml::node.
           */
          Node::Ref add(const std::string& name) throw (Exception) {
            return add(name.c_str());
          }

          /** Append copy of node to children of this node.
           * @param child a copy of which will be added to the children of this node.
           * @return Dv::Xml::Node::Ref referring to the new child of this node.
           * @exception Dv::Xml::Exception if either of the parameters does not refer to a 
           *  valid xml::node.
           */
          Node::Ref add(const Node::Ref& child) throw (Exception);

          /** Check whether this node has an attribute value for given key.
           * @param name key of attribute
           * @return true iff this node has an attribute value of this key.
           * @exception Dv::Xml::Exception if this Dv::Xml::Node::Ref does not refer
           *  to a valid xml::node.
           */
          bool defined(const std::string& name) const throw (Exception);
        
          /** Retrieve attribute value. 
           * @param name key of attribute
           * @return value of attribute
           * @exception Dv::Xml::Exception if this node has no attribute for key
           * "name" or this node does not refer to a valid xml::node.
           */
          const std::string operator()(const std::string& name) const throw (Exception);
        
          /** Set attribute value. 
           * @param name key of attribute
           * @return AttributeReference that can be used to either retrieve
           *   the current value of assign a new one. If there is no
           *   attribute value, the empty string will be returned (and
           *   stored).
           * @exception Dv::Xml::Exception if this Dv::Xml::Node::Ref does not refer
           *  to a valid xml::node.
           * @sa Dv::Xml::Node::AttributeReference
           * \code
           * Dv::Xml::Node::Ref n;
           * ..
           * n["name"] = "fred";
           * std::cout << n["name"] << std::endl;
           * \endcode
           */
          AttributeReference operator[](const std::string& name) throw (Exception);
        
          /** Retrieve text content. 
           * Note that the resulting string is trimmed, i.e. leading and
           * trailing white space is removed. To prevent trimming: use
           * Dv::Xml::Node::Ref::str(false).
           * @return text content of text-xml::node children of this
           *   Dv::Xml::Node::Ref.
           * @exception Dv::Xml::Exception if this Dv::Xml::Node::Ref does not refer 
           *  to a valid xml::node.
           * @sa Dv::Xml::Node::Ref::str
           */
          operator std::string() const throw (Exception);
      
          /** Template user-defined conversion function.
           * @warning This will not work for std::string (and others), unless
           *   the "assignment" syntax is used for explicit initializtion,
           *   as illustrated by the following example.
           * \code
           * Dv::Xml::Node::Ref n;
           * std::string s1(n["a"]); // error
           * std::string s2 = n["a"]; // OK
           * \endcode
           * The initialization of @a s1 is ambiguous: \a n["a"] may be converted
           * to a (single) paramater for a  std::string ctor using at least two
           * instantiations of the user-defined conversion template below:
           * - std::string(const char*)
           * - std::string(const std::string&)
           */
           template<typename T>
           operator T() const {
             typename noconst<T>::mutable_type t;
             Dv::Util::fromstring(t, str());
             return t;
             }
        
          /** Retrieve text content. 
           * @return text content of text-xml::node children of this
           *   Dv::Xml::Node::Ref.
           * @param trim if true, remove leading and trailing white space from result.
           * @exception Dv::Xml::Exception if this Dv::Xml::Node::Ref does not refer 
           *  to a valid xml::node.
           */
          std::string str(bool trim=true) const throw (Exception);
        
          /** Set text content.
           * @param text to be used as content for this node.
           * @warning Note that the text parameter must be legal XML (see test-node-5 in
           * the distrbution). 
           * @return reference to this node. All children of this node will 
           *  have been zapped and a new single child xml::node of type text
           *  will have been inserted.
           * @exception Dv::Xml::Exception if this Dv::Xml::Node::Ref does not
           *  refer to a valid xml::node.
           * @see Dv::Xml::to_html
           */
          Ref& operator=(const std::string& text) throw (Exception);
      
          /** Set content of node referred to by this reference, after converting
           * the parameter object to a std::string. The conversion is done
           * using Dv::Util::tostring<T>.
           * @param t value to assign, after conversion, to attribute.
           * @return string representation of @a t.
           */
          template <typename T>
          const std::string operator=(const T& t) {
            return this->operator=(Dv::Util::tostring<T>(t));
            }
        
          /** Replace this node by another one. The replacement will
           * take place in the tree of which this Ref is a part.
           * @param ref reference to xml::node of which a copy will replace this node.
           * @return reference to this Dv::Xml::Node::Ref.
           * @warning the xml::node to which ref refers will be copied.
           */
          Ref& replace(const Ref& ref);
        
        protected:
          /** Constructor.
           * @param it iterator, possibly referring to xml::node
           * @param nil true iff it does not refer to a valid xml::node.
           */
          explicit Ref(xml::node::iterator it, bool nil=false);
          /** Constructor.
           * @param it const_iterator, possibly referring to xml::node
           * @param nil true iff it does not refer to a valid xml::node.
           */
          explicit Ref(xml::node::const_iterator it, bool nil=false);
          /** Throw an exception if this Dv::Xml::Node::Ref object does
           * not refer to a valid xml::node.
           * @param message to be used in the generated exception.
           */
          void assert_valid(const std::string& message) const throw (Dv::Xml::Exception);
        
        private:
          /** Refers to xml::node, if valid. */
          xml::node::iterator it_;
          /** False iff it_ refers to a valid xml::node. */
          bool nil_;
      };
    
      /** Default constructor. */
      Node(): xml::node() {}
    
      /** Create an xml::node with a given name.
       * @param name of new xml::node.
       */
      explicit Node(const std::string& name): xml::node(name.c_str()) {}
    

      /** Create an xml::node with a given name and content.
       * @param name of new xml::node.
       * @param content text content of new xml::node.
       */
      Node(const std::string& name, const std::string& content): 
        // xml::node(name.c_str(), to_html(content).c_str()) {}
        xml::node(name.c_str(), content.c_str()) {}

      template<typename T>
        explicit Node(const std::string& name, const T& c): 
          xml::node(name.c_str(), Dv::Util::tostring(c).c_str()) {}
    
      /** Return a Dv::Xml::Node::Ref object referring to this Node. */
      Ref ref() const { 
        return Ref(const_cast<xml::node*>(static_cast<const xml::node*>(this))->self()); 
      }

      /** Return a Dv::Xml::Node::Ref object referring to this Node. */
      Ref ref() { 
        return Ref(const_cast<xml::node*>(static_cast<xml::node*>(this))->self()); 
      }
    
      /** Return a Dv::Xml::Node::Ref object referring to this Node. */
      operator Node::Ref() { return ref(); }

      /** Return a Dv::Xml::Node::Ref object referring to this Node. */
      operator Node::Ref() const { return ref(); }
    
      /** Set attribute value. 
       * @param name key of attribute
       * @return Dv::Xml::Node::AttributeReference that can be used to either retrieve
       *   the current value of assign a new one. If there
       * @sa Dv::Xml::Node::AttributeReference
       * \code
       * Dv::Xml::Node::Ref n;
       * ..
       * n["name"] = "fred";
       * std::cout << n["name"] << std::endl;
       * \endcode
       */
      AttributeReference operator[](const std::string& name) { return ref()[name]; }
    
      /** Retrieve attribute value. 
       * @param name key of attribute
       * @return value of attribute
       * @exception Dv::Xml::Exception if this node has no attribute for key "name".
       */
      const std::string operator()(const std::string& name) const throw (Exception) { 
        return ref()(name); 
        }
    
      /** Return Ref that points past the last child of this node.
       * @return nil Dv::Xml::Node::Ref.
       */
      const Ref end() const { return ref().end(); }
    
      /** @return name of underlying xml::node */
      std::string name() const { return get_name(); }
    
      /** Add another node as a child to this node.
       * @param ref reference to node to add
       * @return *this
       */
      Node& add(const Node::Ref& ref);

  
      /** Add another node as a child to this node.
       * @param ref to Node to add
       * @return *this
      Node& add(const Node::Ref& ref) { 
        *this >> ref;
        return *this;
      }
       */

      /** Add a new node as a child to this node.
       * @param name of new node to add as a child
       * @return *this
       */
      Node& add(const std::string& name) {
        add(Node(name));
        return *this;
      }

      /** Add a new text node as a child to this node.
       * @param name of the new node to add as a child
       * @param contents of the new node to add as a child
       * @return *this
       */
      Node& add(const std::string& name, const std::string& contents) {
        add(Node(name, contents));
        return *this;
      }

      /** Add a new text node as a child to this node.
       * @param name of the new node to add as a child
       * @param contents of the new node to add as a child
       * @return *this
       */
      template<typename T>
      Node& add(const std::string& name, const T& contents) {
        add(Node(name, Dv::Util::tostring(contents)));
        return *this;
      }
    };

    /** Print an XML tree rooted at the node referred to by a
     *   Dv::Xml::Node::Ref object. 
     * @param os stream to print to
     * @param ref reference to xml::node (may be invalid)
     * @warning The function will print "nil" if the object does
     *   not refer to a valid xml::node.
     */
    std::ostream&
    operator<<(std::ostream& os, const Node::Ref& ref);

    /** Retrieve child node with matching name 
     * @param ref reference to xml::node of which child is to be found
     * @param name to match in returned child node
     * @return Dv::Xml::Node::Ref referring to first child of this node that
     *  has name or nil.
     * @exception Dv::Xml::Exception if this Dv::Xml::Node::Ref does not refer to a valid
     *   xml::node.
     * @sa Dv::Xml::Node::Ref::nil
     */
    inline Node::Ref operator/(const Node::Ref& ref, const std::string& name) throw (Exception) {
      return ref.find(name);
    }

    /** Equality test. 
     * @param n Dv::Xml::Node::Ref to compare with.
     * @param m Dv::Xml::Node::Ref to compare with.
     * @return true iff both nodes are nil or they refer to the same xml::node.
     */
    inline bool operator==(const Node::Ref& n, const Node::Ref& m) {
      return n.equals(m);
    }

    /** Inequality test. 
     * @param m Dv::Xml::Node::Ref to compare with.
     * @param n Dv::Xml::Node::Ref to compare with.
     * @return true iff the nodes are not equal
     * @sa Dv::Xml::operator==(const Node::Ref& n, const Node::Ref& m)
     */
    inline bool operator!=(const Node::Ref m, const Node::Ref& n) {
      return ! (m.equals(n));
    }
        
    /** Append new child node with given name.
     * @param ref to node to which a new child node will be appended.
     * @param name for new child node.
     * @return Dv::Xml::Node::Ref referring to new child of this node that
     *  has name.
     * @exception Dv::Xml::Exception if \a ref does not refer to 
     *  a valid xml::node.
     */
    inline Node::Ref operator>>(Node::Ref ref, const std::string& name) throw (Exception) {
      return ref.add(name);
    }

    /** Append new child node with given name.
     * @param ref to node to which a new child node will be appended.
     * @param name for new child node.
     * @return Dv::Xml::Node::Ref referring to new child of this node that
     *  has name.
     * @exception Dv::Xml::Exception if \a ref does not refer to 
     *  a valid xml::node.
     */
    inline Node::Ref operator>>(Node::Ref ref, const char* name) throw (Exception) {
      return ref.add(name);
    }

    /** Append copy of node to children of this node.
     * @param ref reference to xml::node to which a child will be added.
     * @param child a copy of which will be added to the children of this node.
     * @return Dv::Xml::Node::Ref referring to the new child of this node.
     * @exception Dv::Xml::Exception if either of the parameters does not refer to a 
     *  valid xml::node.
     */
    inline Node::Ref operator>>(Node::Ref ref, Node::Ref child) throw (Exception) {
      return ref.add(child);
    }

    inline std::ostream& operator<<(std::ostream& os, const Node::AttributeReference& a) {
      return os << a.str();
    }
  }
}

#endif

---

dvxml-0.1.7

[ 7 January, 2008]