00001 #ifndef DVXML_DOC_H 00002 #define DVXML_DOC_H 00003 // $Id: doc.h,v 1.16 2008/01/07 14:45:20 dvermeir Exp $ 00004 #include <stdexcept> 00005 #include <iterator> 00006 #include <iostream> 00007 #include <dvutil/tostring.h> 00008 #include <dvutil/file.h> 00009 #include <xmlwrapp/xmlwrapp.h> 00010 00011 #include <dvxml/exception.h> 00012 #include <dvxml/noconst.h> 00013 #include <dvxml/node.h> 00014 00015 namespace Dv { 00016 namespace Xml { 00017 /** Convenience interface to xml::document. */ 00018 class Document: public xml::document { 00019 public: 00020 /** Default ctor. */ 00021 explicit Document(); 00022 /** Construct a Dv::Xml::Document out of a (copy of a) Dv::Xml::Node object. 00023 * @param ref Dv::Xml::Node::Ref, a copy of which will be used as the root 00024 * of the new Dv::Xml::Document object. 00025 * @exception Dv::Xml::Exception if node is not valid. 00026 */ 00027 explicit Document(const Node::Ref& ref) throw (Exception); 00028 00029 /** Parse a Dv::Xml::Document from a file 00030 * @param file containing document 00031 * @exception Dv::Xml::Exception upon any error 00032 */ 00033 explicit Document(const Dv::Util::File& file) throw (Exception); 00034 00035 /** Create a Dv::Xml::Document with a root labeled with given name and content. 00036 * @param name to be used as the label of the root of the document 00037 * @param content to be used as the content of the root of the document 00038 * @exception Dv::Xml::Exception upon any error 00039 */ 00040 explicit Document(const std::string& name, const std::string& content) 00041 throw (Exception); 00042 00043 /** Create a Dv::Xml::Document with a root labeled with given name. 00044 * @param name to be used as the label of the root of the document 00045 * @exception Dv::Xml::Exception upon any error 00046 */ 00047 explicit Document(const std::string& name) throw (Exception); 00048 00049 /** Parse a Dv::Xml::Document from an array of characters . 00050 * @param pc pointer to the start of the data 00051 * @param size of the data array 00052 * @exception Dv::Xml::Exception upon any error 00053 */ 00054 explicit Document(const char* pc, size_t size) throw (Exception); 00055 00056 /** Create a Dv::Xml::Document by applying an XSLT stylesheet to 00057 * another Document. 00058 * @param stylesheet filename of xslt file 00059 * @param doc input document 00060 * @exception Dv::Xml::Exception upon any error 00061 * @warning Do not use this if the document is not xml output, as 00062 * e.g. specified by an xsl directive such as 00063 * @code 00064 * <xsl:output method="html" encoding="ISO-8859-1" omit-xml-declaration="yes"/> 00065 * @endcode 00066 * For html output, use Dv::Xml::Document::apply instead. 00067 */ 00068 explicit Document(const std::string& stylesheet, Document& doc) throw (Exception); 00069 00070 /** Destructor. */ 00071 virtual ~Document(); 00072 00073 /** Parse a Dv::Xml::Document from an array of characters . The 00074 * result replaces the current contents of this document. 00075 * @param data pointer to the start of the data 00076 * @param size of the data array 00077 * @return reference to this document 00078 * @exception Dv::Xml::Exception upon any error 00079 */ 00080 Document& parse(const char* data, size_t size) throw (Exception); 00081 00082 /** Parse a Dv::Xml::Document from a filenm. The 00083 * result replaces the current contents of this document. 00084 * @param filenm name of file where document can be found. 00085 * @return reference to this document 00086 * @exception Dv::Xml::Exception upon any error 00087 */ 00088 Document& parse(const std::string& filenm) throw (Exception); 00089 00090 /** Set root. 00091 * @param ref reference to node to copy to root of this document. 00092 * @exception Dv::Xml::Exception if ref does not refer to a valid xml::node. 00093 * @sa Dv::Xml::Document::root(const Dv::Xml::Node& node) 00094 */ 00095 Document& operator=(const Node::Ref& ref) throw (Exception); 00096 00097 /** Set root. 00098 * @param ref reference to node that will be copied to the root of this document. 00099 * @exception Dv::Xml::Exception if node is not valid. 00100 * @sa Dv::Xml::Node 00101 */ 00102 void root(const Node::Ref& ref) throw (Exception); 00103 00104 /** Get root Dv::Xml::Node of Document. 00105 * @return root Dv::Xml::Node of Document. 00106 * @warning Assigning the result does \b not change the root. 00107 * Updating is possible, as in the example below. 00108 * @code 00109 * Dv::Xml::Document doc; 00110 * .. 00111 * (doc.root() >> "child" >> "grandchild")["name"] = "Pete"; 00112 * @endcode 00113 */ 00114 Node::Ref root() const; 00115 00116 /** Convert to reference to root of document. 00117 * @sa Dv::Xml::Document::root 00118 */ 00119 operator Node::Ref() const { return root(); } 00120 00121 /** Get encoding of Document. Default is "ISO-8859-1". 00122 * @return encoding of Document. 00123 */ 00124 const std::string& encoding() const { return get_encoding(); } 00125 00126 /** Set encoding of Document. 00127 * @param enc encoding of Document 00128 * @return *this 00129 */ 00130 Document& encoding(const std::string& enc) { 00131 set_encoding(enc.c_str()); return *this; } 00132 00133 /** Validate document w.r.t. DTD. 00134 * @param dtd url or filename of DTD, if empty, the dtd is 00135 * assumed to have been included in the document. 00136 * @return true iff the document is valid w.r.t the DTD. 00137 */ 00138 bool valid(const std::string& dtd = ""); 00139 00140 /** Select node after path from document. 00141 * @param path of the form "a/b/c" 00142 * @return node at the end of the path 00143 * @exception Dv::Xml::Exception if node is not valid. 00144 */ 00145 Node::Ref select(const std::string& path) const throw (Exception); 00146 00147 /** Apply an XSLT stylesheet to this Document. The result 00148 * is immediately serialised in a string (useful e.g. when 00149 * the "omit-xml-declaration" option is used. 00150 * @param stylesheet filename of xslt file 00151 * @param s string that will contain the result of the XSL transform. 00152 * @return s 00153 * @exception Dv::Xml::Exception upon any error 00154 * @warning This is function properly takes into 00155 * account directives such as 00156 * @code 00157 * <xsl:output method="html" encoding="ISO-8859-1" omit-xml-declaration="yes"/> 00158 * @endcode 00159 * Do not look for a simple way to send output of an xslt transformation to a stream. 00160 * There is none (en neither is there in xmlwrapp, xml++, .. ). The 00161 * reason is probably that libxslt only provides output to FILE* 00162 * using xsltSaveResultTo.. functions. And I don't know of an easy 00163 * way to link std::ostream objects to FILE*'s. 00164 */ 00165 std::string& apply(const std::string& stylesheet, std::string& s) throw (Exception); 00166 /** Apply an XSLT stylesheet to this Document. The result 00167 * is immediately serialised in a string (useful e.g. when 00168 * the "omit-xml-declaration" option is used. 00169 * @param stylesheet filename of xslt file 00170 * @return string that containing the result of the XSL transform. 00171 * @exception Dv::Xml::Exception upon any error 00172 * @warning This is function properly takes into 00173 * account directives such as 00174 * @code 00175 * <xsl:output method="html" encoding="ISO-8859-1" omit-xml-declaration="yes"/> 00176 * @endcode 00177 */ 00178 std::string apply(const std::string& stylesheet) throw (Exception) { 00179 std::string s; 00180 apply(stylesheet, s); 00181 return s; 00182 } 00183 }; 00184 } 00185 } 00186 00187 00188 00189 #endif
dvxml-0.1.7 | [ 7 January, 2008] |