1XML::LibXML::XPathConteUxste(r3)Contributed Perl DocumenXtMaLt:i:oLnibXML::XPathContext(3)
2
6 XML::LibXML::XPathContext - XPath Evaluation
7
9 my $xpc = XML::LibXML::XPathContext->new();
10 my $xpc = XML::LibXML::XPathContext->new($node);
11 $xpc->registerNs($prefix, $namespace_uri)
12 $xpc->unregisterNs($prefix)
13 $uri = $xpc->lookupNs($prefix)
14 $xpc->registerVarLookupFunc($callback, $data)
15 $data = $xpc->getVarLookupData();
16 $callback = $xpc->getVarLookupFunc();
17 $xpc->unregisterVarLookupFunc($name);
18 $xpc->registerFunctionNS($name, $uri, $callback)
19 $xpc->unregisterFunctionNS($name, $uri)
20 $xpc->registerFunction($name, $callback)
21 $xpc->unregisterFunction($name)
22 @nodes = $xpc->findnodes($xpath)
23 @nodes = $xpc->findnodes($xpath, $context_node )
24 $nodelist = $xpc->findnodes($xpath, $context_node )
25 $object = $xpc->find($xpath )
26 $object = $xpc->find($xpath, $context_node )
27 $value = $xpc->findvalue($xpath )
28 $value = $xpc->findvalue($xpath, $context_node )
29 $bool = $xpc->exists( $xpath_expression, $context_node );
30 $xpc->setContextNode($node)
31 my $node = $xpc->getContextNode;
32 $xpc->setContextPosition($position)
33 my $position = $xpc->getContextPosition;
34 $xpc->setContextSize($size)
35 my $size = $xpc->getContextSize;
36 $xpc->setContextNode($node)
37
39 The XML::LibXML::XPathContext class provides an almost complete
40 interface to libxml2's XPath implementation. With
41 XML::LibXML::XPathContext, it is possible to evaluate XPath expressions
42 in the context of arbitrary node, context size, and context position,
43 with a user-defined namespace-prefix mapping, custom XPath functions
44 written in Perl, and even a custom XPath variable resolver.
45
47 Namespaces
48 This example demonstrates "registerNs()" method. It finds all paragraph
49 nodes in an XHTML document.
50 my $xc = XML::LibXML::XPathContext->new($xhtml_doc);
52 $xc->registerNs('xhtml', 'http://www.w3.org/1999/xhtml');
53 my @nodes = $xc->findnodes('//xhtml:p');
54 Custom XPath functions
56 This example demonstrates "registerFunction()" method by defining a
57 function filtering nodes based on a Perl regular expression:
58 sub grep_nodes {
60 my ($nodelist,$regexp) = @_;
61 my $result = XML::LibXML::NodeList->new;
62 for my $node ($nodelist->get_nodelist()) {
63 $result->push($node) if $node->textContent =~ $regexp;
64 }
65 return $result;
66 };
67 my $xc = XML::LibXML::XPathContext->new($node);
69 $xc->registerFunction('grep_nodes', \&grep_nodes);
70 my @nodes = $xc->findnodes('//section[grep_nodes(para,"\bsearch(ing|es)?\b")]');
71 Variables
73 This example demonstrates "registerVarLookup()" method. We use XPath
74 variables to recycle results of previous evaluations:
75 sub var_lookup {
77 my ($varname,$ns,$data)=@_;
78 return $data->{$varname};
79 }
80 my $areas = XML::LibXML->new->parse_file('areas.xml');
82 my $empl = XML::LibXML->new->parse_file('employees.xml');
83 my $xc = XML::LibXML::XPathContext->new($empl);
85 my %variables = (
87 A => $xc->find('/employees/employee[@salary>10000]'),
88 B => $areas->find('/areas/area[district='Brooklyn']/street'),
89 );
90 # get names of employees from $A working in an area listed in $B
92 $xc->registerVarLookupFunc(\&var_lookup, \%variables);
93 my @nodes = $xc->findnodes('$A[work_area/street = $B]/name');
94
96 new
97 my $xpc = XML::LibXML::XPathContext->new();
98 Creates a new XML::LibXML::XPathContext object without a context
100 node.
101 my $xpc = XML::LibXML::XPathContext->new($node);
103 Creates a new XML::LibXML::XPathContext object with the context
105 node set to $node.
106 registerNs
108 $xpc->registerNs($prefix, $namespace_uri)
109 Registers namespace $prefix to $namespace_uri.
111 unregisterNs
113 $xpc->unregisterNs($prefix)
114 Unregisters namespace $prefix.
116 lookupNs
118 $uri = $xpc->lookupNs($prefix)
119 Returns namespace URI registered with $prefix. If $prefix is not
121 registered to any namespace URI returns "undef".
122 registerVarLookupFunc
124 $xpc->registerVarLookupFunc($callback, $data)
125 Registers variable lookup function $prefix. The registered function
127 is executed by the XPath engine each time an XPath variable is
128 evaluated. It takes three arguments: $data, variable name, and
129 variable ns-URI and must return one value: a number or string or
130 any "XML::LibXML::" object that can be a result of findnodes:
131 Boolean, Literal, Number, Node (e.g. Document, Element, etc.), or
132 NodeList. For convenience, simple (non-blessed) array references
133 containing only XML::LibXML::Node objects can be used instead of an
134 XML::LibXML::NodeList.
135 getVarLookupData
137 $data = $xpc->getVarLookupData();
138 Returns the data that have been associated with a variable lookup
140 function during a previous call to "registerVarLookupFunc".
141 getVarLookupFunc
143 $callback = $xpc->getVarLookupFunc();
144 Returns the variable lookup function previously registered with
146 "registerVarLookupFunc".
147 unregisterVarLookupFunc
149 $xpc->unregisterVarLookupFunc($name);
150 Unregisters variable lookup function and the associated lookup
152 data.
153 registerFunctionNS
155 $xpc->registerFunctionNS($name, $uri, $callback)
156 Registers an extension function $name in $uri namespace. $callback
158 must be a CODE reference. The arguments of the callback function
159 are either simple scalars or "XML::LibXML::*" objects depending on
160 the XPath argument types. The function is responsible for checking
161 the argument number and types. Result of the callback code must be
162 a single value of the following types: a simple scalar (number,
163 string) or an arbitrary "XML::LibXML::*" object that can be a
164 result of findnodes: Boolean, Literal, Number, Node (e.g.
165 Document, Element, etc.), or NodeList. For convenience, simple
166 (non-blessed) array references containing only XML::LibXML::Node
167 objects can be used instead of a XML::LibXML::NodeList.
168 unregisterFunctionNS
170 $xpc->unregisterFunctionNS($name, $uri)
171 Unregisters extension function $name in $uri namespace. Has the
173 same effect as passing "undef" as $callback to registerFunctionNS.
174 registerFunction
176 $xpc->registerFunction($name, $callback)
177 Same as "registerFunctionNS" but without a namespace.
179 unregisterFunction
181 $xpc->unregisterFunction($name)
182 Same as "unregisterFunctionNS" but without a namespace.
184 findnodes
186 @nodes = $xpc->findnodes($xpath)
187 @nodes = $xpc->findnodes($xpath, $context_node )
189 $nodelist = $xpc->findnodes($xpath, $context_node )
191 Performs the xpath statement on the current node and returns the
193 result as an array. In scalar context, returns an
194 XML::LibXML::NodeList object. Optionally, a node may be passed as a
195 second argument to set the context node for the query.
196 The xpath expression can be passed either as a string, or as a
198 XML::LibXML::XPathExpression object.
199 find
201 $object = $xpc->find($xpath )
202 $object = $xpc->find($xpath, $context_node )
204 Performs the xpath expression using the current node as the context
206 of the expression, and returns the result depending on what type of
207 result the XPath expression had. For example, the XPath "1 * 3 +
208 52" results in an XML::LibXML::Number object being returned. Other
209 expressions might return a XML::LibXML::Boolean object, or a
210 XML::LibXML::Literal object (a string). Each of those objects uses
211 Perl's overload feature to ``do the right thing'' in different
212 contexts. Optionally, a node may be passed as a second argument to
213 set the context node for the query.
214 The xpath expression can be passed either as a string, or as a
216 XML::LibXML::XPathExpression object.
217 findvalue
219 $value = $xpc->findvalue($xpath )
220 $value = $xpc->findvalue($xpath, $context_node )
222 Is exactly equivalent to:
224 $xpc->find( $xpath, $context_node )->to_literal;
226 That is, it returns the literal value of the results. This enables
228 you to ensure that you get a string back from your search, allowing
229 certain shortcuts. This could be used as the equivalent of
230 <xsl:value-of select=``some_xpath''/>. Optionally, a node may be
231 passed in the second argument to set the context node for the
232 query.
233 The xpath expression can be passed either as a string, or as a
235 XML::LibXML::XPathExpression object.
236 exists
238 $bool = $xpc->exists( $xpath_expression, $context_node );
239 This method behaves like findnodes, except that it only returns a
241 boolean value (1 if the expression matches a node, 0 otherwise) and
242 may be faster than findnodes, because the XPath evaluation may stop
243 early on the first match (this is true for libxml2 >= 2.6.27).
244 For XPath expressions that do not return node-set, the method
246 returns true if the returned value is a non-zero number or a non-
247 empty string.
248 setContextNode
250 $xpc->setContextNode($node)
251 Set the current context node.
253 getContextNode
255 my $node = $xpc->getContextNode;
256 Get the current context node.
258 setContextPosition
260 $xpc->setContextPosition($position)
261 Set the current context position. By default, this value is -1 (and
263 evaluating XPath function "position()" in the initial context
264 raises an XPath error), but can be set to any value up to context
265 size. This usually only serves to cheat the XPath engine to return
266 given position when "position()" XPath function is called. Setting
267 this value to -1 restores the default behavior.
268 getContextPosition
270 my $position = $xpc->getContextPosition;
271 Get the current context position.
273 setContextSize
275 $xpc->setContextSize($size)
276 Set the current context size. By default, this value is -1 (and
278 evaluating XPath function "last()" in the initial context raises an
279 XPath error), but can be set to any non-negative value. This
280 usually only serves to cheat the XPath engine to return the given
281 value when "last()" XPath function is called. If context size is
282 set to 0, position is automatically also set to 0. If context size
283 is positive, position is automatically set to 1. Setting context
284 size to -1 restores the default behavior.
285 getContextSize
287 my $size = $xpc->getContextSize;
288 Get the current context size.
290 setContextNode
292 $xpc->setContextNode($node)
293 Set the current context node.
295
297 XML::LibXML::XPathContext objects are reentrant, meaning that you can
298 call methods of an XML::LibXML::XPathContext even from XPath extension
299 functions registered with the same object or from a variable lookup
300 function. On the other hand, you should rather avoid registering new
301 extension functions, namespaces and a variable lookup function from
302 within extension functions and a variable lookup function, unless you
303 want to experience untested behavior.
304
306 Ilya Martynov and Petr Pajas, based on XML::LibXML and XML::LibXSLT
307 code by Matt Sergeant and Christian Glahn.
308
310 Prior to XML::LibXML 1.61 this module was distributed separately for
311 maintenance reasons.
312
314 Matt Sergeant, Christian Glahn, Petr Pajas
315
317 2.0205
318
320 2001-2007, AxKit.com Ltd.
321 2002-2006, Christian Glahn.
323 2006-2009, Petr Pajas.
325
327 This program is free software; you can redistribute it and/or modify it
328 under the same terms as Perl itself.
329perl v5.32.0 2020-07-28 XML::LibXML::XPathContext(3)