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