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::event_parser class. 00037 */ 00038 00039 #ifndef _xmlwrapp_event_parser_h_ 00040 #define _xmlwrapp_event_parser_h_ 00041 00042 // xmlwrapp includes 00043 #include "xmlwrapp/init.h" 00044 00045 // standard includes 00046 #include <cstddef> 00047 #include <string> 00048 #include <iosfwd> 00049 #include <map> 00050 00051 namespace xml 00052 { 00053 00054 namespace impl 00055 { 00056 struct epimpl; // forward declaration of private implementation 00057 } 00058 00059 /** 00060 The xml::event_parser is used to parse an XML document by calling member 00061 functions when certain things in the XML document are parsed. In order to 00062 use this class you derive a sub-class from it and override the protected 00063 virtual functions. 00064 */ 00065 class event_parser 00066 { 00067 public: 00068 /// a type for holding XML node attributes 00069 typedef std::map<std::string, std::string> attrs_type; 00070 /// size type 00071 typedef std::size_t size_type; 00072 00073 /// Default constructor. 00074 event_parser(); 00075 00076 virtual ~event_parser(); 00077 00078 /** 00079 Call this member function to parse the given file. 00080 00081 @param filename The name of the file to parse. 00082 @return True if the file was successfully parsed; false otherwise. 00083 */ 00084 bool parse_file(const char *filename); 00085 00086 /** 00087 Parse what ever data that can be read from the given stream. 00088 00089 @param stream The stream to read data from. 00090 @return True if the stream was successfully parsed; false otherwise. 00091 */ 00092 bool parse_stream(std::istream& stream); 00093 00094 /** 00095 Call this function to parse a chunk of xml data. When you are done 00096 feeding the parser chucks of data you need to call the parse_finish 00097 member function. 00098 00099 @param chunk The xml data chuck to parse. 00100 @param length The size of the given data chunk 00101 @return True if the chunk was parsed sucessfully; false otherwise. 00102 */ 00103 bool parse_chunk(const char *chunk, size_type length); 00104 00105 /** 00106 Finish parsing chunked data. You only need to call this member 00107 function is you were parsing chunked xml data via the parse_chunk 00108 member function. 00109 00110 @return True if all parsing was successful; false otherwise. 00111 */ 00112 bool parse_finish(); 00113 00114 /** 00115 If there was an error parsing the XML data, (indicated by one of the 00116 parsing functions returning false), you can call this function to get 00117 a message describing the error. 00118 00119 @return A description of the XML parsing error. 00120 */ 00121 const std::string& get_error_message() const; 00122 00123 protected: 00124 /** 00125 Override this member function to receive the start_element message. 00126 This member function is called when the parser encounters an xml 00127 element. 00128 00129 @param name The name of the element 00130 @param attrs The element's attributes 00131 @return You should return true to continue parsing; false to stop. 00132 */ 00133 virtual bool start_element(const std::string& name, const attrs_type& attrs) = 0; 00134 00135 /** 00136 Override this member function to receive the end_element message. 00137 This member function is called when the parser encounters the closing 00138 of an element. 00139 00140 @param name The name of the element that was closed. 00141 @return You should return true to continue parsing; false to stop. 00142 */ 00143 virtual bool end_element(const std::string& name) = 0; 00144 00145 /** 00146 Override this member function to receive the text message. This 00147 member function is called when the parser encounters text nodes. 00148 00149 @param contents The contents of the text node. 00150 @return You should return true to continue parsing; false to stop. 00151 */ 00152 virtual bool text(const std::string& contents) = 0; 00153 00154 /** 00155 Override this member function to receive the cdata mesage. This 00156 member function is called when the parser encounters a <![CDATA[]]> 00157 section in the XML data. 00158 00159 The default implementation just calls the text() member function to 00160 handle the text inside the CDATA section. 00161 00162 @param contents The contents of the CDATA section. 00163 @return You should return true to continue parsing. 00164 @return Return false if you want to stop. 00165 */ 00166 virtual bool cdata(const std::string& contents); 00167 00168 /** 00169 Override this member function to receive the procesing_instruction 00170 message. This member function will be called when the XML parser 00171 encounters a processing instruction <?target data?>. 00172 00173 The default implementation will ignore processing instructions and 00174 return true. 00175 00176 @param target The target of the processing instruction 00177 @param data The data of the processing instruction. 00178 @return You should return true to continue parsing. 00179 @return Return false if you want to stop. 00180 */ 00181 virtual bool processing_instruction(const std::string& target, const std::string& data); 00182 00183 /** 00184 Override this member function to receive the comment message. This 00185 member function will be called when the XML parser encounters a 00186 comment <!-- contents -->. 00187 00188 The default implementation will ignore XML comments and return true. 00189 00190 @param contents The contents of the XML comment. 00191 @return You should return true to continue parsing. 00192 @return Return false if you want to stop. 00193 */ 00194 virtual bool comment(const std::string& contents); 00195 00196 /** 00197 Override this memeber function to receive parser warnings. The 00198 default behaviour is to ignore warnings. 00199 00200 @param message The warning message from the compiler. 00201 @return You should return true to continue parsing. 00202 @return Return false if you want to stop. 00203 */ 00204 virtual bool warning(const std::string& message); 00205 00206 /** 00207 Set the error message that will be returned from the 00208 get_error_message() member function. If one of your callback 00209 functions returns false and does not first call this memeber 00210 function, "Unknown Error" will be returned from get_error_message(). 00211 00212 @param message The message to return from get_error_message(). 00213 */ 00214 void set_error_message(const char *message); 00215 00216 private: 00217 friend struct impl::epimpl; 00218 impl::epimpl *pimpl_; // private implementation 00219 00220 // Don't allow anyone to copy construct an event_parser or to call the 00221 // assignment operator. It does not make sense to copy a parser if it is 00222 // half way done parsing. Plus, it would be a pain! 00223 event_parser(const event_parser&); 00224 event_parser& operator=(const event_parser&); 00225 }; 00226 00227 } // namespace xml 00228 00229 #endif // _xmlwrapp_event_parser_h_