1XML::LibXML::XPathConteUxste(r3)Contributed Perl DocumenXtMaLt:i:oLnibXML::XPathContext(3)
2
3
4

NAME

6       XML::LibXML::XPathContext - XPath Evaluation
7

SYNOPSIS

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

DESCRIPTION

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

EXAMPLES

47   Namespaces
48       This example demonstrates "registerNs()" method. It finds all paragraph
49       nodes in an XHTML document.
50
51         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
55   Custom XPath functions
56       This example demonstrates "registerFunction()" method by defining a
57       function filtering nodes based on a Perl regular expression:
58
59         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
68         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
72   Variables
73       This example demonstrates "registerVarLookup()" method. We use XPath
74       variables to recycle results of previous evaluations:
75
76         sub var_lookup {
77           my ($varname,$ns,$data)=@_;
78           return $data->{$varname};
79         }
80
81         my $areas = XML::LibXML->new->parse_file('areas.xml');
82         my $empl = XML::LibXML->new->parse_file('employees.xml');
83
84         my $xc = XML::LibXML::XPathContext->new($empl);
85
86         my %variables = (
87           A => $xc->find('/employees/employee[@salary>10000]'),
88           B => $areas->find('/areas/area[district='Brooklyn']/street'),
89         );
90
91         # 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

METHODS

96       new
97             my $xpc = XML::LibXML::XPathContext->new();
98
99           Creates a new XML::LibXML::XPathContext object without a context
100           node.
101
102             my $xpc = XML::LibXML::XPathContext->new($node);
103
104           Creates a new XML::LibXML::XPathContext object with the context
105           node set to $node.
106
107       registerNs
108             $xpc->registerNs($prefix, $namespace_uri)
109
110           Registers namespace $prefix to $namespace_uri.
111
112       unregisterNs
113             $xpc->unregisterNs($prefix)
114
115           Unregisters namespace $prefix.
116
117       lookupNs
118             $uri = $xpc->lookupNs($prefix)
119
120           Returns namespace URI registered with $prefix. If $prefix is not
121           registered to any namespace URI returns "undef".
122
123       registerVarLookupFunc
124             $xpc->registerVarLookupFunc($callback, $data)
125
126           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
136       getVarLookupData
137             $data = $xpc->getVarLookupData();
138
139           Returns the data that have been associated with a variable lookup
140           function during a previous call to "registerVarLookupFunc".
141
142       getVarLookupFunc
143             $callback = $xpc->getVarLookupFunc();
144
145           Returns the variable lookup function previously registered with
146           "registerVarLookupFunc".
147
148       unregisterVarLookupFunc
149             $xpc->unregisterVarLookupFunc($name);
150
151           Unregisters variable lookup function and the associated lookup
152           data.
153
154       registerFunctionNS
155             $xpc->registerFunctionNS($name, $uri, $callback)
156
157           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
169       unregisterFunctionNS
170             $xpc->unregisterFunctionNS($name, $uri)
171
172           Unregisters extension function $name in $uri namespace. Has the
173           same effect as passing "undef" as $callback to registerFunctionNS.
174
175       registerFunction
176             $xpc->registerFunction($name, $callback)
177
178           Same as "registerFunctionNS" but without a namespace.
179
180       unregisterFunction
181             $xpc->unregisterFunction($name)
182
183           Same as "unregisterFunctionNS" but without a namespace.
184
185       findnodes
186             @nodes = $xpc->findnodes($xpath)
187
188             @nodes = $xpc->findnodes($xpath, $context_node )
189
190             $nodelist = $xpc->findnodes($xpath, $context_node )
191
192           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
197           The xpath expression can be passed either as a string, or as a
198           XML::LibXML::XPathExpression object.
199
200       find
201             $object = $xpc->find($xpath )
202
203             $object = $xpc->find($xpath, $context_node )
204
205           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
215           The xpath expression can be passed either as a string, or as a
216           XML::LibXML::XPathExpression object.
217
218       findvalue
219             $value = $xpc->findvalue($xpath )
220
221             $value = $xpc->findvalue($xpath, $context_node )
222
223           Is exactly equivalent to:
224
225             $xpc->find( $xpath, $context_node )->to_literal;
226
227           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
234           The xpath expression can be passed either as a string, or as a
235           XML::LibXML::XPathExpression object.
236
237       exists
238             $bool = $xpc->exists( $xpath_expression, $context_node );
239
240           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
245           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
249       setContextNode
250             $xpc->setContextNode($node)
251
252           Set the current context node.
253
254       getContextNode
255             my $node = $xpc->getContextNode;
256
257           Get the current context node.
258
259       setContextPosition
260             $xpc->setContextPosition($position)
261
262           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
269       getContextPosition
270             my $position = $xpc->getContextPosition;
271
272           Get the current context position.
273
274       setContextSize
275             $xpc->setContextSize($size)
276
277           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
286       getContextSize
287             my $size = $xpc->getContextSize;
288
289           Get the current context size.
290
291       setContextNode
292             $xpc->setContextNode($node)
293
294           Set the current context node.
295

BUGS AND CAVEATS

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

AUTHORS

306       Ilya Martynov and Petr Pajas, based on XML::LibXML and XML::LibXSLT
307       code by Matt Sergeant and Christian Glahn.
308

HISTORICAL REMARK

310       Prior to XML::LibXML 1.61 this module was distributed separately for
311       maintenance reasons.
312

AUTHORS

314       Matt Sergeant, Christian Glahn, Petr Pajas
315

VERSION

317       2.0201
318
320       2001-2007, AxKit.com Ltd.
321
322       2002-2006, Christian Glahn.
323
324       2006-2009, Petr Pajas.
325

LICENSE

327       This program is free software; you can redistribute it and/or modify it
328       under the same terms as Perl itself.
329
330
331
332perl v5.30.0                      2019-07-26      XML::LibXML::XPathContext(3)
Impressum