xmlwrapp Lightweight C++ XML parsing library

xpath.h
Go to the documentation of this file.
1 /*
2 * Copyright (C) 2011 Jonas Weber (mail@jonasw.de)
3 * 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 files contains definitions for XPath-related classes.
38 */
39
40 #ifndef _xmlwrapp_xpath_h_
41 #define _xmlwrapp_xpath_h_
42
43
44 // xmlwrapp includes
45 #include "xmlwrapp/init.h"
46 #include "xmlwrapp/errors.h"
47 #include "xmlwrapp/export.h"
48 #include "xmlwrapp/nodes_view.h"
49
50 #include <string>
51
52 namespace xml
53 {
54
55 class node;
56 class document;
57
58 namespace impl
59 {
60 struct xpath_context_impl;
61 }
62
63 /**
64 Context in which XPath expressions can be evaluated.
65
66 The context object can (and indeed, should) be reused for multiple XPath
67 queries on the same document.
68
69 @since 0.8.0
70 */
71 class XMLWRAPP_API xpath_context
72 {
73 public:
74 /**
75 Create XPath context for the given document.
76
77 @param doc Document for the context to work with. The lifetime
78 of the document must be greater than the context object's.
79 */
80 xpath_context(const xml::document& doc);
81
82 ~xpath_context();
83
84 /**
85 Register a namespace with prefix.
86
87 This function has to be called in order to be able to evaluate XPath
88 expressions that match nodes in a non-default namespace. Must be
89 called before evaluate().
90
91 @param prefix The prefix used in XPath expressions for the namespace.
92 (Notice that it doesn't have to be the same prefix as
93 used in the XML document.)
94 @param href URI of the namespace used in the document.
95 */
96 void register_namespace(const std::string& prefix, const std::string& href);
97
98 /**
99 Execute an XPath query in the document scope.
100
101 Calling this function is exactly equivalent to using the overload
102 taking an xml::node argument with xml::document::get_root_node().
103
104 In particular, this implies that if you need to modify nodes in the
105 returned set, you can simple use the non-const overload taking
106 xml::node& argument and pass xml::document::get_root_node() result to
107 it.
108 */
109 const_nodes_view evaluate(const std::string& expr,
110 error_handler& on_error = throw_on_error);
111
112 /**
113 Execute an XPath query in the scope of XML node @a n.
114
115 @param expr XPath expression.
116 @param n The context node for the expression.
117 @param on_error Error handler throwing an exception if an error occurs
118 during the expression evaluation. Notice that absence of matches
119 isn't considered to be an error, in this case the function just
120 returns an empty set.
121
122 @return Const set of matching nodes.
123 */
124 const_nodes_view evaluate(const std::string& expr,
125 const xml::node& n,
126 error_handler& on_error = throw_on_error);
127
128 /**
129 Execute an XPath query in the scope of XML node @a n.
130
131 This overload is identical to the one taking const @a n argument,
132 except that it returns a set of nodes that can be modified.
133 */
134 nodes_view evaluate(const std::string& expr,
135 xml::node& n,
136 error_handler& on_error = throw_on_error);
137
138 private:
139 // no copying
140 xpath_context(const xpath_context&);
141 xpath_context& operator=(const xpath_context&);
142
143 impl::xpath_context_impl *pimpl_;
144 };
145
146 } // namespace xml
147
148 #endif // _xmlwrapp_xpath_h_
xml::const_nodes_view
This class implements a read-only view of XML nodes.
Definition: nodes_view.h:253
xml::xpath_context::evaluate
const_nodes_view evaluate(const std::string &expr, error_handler &on_error=throw_on_error)
Execute an XPath query in the document scope.
errors.h
xml::xpath_context::register_namespace
void register_namespace(const std::string &prefix, const std::string &href)
Register a namespace with prefix.
xml::error_handler
The xml::error_handler class is used to handle libxml2 errors and warnings emitted during parsing,...
Definition: errors.h:85
xml::xpath_context::evaluate
const_nodes_view evaluate(const std::string &expr, const xml::node &n, error_handler &on_error=throw_on_error)
Execute an XPath query in the scope of XML node n.
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::xpath_context
Context in which XPath expressions can be evaluated.
Definition: xpath.h:72
xml::throw_on_error
error_handler_throw_on_error throw_on_error
Error handler object that throws on any error.
nodes_view.h
xml
XML library namespace.
Definition: attributes.h:52
xml::xpath_context::xpath_context
xpath_context(const xml::document &doc)
Create XPath context for the given document.
xml::xpath_context::evaluate
nodes_view evaluate(const std::string &expr, xml::node &n, error_handler &on_error=throw_on_error)
Execute an XPath query in the scope of XML node n.
xml::node
The xml::node class is used to hold information about one XML node.
Definition: node.h:89
xml::nodes_view
This class implements a view of XML nodes.
Definition: nodes_view.h:79
init.h