1=head1 NAME
2
3XML::LibXML::XPathContext - XPath Evaluation
4
5=head1 SYNOPSIS
6
7  my $xpc = XML::LibXML::XPathContext->new();
8  my $xpc = XML::LibXML::XPathContext->new($node);
9  $xpc->registerNs($prefix, $namespace_uri)
10  $xpc->unregisterNs($prefix)
11  $uri = $xpc->lookupNs($prefix)
12  $xpc->registerVarLookupFunc($callback, $data)
13  $data = $xpc->getVarLookupData();
14  $callback = $xpc->getVarLookupFunc();
15  $xpc->unregisterVarLookupFunc($name);
16  $xpc->registerFunctionNS($name, $uri, $callback)
17  $xpc->unregisterFunctionNS($name, $uri)
18  $xpc->registerFunction($name, $callback)
19  $xpc->unregisterFunction($name)
20  @nodes = $xpc->findnodes($xpath)
21  @nodes = $xpc->findnodes($xpath, $context_node )
22  $nodelist = $xpc->findnodes($xpath, $context_node )
23  $object = $xpc->find($xpath )
24  $object = $xpc->find($xpath, $context_node )
25  $value = $xpc->findvalue($xpath )
26  $value = $xpc->findvalue($xpath, $context_node )
27  $bool = $xpc->exists( $xpath_expression, $context_node );
28  $xpc->setContextNode($node)
29  my $node = $xpc->getContextNode;
30  $xpc->setContextPosition($position)
31  my $position = $xpc->getContextPosition;
32  $xpc->setContextSize($size)
33  my $size = $xpc->getContextSize;
34  $xpc->setContextNode($node)
35
36=head1 DESCRIPTION
37
38The XML::LibXML::XPathContext class provides an almost complete interface to
39libxml2's XPath implementation. With XML::LibXML::XPathContext, it is possible
40to evaluate XPath expressions in the context of arbitrary node, context size,
41and context position, with a user-defined namespace-prefix mapping, custom
42XPath functions written in Perl, and even a custom XPath variable resolver.
43
44
45=head1 EXAMPLES
46
47
48=head2 Namespaces
49
50This example demonstrates C<<<<<< registerNs() >>>>>> method. It finds all paragraph nodes in an XHTML document.
51
52
53
54  my $xc = XML::LibXML::XPathContext->new($xhtml_doc);
55  $xc->registerNs('xhtml', 'http://www.w3.org/1999/xhtml');
56  my @nodes = $xc->findnodes('//xhtml:p');
57
58
59=head2 Custom XPath functions
60
61This example demonstrates C<<<<<< registerFunction() >>>>>> method by defining a function filtering nodes based on a Perl regular
62expression:
63
64
65
66  sub grep_nodes {
67    my ($nodelist,$regexp) =  @_;
68    my $result = XML::LibXML::NodeList->new;
69    for my $node ($nodelist->get_nodelist()) {
70      $result->push($node) if $node->textContent =~ $regexp;
71    }
72    return $result;
73  };
74
75  my $xc = XML::LibXML::XPathContext->new($node);
76  $xc->registerFunction('grep_nodes', \&grep_nodes);
77  my @nodes = $xc->findnodes('//section[grep_nodes(para,"\bsearch(ing|es)?\b")]');
78
79
80=head2 Variables
81
82This example demonstrates C<<<<<< registerVarLookup() >>>>>> method. We use XPath variables to recycle results of previous evaluations:
83
84
85
86  sub var_lookup {
87    my ($varname,$ns,$data)=@_;
88    return $data->{$varname};
89  }
90
91  my $areas = XML::LibXML->new->parse_file('areas.xml');
92  my $empl = XML::LibXML->new->parse_file('employees.xml');
93
94  my $xc = XML::LibXML::XPathContext->new($empl);
95
96  my %variables = (
97    A => $xc->find('/employees/employee[@salary>10000]'),
98    B => $areas->find('/areas/area[district='Brooklyn']/street'),
99  );
100
101  # get names of employees from $A working in an area listed in $B
102  $xc->registerVarLookupFunc(\&var_lookup, \%variables);
103  my @nodes = $xc->findnodes('$A[work_area/street = $B]/name');
104
105
106=head1 METHODS
107
108=over 4
109
110=item new
111
112  my $xpc = XML::LibXML::XPathContext->new();
113
114Creates a new XML::LibXML::XPathContext object without a context node.
115
116  my $xpc = XML::LibXML::XPathContext->new($node);
117
118Creates a new XML::LibXML::XPathContext object with the context node set to C<<<<<< $node >>>>>>.
119
120
121=item registerNs
122
123  $xpc->registerNs($prefix, $namespace_uri)
124
125Registers namespace C<<<<<< $prefix >>>>>> to C<<<<<< $namespace_uri >>>>>>.
126
127
128=item unregisterNs
129
130  $xpc->unregisterNs($prefix)
131
132Unregisters namespace C<<<<<< $prefix >>>>>>.
133
134
135=item lookupNs
136
137  $uri = $xpc->lookupNs($prefix)
138
139Returns namespace URI registered with C<<<<<< $prefix >>>>>>. If C<<<<<< $prefix >>>>>> is not registered to any namespace URI returns C<<<<<< undef >>>>>>.
140
141
142=item registerVarLookupFunc
143
144  $xpc->registerVarLookupFunc($callback, $data)
145
146Registers variable lookup function C<<<<<< $callback >>>>>>. The registered function is executed by the XPath engine each time an XPath
147variable is evaluated. It takes three arguments: C<<<<<< $data >>>>>>, variable name, and variable ns-URI and must return one value: a number or
148string or any C<<<<<< XML::LibXML:: >>>>>> object that can be a result of findnodes: Boolean, Literal, Number, Node (e.g.
149Document, Element, etc.), or NodeList. For convenience, simple (non-blessed)
150array references containing only L<<<<<< XML::LibXML::Node >>>>>> objects can be used instead of an L<<<<<< XML::LibXML::NodeList >>>>>>.
151
152
153=item getVarLookupData
154
155  $data = $xpc->getVarLookupData();
156
157Returns the data that have been associated with a variable lookup function
158during a previous call to C<<<<<< registerVarLookupFunc >>>>>>.
159
160
161=item getVarLookupFunc
162
163  $callback = $xpc->getVarLookupFunc();
164
165Returns the variable lookup function previously registered with C<<<<<< registerVarLookupFunc >>>>>>.
166
167
168=item unregisterVarLookupFunc
169
170  $xpc->unregisterVarLookupFunc($name);
171
172Unregisters variable lookup function and the associated lookup data.
173
174
175=item registerFunctionNS
176
177  $xpc->registerFunctionNS($name, $uri, $callback)
178
179Registers an extension function C<<<<<< $name >>>>>> in C<<<<<< $uri >>>>>> namespace. C<<<<<< $callback >>>>>> must be a CODE reference. The arguments of the callback function are either
180simple scalars or C<<<<<< XML::LibXML::* >>>>>> objects depending on the XPath argument types. The function is responsible for
181checking the argument number and types. Result of the callback code must be a
182single value of the following types: a simple scalar (number, string) or an
183arbitrary C<<<<<< XML::LibXML::* >>>>>> object that can be a result of findnodes: Boolean, Literal, Number, Node (e.g.
184Document, Element, etc.), or NodeList. For convenience, simple (non-blessed)
185array references containing only L<<<<<< XML::LibXML::Node >>>>>> objects can be used instead of a L<<<<<< XML::LibXML::NodeList >>>>>>.
186
187
188=item unregisterFunctionNS
189
190  $xpc->unregisterFunctionNS($name, $uri)
191
192Unregisters extension function C<<<<<< $name >>>>>> in C<<<<<< $uri >>>>>> namespace. Has the same effect as passing C<<<<<< undef >>>>>> as C<<<<<< $callback >>>>>> to registerFunctionNS.
193
194
195=item registerFunction
196
197  $xpc->registerFunction($name, $callback)
198
199Same as C<<<<<< registerFunctionNS >>>>>> but without a namespace.
200
201
202=item unregisterFunction
203
204  $xpc->unregisterFunction($name)
205
206Same as C<<<<<< unregisterFunctionNS >>>>>> but without a namespace.
207
208
209=item findnodes
210
211  @nodes = $xpc->findnodes($xpath)
212
213  @nodes = $xpc->findnodes($xpath, $context_node )
214
215  $nodelist = $xpc->findnodes($xpath, $context_node )
216
217Performs the xpath statement on the current node and returns the result as an
218array. In scalar context, returns an L<<<<<< XML::LibXML::NodeList >>>>>> object. Optionally, a node may be passed as a second argument to set the
219context node for the query.
220
221The xpath expression can be passed either as a string, or as a L<<<<<< XML::LibXML::XPathExpression >>>>>> object.
222
223
224=item find
225
226  $object = $xpc->find($xpath )
227
228  $object = $xpc->find($xpath, $context_node )
229
230Performs the xpath expression using the current node as the context of the
231expression, and returns the result depending on what type of result the XPath
232expression had. For example, the XPath C<<<<<< 1 * 3 + 	      52 >>>>>> results in an L<<<<<< XML::LibXML::Number >>>>>> object being returned. Other expressions might return a L<<<<<< XML::LibXML::Boolean >>>>>> object, or a L<<<<<< XML::LibXML::Literal >>>>>> object (a string). Each of those objects uses Perl's overload feature to ``do
233the right thing'' in different contexts. Optionally, a node may be passed as a
234second argument to set the context node for the query.
235
236The xpath expression can be passed either as a string, or as a L<<<<<< XML::LibXML::XPathExpression >>>>>> object.
237
238
239=item findvalue
240
241  $value = $xpc->findvalue($xpath )
242
243  $value = $xpc->findvalue($xpath, $context_node )
244
245Is exactly equivalent to:
246
247
248
249  $xpc->find( $xpath, $context_node )->to_literal;
250
251That is, it returns the literal value of the results. This enables you to
252ensure that you get a string back from your search, allowing certain shortcuts.
253This could be used as the equivalent of <xsl:value-of select=``some_xpath''/>.
254Optionally, a node may be passed in the second argument to set the context node
255for the query.
256
257The xpath expression can be passed either as a string, or as a L<<<<<< XML::LibXML::XPathExpression >>>>>> object.
258
259
260=item exists
261
262  $bool = $xpc->exists( $xpath_expression, $context_node );
263
264This method behaves like I<<<<<< findnodes >>>>>>, except that it only returns a boolean value (1 if the expression matches a
265node, 0 otherwise) and may be faster than I<<<<<< findnodes >>>>>>, because the XPath evaluation may stop early on the first match (this is true
266for libxml2 >= 2.6.27).
267
268For XPath expressions that do not return node-set, the method returns true if
269the returned value is a non-zero number or a non-empty string.
270
271
272=item setContextNode
273
274  $xpc->setContextNode($node)
275
276Set the current context node.
277
278
279=item getContextNode
280
281  my $node = $xpc->getContextNode;
282
283Get the current context node.
284
285
286=item setContextPosition
287
288  $xpc->setContextPosition($position)
289
290Set the current context position. By default, this value is -1 (and evaluating
291XPath function C<<<<<< position() >>>>>> in the initial context raises an XPath error), but can be set to any value up
292to context size. This usually only serves to cheat the XPath engine to return
293given position when C<<<<<< position() >>>>>> XPath function is called. Setting this value to -1 restores the default
294behavior.
295
296
297=item getContextPosition
298
299  my $position = $xpc->getContextPosition;
300
301Get the current context position.
302
303
304=item setContextSize
305
306  $xpc->setContextSize($size)
307
308Set the current context size. By default, this value is -1 (and evaluating
309XPath function C<<<<<< last() >>>>>> in the initial context raises an XPath error), but can be set to any
310non-negative value. This usually only serves to cheat the XPath engine to
311return the given value when C<<<<<< last() >>>>>> XPath function is called. If context size is set to 0, position is
312automatically also set to 0. If context size is positive, position is
313automatically set to 1. Setting context size to -1 restores the default
314behavior.
315
316
317=item getContextSize
318
319  my $size = $xpc->getContextSize;
320
321Get the current context size.
322
323
324=item setContextNode
325
326  $xpc->setContextNode($node)
327
328Set the current context node.
329
330
331
332=back
333
334
335=head1 BUGS AND CAVEATS
336
337XML::LibXML::XPathContext objects I<<<<<< are >>>>>> reentrant, meaning that you can call methods of an XML::LibXML::XPathContext
338even from XPath extension functions registered with the same object or from a
339variable lookup function. On the other hand, you should rather avoid
340registering new extension functions, namespaces and a variable lookup function
341from within extension functions and a variable lookup function, unless you want
342to experience untested behavior.
343
344
345=head1 AUTHORS
346
347Ilya Martynov and Petr Pajas, based on XML::LibXML and XML::LibXSLT code by
348Matt Sergeant and Christian Glahn.
349
350
351=head1 HISTORICAL REMARK
352
353Prior to XML::LibXML 1.61 this module was distributed separately for
354maintenance reasons.
355
356=head1 AUTHORS
357
358Matt Sergeant,
359Christian Glahn,
360Petr Pajas
361
362
363=head1 VERSION
364
3652.0207
366
367=head1 COPYRIGHT
368
3692001-2007, AxKit.com Ltd.
370
3712002-2006, Christian Glahn.
372
3732006-2009, Petr Pajas.
374
375=cut
376
377
378=head1 LICENSE
379
380This program is free software; you can redistribute it and/or modify it under
381the same terms as Perl itself.
382
383