xmlwrapp
xmlwrapp/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 /**
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_