xmlwrapp Lightweight C++ XML parsing library

event_parser.h
Go to the documentation of this file.
1 /*
2 * Copyright (C) 2001-2003 Peter J Jones (pjones@pmade.org)
3 * All Rights Reserved
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met:
8 *
9 * 1. Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 * 2. Redistributions in binary form must reproduce the above copyright
12 * notice, this list of conditions and the following disclaimer in
13 * the documentation and/or other materials provided with the
14 * distribution.
15 * 3. Neither the name of the Author nor the names of its contributors
16 * may be used to endorse or promote products derived from this software
17 * without specific prior written permission.
18 *
19 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS''
20 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
21 * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
22 * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR
23 * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
24 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
25 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
26 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
27 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
28 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
29 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30 * SUCH DAMAGE.
31 */
32
33 /**
34 @file
35
36 This file contains the definition of the xml::event_parser class.
37 */
38
39 #ifndef _xmlwrapp_event_parser_h_
40 #define _xmlwrapp_event_parser_h_
41
42 // xmlwrapp includes
43 #include "xmlwrapp/init.h"
44 #include "xmlwrapp/export.h"
45
46 // standard includes
47 #include <cstddef>
48 #include <string>
49 #include <iosfwd>
50 #include <map>
51
52 namespace xml
53 {
54
55 namespace impl
56 {
57 struct epimpl; // forward declaration of private implementation
58 }
59
60 /**
61 The xml::event_parser is used to parse an XML document by calling member
62 functions when certain things in the XML document are parsed. In order to
63 use this class you derive a sub-class from it and override the protected
64 virtual functions.
65 */
66 class XMLWRAPP_API event_parser
67 {
68 public:
69 /// a type for holding XML node attributes
70 typedef std::map<std::string, std::string> attrs_type;
71 /// size type
72 typedef std::size_t size_type;
73
74 /// Default constructor.
75 event_parser();
76
77 virtual ~event_parser();
78
79 /**
80 Call this member function to parse the given file.
81
82 @param filename The name of the file to parse.
83 @return True if the file was successfully parsed; false otherwise.
84 */
85 bool parse_file(const char *filename);
86
87 /**
88 Parse what ever data that can be read from the given stream.
89
90 @param stream The stream to read data from.
91 @return True if the stream was successfully parsed; false otherwise.
92 */
93 bool parse_stream(std::istream& stream);
94
95 /**
96 Call this function to parse a chunk of xml data. When you are done
97 feeding the parser chucks of data you need to call the parse_finish
98 member function.
99
100 @param chunk The xml data chuck to parse.
101 @param length The size of the given data chunk
102 @return True if the chunk was parsed successfully; false otherwise.
103 */
104 bool parse_chunk(const char *chunk, size_type length);
105
106 /**
107 Finish parsing chunked data. You only need to call this member
108 function is you were parsing chunked xml data via the parse_chunk
109 member function.
110
111 @return True if all parsing was successful; false otherwise.
112 */
113 bool parse_finish();
114
115 /**
116 If there was an error parsing the XML data, (indicated by one of the
117 parsing functions returning false), you can call this function to get
118 a message describing the error.
119
120 @return A description of the XML parsing error.
121 */
122 const std::string& get_error_message() const;
123
124 protected:
125 /**
126 Override this member function to receive the start_element message.
127 This member function is called when the parser encounters an xml
128 element.
129
130 @param name The name of the element
131 @param attrs The element's attributes
132 @return You should return true to continue parsing; false to stop.
133 */
134 virtual bool start_element(const std::string& name, const attrs_type& attrs) = 0;
135
136 /**
137 Override this member function to receive the end_element message.
138 This member function is called when the parser encounters the closing
139 of an element.
140
141 @param name The name of the element that was closed.
142 @return You should return true to continue parsing; false to stop.
143 */
144 virtual bool end_element(const std::string& name) = 0;
145
146 /**
147 Override this member function to receive the text message. This
148 member function is called when the parser encounters text nodes.
149
150 @param contents The contents of the text node.
151 @return You should return true to continue parsing; false to stop.
152 */
153 virtual bool text(const std::string& contents) = 0;
154
155 /**
156 Override this member function to receive the cdata message. This
157 member function is called when the parser encounters a <![CDATA[]]>
158 section in the XML data.
159
160 The default implementation just calls the text() member function to
161 handle the text inside the CDATA section.
162
163 @param contents The contents of the CDATA section.
164 @return You should return true to continue parsing.
165 @return Return false if you want to stop.
166 */
167 virtual bool cdata(const std::string& contents);
168
169 /**
170 Override this member function to receive the processing_instruction
171 message. This member function will be called when the XML parser
172 encounters a processing instruction <?target data?>.
173
174 The default implementation will ignore processing instructions and
175 return true.
176
177 @param target The target of the processing instruction
178 @param data The data of the processing instruction.
179 @return You should return true to continue parsing.
180 @return Return false if you want to stop.
181 */
182 virtual bool processing_instruction(const std::string& target, const std::string& data);
183
184 /**
185 Override this member function to receive the comment message. This
186 member function will be called when the XML parser encounters a
187 comment <!-- contents -->.
188
189 The default implementation will ignore XML comments and return true.
190
191 @param contents The contents of the XML comment.
192 @return You should return true to continue parsing.
193 @return Return false if you want to stop.
194 */
195 virtual bool comment(const std::string& contents);
196
197 /**
198 Override this member function to receive parser warnings. The
199 default behaviour is to ignore warnings.
200
201 @param message The warning message from the compiler.
202 @return You should return true to continue parsing.
203 @return Return false if you want to stop.
204 */
205 virtual bool warning(const std::string& message);
206
207 /**
208 Set the error message that will be returned from the
209 get_error_message() member function. If one of your callback
210 functions returns false and does not first call this member
211 function, "Unknown Error" will be returned from get_error_message().
212
213 @param message The message to return from get_error_message().
214 */
215 void set_error_message(const char *message);
216
217 private:
218 friend struct impl::epimpl;
219 impl::epimpl *pimpl_; // private implementation
220
221 // Don't allow anyone to copy construct an event_parser or to call the
222 // assignment operator. It does not make sense to copy a parser if it is
223 // half way done parsing. Plus, it would be a pain!
224 event_parser(const event_parser&);
225 event_parser& operator=(const event_parser&);
226 };
227
228 } // namespace xml
229
230 #endif // _xmlwrapp_event_parser_h_
xml::event_parser::cdata
virtual bool cdata(const std::string &contents)
Override this member function to receive the cdata message.
xml::event_parser::text
virtual bool text(const std::string &contents)=0
Override this member function to receive the text message.
xml::event_parser::set_error_message
void set_error_message(const char *message)
Set the error message that will be returned from the get_error_message() member function.
xml::event_parser::parse_file
bool parse_file(const char *filename)
Call this member function to parse the given file.
xml::event_parser::processing_instruction
virtual bool processing_instruction(const std::string &target, const std::string &data)
Override this member function to receive the processing_instruction message.
xml::event_parser::event_parser
event_parser()
Default constructor.
xml::event_parser::parse_stream
bool parse_stream(std::istream &stream)
Parse what ever data that can be read from the given stream.
xml::event_parser::comment
virtual bool comment(const std::string &contents)
Override this member function to receive the comment message.
xml::event_parser::end_element
virtual bool end_element(const std::string &name)=0
Override this member function to receive the end_element message.
xml
XML library namespace.
Definition: attributes.h:52
xml::event_parser::get_error_message
const std::string & get_error_message() const
If there was an error parsing the XML data, (indicated by one of the parsing functions returning fals...
xml::event_parser::attrs_type
std::map< std::string, std::string > attrs_type
a type for holding XML node attributes
Definition: event_parser.h:70
xml::event_parser::parse_chunk
bool parse_chunk(const char *chunk, size_type length)
Call this function to parse a chunk of xml data.
xml::event_parser::size_type
std::size_t size_type
size type
Definition: event_parser.h:72
xml::event_parser::warning
virtual bool warning(const std::string &message)
Override this member function to receive parser warnings.
xml::event_parser::start_element
virtual bool start_element(const std::string &name, const attrs_type &attrs)=0
Override this member function to receive the start_element message.
xml::event_parser
The xml::event_parser is used to parse an XML document by calling member functions when certain thing...
Definition: event_parser.h:67
init.h
xml::event_parser::parse_finish
bool parse_finish()
Finish parsing chunked data.