doc.h

Go to the documentation of this file.

#ifndef DVXML_DOC_H
#define DVXML_DOC_H
// $Id: doc.h,v 1.16 2008/01/07 14:45:20 dvermeir Exp $
#include <stdexcept>
#include <iterator>
#include <iostream>
#include <dvutil/tostring.h>
#include <dvutil/file.h>
#include <xmlwrapp/xmlwrapp.h>

#include <dvxml/exception.h>
#include <dvxml/noconst.h>
#include <dvxml/node.h>

namespace Dv { 
  namespace Xml { 
    /** Convenience interface to xml::document. */
    class Document: public xml::document { 
      public: 
        /** Default ctor. */ 
        explicit Document(); 
        /** Construct a Dv::Xml::Document out of a (copy of a) Dv::Xml::Node object. 
         * @param ref Dv::Xml::Node::Ref, a copy of which will be used as the root
         *   of the new Dv::Xml::Document object.
         * @exception Dv::Xml::Exception if node is not valid.
         */
        explicit Document(const Node::Ref& ref) throw (Exception);

        /** Parse a Dv::Xml::Document from a file
         * @param file containing document
         * @exception Dv::Xml::Exception upon any error
         */
        explicit Document(const Dv::Util::File& file) throw (Exception);
      
        /** Create a Dv::Xml::Document with a root labeled with given name and content. 
         * @param name to be used as the label of the root of the document
         * @param content to be used as the content of the root of the document
         * @exception Dv::Xml::Exception upon any error
         */
        explicit Document(const std::string& name, const std::string& content)
          throw (Exception);
      
        /** Create a Dv::Xml::Document with a root labeled with given name.
         * @param name to be used as the label of the root of the document
         * @exception Dv::Xml::Exception upon any error
         */
        explicit Document(const std::string& name) throw (Exception);
      
        /** Parse a Dv::Xml::Document from an array of characters .
         * @param pc pointer to the start of the data
         * @param size of the data array
         * @exception Dv::Xml::Exception upon any error
         */
        explicit Document(const char* pc, size_t size) throw (Exception);
      
        /** Create a Dv::Xml::Document by applying an XSLT stylesheet to
         * another Document.
         * @param stylesheet filename of xslt file
         * @param doc input document
         * @exception Dv::Xml::Exception upon any error
         * @warning Do not use this if the document is not xml output, as
         * e.g. specified by an xsl directive such as
         * @code
         * <xsl:output method="html" encoding="ISO-8859-1" omit-xml-declaration="yes"/>
         * @endcode
         * For html output, use Dv::Xml::Document::apply instead.
         */
        explicit Document(const std::string& stylesheet, Document& doc) throw (Exception);
      
        /** Destructor. */
        virtual ~Document();
      
        /** Parse a Dv::Xml::Document from an array of characters . The
         * result replaces the current contents of this document.
         * @param data pointer to the start of the data
         * @param size of the data array
         * @return reference to this document
         * @exception Dv::Xml::Exception upon any error
         */
        Document& parse(const char* data, size_t size) throw (Exception);
      
        /** Parse a Dv::Xml::Document from a filenm. The
         * result replaces the current contents of this document.
         * @param filenm name of file where document can be found.
         * @return reference to this document
         * @exception Dv::Xml::Exception upon any error
         */
        Document& parse(const std::string& filenm) throw (Exception);
      
        /** Set root.
         * @param ref reference to node to copy to root of this document.
         * @exception Dv::Xml::Exception if ref does not refer to a valid xml::node.
         * @sa Dv::Xml::Document::root(const Dv::Xml::Node& node)
         */
        Document& operator=(const Node::Ref& ref) throw (Exception);
      
        /** Set root.
         * @param ref reference to node that will be copied to the root of this document.
         * @exception Dv::Xml::Exception if node is not valid.
         * @sa Dv::Xml::Node
         */
        void root(const Node::Ref& ref) throw (Exception);
      
        /** Get root Dv::Xml::Node of Document.
         * @return root Dv::Xml::Node of Document.
         * @warning Assigning the result does \b not change the root.
         * Updating is possible, as in the example below.
         * @code
         * Dv::Xml::Document doc;
         * ..
         * (doc.root() >> "child" >> "grandchild")["name"] = "Pete";
         * @endcode
         */
        Node::Ref root() const;

        /** Convert to reference to root of document.
         * @sa Dv::Xml::Document::root
         */
        operator Node::Ref() const { return root(); }
       
        /** Get encoding of Document. Default is "ISO-8859-1". 
         * @return encoding of Document.
         */
        const std::string& encoding() const { return get_encoding(); }
      
        /** Set encoding of Document. 
         * @param enc encoding of Document
         * @return *this
         */
        Document& encoding(const std::string& enc) { 
          set_encoding(enc.c_str()); return *this; }
      
        /** Validate document w.r.t. DTD.
         * @param dtd url or filename of DTD, if empty, the dtd is
         *   assumed to have been included in the document.
         * @return true iff the document is valid w.r.t the DTD.
         */
        bool valid(const std::string& dtd = "");
      
        /** Select node after path from document.
         * @param path of the form "a/b/c"
         * @return node at the end of the path
         * @exception Dv::Xml::Exception if node is not valid.
         */
        Node::Ref select(const std::string& path) const throw (Exception);

        /** Apply an XSLT stylesheet to this Document. The result
         * is immediately serialised in a string (useful e.g. when
         * the "omit-xml-declaration" option is used.
         * @param stylesheet filename of xslt file
         * @param s string that will contain the result of the XSL transform.
         * @return s
         * @exception Dv::Xml::Exception upon any error
         * @warning This is function properly takes into
         * account directives such as
         * @code
         * <xsl:output method="html" encoding="ISO-8859-1" omit-xml-declaration="yes"/>
         * @endcode
         * Do not look for a simple way to send output of an xslt transformation to a stream.
         * There is none (en neither is there in xmlwrapp, xml++, .. ). The
         * reason is probably that libxslt only provides output to FILE*
         * using xsltSaveResultTo.. functions. And I don't know of an easy
         * way to link std::ostream objects to FILE*'s.
         */
        std::string& apply(const std::string& stylesheet, std::string& s) throw (Exception);
        /** Apply an XSLT stylesheet to this Document. The result
         * is immediately serialised in a string (useful e.g. when
         * the "omit-xml-declaration" option is used.
         * @param stylesheet filename of xslt file
         * @return string that containing the result of the XSL transform.
         * @exception Dv::Xml::Exception upon any error
         * @warning This is function properly takes into
         * account directives such as
         * @code
         * <xsl:output method="html" encoding="ISO-8859-1" omit-xml-declaration="yes"/>
         * @endcode
         */
        std::string apply(const std::string& stylesheet) throw (Exception) {
          std::string s;
          apply(stylesheet, s);
          return s; 
        } 
    };
  }
}
       
      

#endif

---

dvxml-0.1.7

[ 7 January, 2008]