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 @author Peter Jones 00084 */ 00085 bool parse_file(const char *filename); 00086 00087 /** 00088 Parse what ever data that can be read from the given stream. 00089 00090 @param stream The stream to read data from. 00091 @return True if the stream was successfully parsed; false otherwise. 00092 @author Peter Jones 00093 */ 00094 bool parse_stream(std::istream& stream); 00095 00096 /** 00097 Call this function to parse a chunk of xml data. When you are done 00098 feeding the parser chucks of data you need to call the parse_finish 00099 member function. 00100 00101 @param chunk The xml data chuck to parse. 00102 @param length The size of the given data chunk 00103 @return True if the chunk was parsed sucessfully; false otherwise. 00104 @author Peter Jones 00105 */ 00106 bool parse_chunk(const char *chunk, size_type length); 00107 00108 /** 00109 Finish parsing chunked data. You only need to call this member 00110 function is you were parsing chunked xml data via the parse_chunk 00111 member function. 00112 00113 @return True if all parsing was successful; false otherwise. 00114 @author Peter Jones 00115 */ 00116 bool parse_finish(); 00117 00118 /** 00119 If there was an error parsing the XML data, (indicated by one of the 00120 parsing functions returning false), you can call this function to get 00121 a message describing the error. 00122 00123 @return A description of the XML parsing error. 00124 @author Peter Jones 00125 */ 00126 const std::string& get_error_message() const; 00127 00128 protected: 00129 /** 00130 Override this member function to receive the start_element message. 00131 This member function is called when the parser encounters an xml 00132 element. 00133 00134 @param name The name of the element 00135 @param attrs The element's attributes 00136 @return You should return true to continue parsing; false to stop. 00137 @author Peter Jones 00138 */ 00139 virtual bool start_element(const std::string& name, const attrs_type& attrs) = 0; 00140 00141 /** 00142 Override this member function to receive the end_element message. 00143 This member function is called when the parser encounters the closing 00144 of an element. 00145 00146 @param name The name of the element that was closed. 00147 @return You should return true to continue parsing; false to stop. 00148 @author Peter Jones 00149 */ 00150 virtual bool end_element(const std::string& name) = 0; 00151 00152 /** 00153 Override this member function to receive the text message. This 00154 member function is called when the parser encounters text nodes. 00155 00156 @param contents The contents of the text node. 00157 @return You should return true to continue parsing; false to stop. 00158 @author Peter Jones 00159 */ 00160 virtual bool text(const std::string& contents) = 0; 00161 00162 /** 00163 Override this member function to receive the cdata mesage. This 00164 member function is called when the parser encounters a <![CDATA[]]> 00165 section in the XML data. 00166 00167 The default implementation just calls the text() member function to 00168 handle the text inside the CDATA section. 00169 00170 @param contents The contents of the CDATA section. 00171 @return You should return true to continue parsing. 00172 @return Return false if you want to stop. 00173 @author Peter Jones 00174 */ 00175 virtual bool cdata(const std::string& contents); 00176 00177 /** 00178 Override this member function to receive the procesing_instruction 00179 message. This member function will be called when the XML parser 00180 encounters a processing instruction <?target data?>. 00181 00182 The default implementation will ignore processing instructions and 00183 return true. 00184 00185 @param target The target of the processing instruction 00186 @param data The data of the processing instruction. 00187 @return You should return true to continue parsing. 00188 @return Return false if you want to stop. 00189 @author Peter Jones 00190 */ 00191 virtual bool processing_instruction(const std::string& target, const std::string& data); 00192 00193 /** 00194 Override this member function to receive the comment message. This 00195 member function will be called when the XML parser encounters a 00196 comment <!-- contents -->. 00197 00198 The default implementation will ignore XML comments and return true. 00199 00200 @param contents The contents of the XML comment. 00201 @return You should return true to continue parsing. 00202 @return Return false if you want to stop. 00203 @author Peter Jones 00204 */ 00205 virtual bool comment(const std::string& contents); 00206 00207 /** 00208 Override this memeber function to receive parser warnings. The 00209 default behaviour is to ignore warnings. 00210 00211 @param message The warning message from the compiler. 00212 @return You should return true to continue parsing. 00213 @return Return false if you want to stop. 00214 @author Peter Jones 00215 */ 00216 virtual bool warning(const std::string& message); 00217 00218 /** 00219 Set the error message that will be returned from the 00220 get_error_message() member function. If one of your callback 00221 functions returns false and does not first call this memeber 00222 function, "Unknown Error" will be returned from get_error_message(). 00223 00224 @param message The message to return from get_error_message(). 00225 @author Peter Jones 00226 */ 00227 void set_error_message(const char *message); 00228 00229 private: 00230 friend struct impl::epimpl; 00231 impl::epimpl *pimpl_; // private implementation 00232 00233 // Don't allow anyone to copy construct an event_parser or to call the 00234 // assignment operator. It does not make sense to copy a parser if it is 00235 // half way done parsing. Plus, it would be a pain! 00236 event_parser(const event_parser&); 00237 event_parser& operator=(const event_parser&); 00238 }; 00239 00240 } // namespace xml 00241 00242 #endif // _xmlwrapp_event_parser_h_