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       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

EXAMPLES

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

METHODS

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

BUGS AND CAVEATS

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

AUTHORS

303       Ilya Martynov and Petr Pajas, based on XML::LibXML and XML::LibXSLT
304       code by Matt Sergeant and Christian Glahn.
305

HISTORICAL REMARK

307       Prior to XML::LibXML 1.61 this module was distributed separately for
308       maintenance reasons.
309

AUTHORS

311       Matt Sergeant, Christian Glahn, Petr Pajas
312

VERSION

314       1.70
315
317       2001-2007, AxKit.com Ltd.
318
319       2002-2006, Christian Glahn.
320
321       2006-2009, Petr Pajas.
322
323
324
325perl v5.12.0                      2009-10-07      XML::LibXML::XPathContext(3)
Impressum