xmlwrapp
Main Page
Related Pages
Namespaces
Classes
Files
File List
File Members
xmlwrapp
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_
Generated on Sat Mar 16 2013 12:46:44 for xmlwrapp by
1.8.3.1