00001 /* 00002 * Copyright (C) 2001-2003 Peter J Jones (pjones@pmade.org) 00003 * All Rights Reserved 00004 * 00005 * Redistribution and use in source and binary forms, with or without 00006 * modification, are permitted provided that the following conditions 00007 * are met: 00008 * 00009 * 1. Redistributions of source code must retain the above copyright 00010 * notice, this list of conditions and the following disclaimer. 00011 * 2. Redistributions in binary form must reproduce the above copyright 00012 * notice, this list of conditions and the following disclaimer in 00013 * the documentation and/or other materials provided with the 00014 * distribution. 00015 * 3. Neither the name of the Author nor the names of its contributors 00016 * may be used to endorse or promote products derived from this software 00017 * without specific prior written permission. 00018 * 00019 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' 00020 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 00021 * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A 00022 * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR 00023 * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 00024 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 00025 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF 00026 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 00027 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 00028 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 00029 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 00030 * SUCH DAMAGE. 00031 */ 00032 00033 /** @file 00034 * This file contains the definition of the xml::tree_parser class. 00035 **/ 00036 00037 #ifndef _xmlwrapp_tree_parser_h_ 00038 #define _xmlwrapp_tree_parser_h_ 00039 00040 // standard includes 00041 #include <cstddef> 00042 #include <string> 00043 00044 namespace xml { 00045 00046 // forward declarations 00047 struct tree_impl; 00048 class document; 00049 00050 /** 00051 * The xml::tree_parser class is used to parse an XML document and generate 00052 * a tree like structure of xml::node objects. After constructing a 00053 * tree_parser, with either a file to parse or some in memory data to parse, 00054 * you can walk the tree using the xml::node interface. 00055 **/ 00056 class tree_parser { 00057 public: 00058 typedef std::size_t size_type; 00059 00060 //#################################################################### 00061 /** 00062 * xml::tree_parser class constructor. Given the name of a file, this 00063 * constructor will parse that file. 00064 * 00065 * There are two options for dealing with XML parsing errors. The 00066 * default it to throw an exception (std::runtime_error). The other 00067 * option is to pass false for the allow_exceptions flag. This will 00068 * prevent an exception from being thrown, instead, a flag will be set 00069 * that you can test with the operator! member function. 00070 * 00071 * No matter what option you choose, this constructor may still throw 00072 * exceptions for memory failure or other non-parsing related failures. 00073 * 00074 * @param filename The name of the file to parse. 00075 * @param allow_exceptions Whether or not you want an exception for parsing errors. 00076 * @author Peter Jones 00077 **/ 00078 //#################################################################### 00079 tree_parser (const char *filename, bool allow_exceptions=true); 00080 00081 //#################################################################### 00082 /** 00083 * xml::tree_parser class constructor. Given some data and the size of 00084 * that data, parse that data as XML. To see if the data was parsed 00085 * successfully use operator!. 00086 * 00087 * @param data The XML data to parse. 00088 * @param size The size of the XML data to parse. 00089 * @param allow_exceptions Whether or not you want an exception for parsing errors. 00090 * @author Peter Jones 00091 **/ 00092 //#################################################################### 00093 tree_parser (const char *data, size_type size, bool allow_exceptions=true); 00094 00095 //#################################################################### 00096 /** 00097 * xml::tree_parser class destructor. 00098 * 00099 * @author Peter Jones 00100 **/ 00101 //#################################################################### 00102 ~tree_parser (void); 00103 00104 //#################################################################### 00105 /** 00106 * Check to see if a xml::tree_parser class is vaild. That is, check to 00107 * see if parsing XML data was successful and the tree_parser holds a 00108 * good XML node tree. 00109 * 00110 * @return True if the tree_parser is NOT VAILD; false if it is vaild. 00111 * @author Peter Jones 00112 **/ 00113 //#################################################################### 00114 bool operator! (void) const; 00115 00116 //#################################################################### 00117 /** 00118 * If operator! indicates that there was an error parsing your XML data, 00119 * you can use this member function to get the error message that was 00120 * generated durring parsing. 00121 * 00122 * @return The error message generated durring XML parsing. 00123 * @author Peter Jones 00124 **/ 00125 //#################################################################### 00126 const std::string& get_error_message (void) const; 00127 00128 //#################################################################### 00129 /** 00130 * Check to see if there were any warnings from the parser while 00131 * processing the given XML data. If there were, you may want to send 00132 * the same document through xmllint or the event_parser to catch and 00133 * review the warning messages. 00134 * 00135 * @return True if there were any warnings. 00136 * @return False if there were no warnings. 00137 * @author Peter Jones 00138 **/ 00139 //#################################################################### 00140 bool had_warnings (void) const; 00141 00142 //#################################################################### 00143 /** 00144 * Get a reference to the xml::document that was generated during the 00145 * XML parsing. You should make sure to only use a reference to the 00146 * document to avoid a deep copy. 00147 * 00148 * @return A reference to the xml::document. 00149 * @author Peter Jones 00150 **/ 00151 //#################################################################### 00152 xml::document& get_document (void); 00153 00154 //#################################################################### 00155 /** 00156 * Get a const reference to the xml::document that was generate during 00157 * the XML parsing. You should make sure to only use a reference to the 00158 * document to avoid a deep copy. 00159 * 00160 * @return A const reference to the xml::document. 00161 * @author Peter Jones 00162 **/ 00163 //#################################################################### 00164 const xml::document& get_document (void) const; 00165 private: 00166 tree_impl *pimpl_; // private implementation 00167 00168 /* 00169 * Don't allow anyone to copy construct a xml::tree_parser or allow the 00170 * assignment operator to be called. It is not very useful to copy a 00171 * parser that has already parsed half a document. 00172 */ 00173 tree_parser (const tree_parser&); 00174 tree_parser& operator= (const tree_parser&); 00175 }; // end xml::tree_parser class 00176 00177 } // end xml namespace 00178 #endif