Main Page | Class Hierarchy | Class List | File List | Class Members

event_parser.h

Go to the documentation of this file.
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

Generated on Tue Oct 19 12:26:02 2004 for xmlwrapp by doxygen 1.3.6