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