xmlwrapp
|
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 /** 00034 @file 00035 00036 This file contains the definition of the xml::tree_parser class. 00037 */ 00038 00039 #ifndef _xmlwrapp_tree_parser_h_ 00040 #define _xmlwrapp_tree_parser_h_ 00041 00042 // xmlwrapp includes 00043 #include "xmlwrapp/init.h" 00044 00045 // standard includes 00046 #include <cstddef> 00047 #include <string> 00048 00049 namespace xml 00050 { 00051 00052 // forward declarations 00053 class document; 00054 00055 namespace impl 00056 { 00057 struct tree_impl; 00058 } 00059 00060 /** 00061 The xml::tree_parser class is used to parse an XML document and generate 00062 a tree like structure of xml::node objects. 00063 00064 After constructing a tree_parser, with either a file to parse or some in 00065 memory data to parse, you can walk the tree using the xml::node interface. 00066 */ 00067 class tree_parser 00068 { 00069 public: 00070 typedef std::size_t size_type; 00071 00072 /** 00073 xml::tree_parser class constructor. Given the name of a file, this 00074 constructor will parse that file. 00075 00076 There are two options for dealing with XML parsing errors. The 00077 default it to throw an exception (std::runtime_error). The other 00078 option is to pass false for the allow_exceptions flag. This will 00079 prevent an exception from being thrown, instead, a flag will be set 00080 that you can test with the operator! member function. 00081 00082 No matter what option you choose, this constructor may still throw 00083 exceptions for memory failure or other non-parsing related failures. 00084 00085 @param filename The name of the file to parse. 00086 @param allow_exceptions Whether or not you want an exception for parsing errors. 00087 */ 00088 tree_parser(const char *filename, bool allow_exceptions = true); 00089 00090 /** 00091 xml::tree_parser class constructor. Given some data and the size of 00092 that data, parse that data as XML. To see if the data was parsed 00093 successfully use operator!. 00094 00095 @param data The XML data to parse. 00096 @param size The size of the XML data to parse. 00097 @param allow_exceptions Whether or not you want an exception 00098 for parsing errors. 00099 */ 00100 tree_parser(const char *data, size_type size, bool allow_exceptions = true); 00101 00102 ~tree_parser(); 00103 00104 /** 00105 Check to see if a xml::tree_parser class is vaild. That is, check to 00106 see if parsing XML data was successful and the tree_parser holds a 00107 good XML node tree. 00108 00109 @return True if the tree_parser is NOT VAILD; false if it is vaild. 00110 */ 00111 bool operator!() const; 00112 00113 /** 00114 If operator! indicates that there was an error parsing your XML data, 00115 you can use this member function to get the error message that was 00116 generated during parsing. 00117 00118 @return The error message generated durring XML parsing. 00119 */ 00120 const std::string& get_error_message() const; 00121 00122 /** 00123 Check to see if there were any warnings from the parser while 00124 processing the given XML data. If there were, you may want to send 00125 the same document through xmllint or the event_parser to catch and 00126 review the warning messages. 00127 00128 @return True if there were any warnings. 00129 @return False if there were no warnings. 00130 */ 00131 bool had_warnings() const; 00132 00133 /** 00134 Get a reference to the xml::document that was generated during the 00135 XML parsing. You should make sure to only use a reference to the 00136 document to avoid a deep copy. 00137 00138 @return A reference to the xml::document. 00139 */ 00140 xml::document& get_document(); 00141 00142 /** 00143 Get a const reference to the xml::document that was generate during 00144 the XML parsing. You should make sure to only use a reference to the 00145 document to avoid a deep copy. 00146 00147 @return A const reference to the xml::document. 00148 */ 00149 const xml::document& get_document() const; 00150 00151 private: 00152 impl::tree_impl *pimpl_; // private implementation 00153 00154 // Don't allow anyone to copy construct a xml::tree_parser or allow the 00155 // assignment operator to be called. It is not very useful to copy a 00156 // parser that has already parsed half a document. 00157 tree_parser(const tree_parser&); 00158 tree_parser& operator=(const tree_parser&); 00159 }; 00160 00161 } // end xml namespace 00162 00163 #endif // _xmlwrapp_tree_parser_h_