xmlwrapp Lightweight C++ XML parsing library

tree_parser.h
Go to the documentation of this file.
1 /*
2 * Copyright (C) 2001-2003 Peter J Jones (pjones@pmade.org)
3 * Copyright (C) 2013 Vaclav Slavik <vslavik@gmail.com>
4 * All Rights Reserved
5 *
6 * Redistribution and use in source and binary forms, with or without
7 * modification, are permitted provided that the following conditions
8 * are met:
9 *
10 * 1. Redistributions of source code must retain the above copyright
11 * notice, this list of conditions and the following disclaimer.
12 * 2. Redistributions in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in
14 * the documentation and/or other materials provided with the
15 * distribution.
16 * 3. Neither the name of the Author nor the names of its contributors
17 * may be used to endorse or promote products derived from this software
18 * without specific prior written permission.
19 *
20 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS''
21 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
22 * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
23 * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR
24 * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
25 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
26 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
27 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
28 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
29 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
30 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
31 * SUCH DAMAGE.
32 */
33
34 /**
35 @file
36
37 This file contains the definition of the xml::tree_parser class.
38 */
39
40 #ifndef _xmlwrapp_tree_parser_h_
41 #define _xmlwrapp_tree_parser_h_
42
43 // xmlwrapp includes
44 #include "xmlwrapp/init.h"
45 #include "xmlwrapp/export.h"
46 #include "xmlwrapp/errors.h"
47
48 // standard includes
49 #include <cstddef>
50 #include <string>
51
52 namespace xml
53 {
54
55 // forward declarations
56 class document;
57
58 namespace impl
59 {
60 struct tree_impl;
61 }
62
63 /**
64 The xml::tree_parser class is used to parse an XML document and generate
65 a tree like structure of xml::node objects.
66
67 After constructing a tree_parser, with either a file to parse or some in
68 memory data to parse, you can walk the tree using the xml::node interface.
69
70 @note You probably don't need to use this class directly anymore and
71 can just use the corresponding xml::document constructors.
72 */
73 class XMLWRAPP_API tree_parser
74 {
75 public:
76 typedef std::size_t size_type;
77 /**
78 xml::tree_parser class constructor. Given the name of a file, this
79 constructor will parse that file.
80
81 @param filename The name of the file to parse.
82 @param on_error Handler called to process errors and warnings.
83
84 @since 0.7.0
85 */
86 tree_parser(const char *filename, error_handler& on_error = throw_on_error);
87
88 /**
89 xml::tree_parser class constructor. Given some data and the size of
90 that data, parse that data as XML.
91
92 @param data The XML data to parse.
93 @param size The size of the XML data to parse.
94 @param on_error Handler called to process errors and warnings.
95
96 @since 0.7.0
97 */
98 tree_parser(const char *data, size_type size, error_handler& on_error = throw_on_error);
99
100 /**
101 xml::tree_parser class constructor. Given the name of a file, this
102 constructor will parse that file.
103
104 There are two options for dealing with XML parsing errors. The
105 default it to throw an exception (xml::exception). The other
106 option is to pass false for the allow_exceptions flag. This will
107 prevent an exception from being thrown, instead, a flag will be set
108 that you can test with the operator! member function.
109
110 No matter what option you choose, this constructor may still throw
111 exceptions for memory failure or other non-parsing related failures.
112
113 @param filename The name of the file to parse.
114 @param allow_exceptions Whether or not you want an exception for parsing errors.
115 */
116 tree_parser(const char *filename, bool allow_exceptions);
117
118 /**
119 xml::tree_parser class constructor. Given some data and the size of
120 that data, parse that data as XML. To see if the data was parsed
121 successfully use operator!.
122
123 @param data The XML data to parse.
124 @param size The size of the XML data to parse.
125 @param allow_exceptions Whether or not you want an exception
126 for parsing errors.
127 */
128 tree_parser(const char *data, size_type size, bool allow_exceptions);
129
130 ~tree_parser();
131
132 /**
133 Return error_messages object with errors and warnings collected
134 during parsing.
135
136 @since 0.7.0
137 */
138 const error_messages& messages() const;
139
140 /**
141 Check to see if a xml::tree_parser class is valid. That is, check to
142 see if parsing XML data was successful and the tree_parser holds a
143 good XML node tree.
144
145 @return True if the tree_parser is NOT VALID; false if it is valid.
146 */
147 bool operator!() const;
148
149 /**
150 If operator! indicates that there was an error parsing your XML data,
151 you can use this member function to get the error message that was
152 generated during parsing.
153
154 @return The error message generated during XML parsing.
155
156 @deprecated Use messages() instead.
157 */
158 XMLWRAPP_DEPRECATED("use messages() instead")
159 const std::string& get_error_message() const;
160
161 /**
162 Check to see if there were any warnings from the parser while
163 processing the given XML data. If there were, you may want to send
164 the same document through xmllint or the event_parser to catch and
165 review the warning messages.
166
167 @return True if there were any warnings.
168 @return False if there were no warnings.
169 */
170 bool had_warnings() const;
171
172 /**
173 Get a reference to the xml::document that was generated during the
174 XML parsing. You should make sure to only use a reference to the
175 document to avoid a deep copy.
176
177 @return A reference to the xml::document.
178 */
179 xml::document& get_document();
180
181 /**
182 Get a const reference to the xml::document that was generate during
183 the XML parsing. You should make sure to only use a reference to the
184 document to avoid a deep copy.
185
186 @return A const reference to the xml::document.
187 */
188 const xml::document& get_document() const;
189
190 private:
191 void init(const char *filename, error_handler *on_error);
192 void init(const char *data, size_type size, error_handler *on_error);
193
194 impl::tree_impl *pimpl_; // private implementation
195
196 // Don't allow anyone to copy construct a xml::tree_parser or allow the
197 // assignment operator to be called. It is not very useful to copy a
198 // parser that has already parsed half a document.
199 tree_parser(const tree_parser&);
200 tree_parser& operator=(const tree_parser&);
201 };
202
203 } // end xml namespace
204
205 #endif // _xmlwrapp_tree_parser_h_
xml::tree_parser::tree_parser
tree_parser(const char *filename, bool allow_exceptions)
xml::tree_parser class constructor.
xml::tree_parser::messages
const error_messages & messages() const
Return error_messages object with errors and warnings collected during parsing.
xml::tree_parser::operator!
bool operator!() const
Check to see if a xml::tree_parser class is valid.
errors.h
xml::error_handler
The xml::error_handler class is used to handle libxml2 errors and warnings emitted during parsing,...
Definition: errors.h:85
xml::document
The xml::document class is used to hold the XML tree and various bits of information about it.
Definition: document.h:85
xml::throw_on_error
error_handler_throw_on_error throw_on_error
Error handler object that throws on any error.
xml::tree_parser::tree_parser
tree_parser(const char *data, size_type size, bool allow_exceptions)
xml::tree_parser class constructor.
xml::init
The xml::init class is used to configure the XML parser.
Definition: init.h:64
xml::tree_parser
The xml::tree_parser class is used to parse an XML document and generate a tree like structure of xml...
Definition: tree_parser.h:74
xml::error_messages
The xml::error_messages class is used to store all the error messages which are collected while parsi...
Definition: errors.h:186
xml::tree_parser::tree_parser
tree_parser(const char *filename, error_handler &on_error=throw_on_error)
xml::tree_parser class constructor.
xml
XML library namespace.
Definition: attributes.h:52
xml::tree_parser::tree_parser
tree_parser(const char *data, size_type size, error_handler &on_error=throw_on_error)
xml::tree_parser class constructor.
init.h