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 $xpc->setContextNode($node)
30 my $node = $xpc->getContextNode;
31 $xpc->setContextPosition($position)
32 my $position = $xpc->getContextPosition;
33 $xpc->setContextSize($size)
34 my $size = $xpc->getContextSize;
35 $xpc->setContextNode($node)
36
38 The XML::LibXML::XPathContext class provides an almost complete inter‐
39 face to libxml2's XPath implementation. With XML::LibXML::XPathContext
40 is is possible to evaluate XPath expressions in the context of arbi‐
41 trary node, context size, and context position, with a user-defined
42 namespace-prefix mapping, custom XPath functions written in Perl, and
43 even a custom XPath variable resolver.
44
46 Namespaces
47 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 func‐
58 tion filtering nodes based on a Perl regular expression:
59 sub grep_nodes {
61 my ($nodelist,$regexp) = @_;
62 my $result = XML::LibXML::NodeList->new;
63 for my $node ($nodelist->get_nodelist()) {
64 $result->push($node) if $node->textContent =~ $regexp;
65 }
66 return $result;
67 };
68 my $xc = XML::LibXML::XPathContext->new($node);
70 $xc->registerFunction('grep_nodes', \&grep_nodes);
71 my @nodes = $xc->findnodes('//section[grep_nodes(para,"\bsearch(ing⎪es)?\b")]');
72 Variables
74 This example demonstrates registerVarLookup() method. We use XPath
76 variables to recycle results of previous evaluations:
77 sub var_lookup {
79 my ($varname,$ns,$data)=@_;
80 return $data->{$varname};
81 }
82 my $areas = XML::LibXML->new->parse_file('areas.xml');
84 my $empl = XML::LibXML->new->parse_file('employees.xml');
85 my $xc = XML::LibXML::XPathContext->new($empl);
87 my %variables = (
89 A => $xc->find('/employees/employee[@salary>10000]'),
90 B => $areas->find('/areas/area[district='Brooklyn']/street'),
91 );
92 # get names of employees from $A woring in an area listed in $B
94 $xc->registerVarLookupFunc(\&var_lookup, \%variables);
95 my @nodes = $xc->findnodes('$A[work_area/street = $B]/name');
96
98 new
99 my $xpc = XML::LibXML::XPathContext->new();
100 Creates a new XML::LibXML::XPathContext object without a context
102 node.
103 my $xpc = XML::LibXML::XPathContext->new($node);
105 Creates a new XML::LibXML::XPathContext object with the context
107 node set to $node.
108 registerNs
110 $xpc->registerNs($prefix, $namespace_uri)
111 Registers namespace $prefix to $namespace_uri.
113 unregisterNs
115 $xpc->unregisterNs($prefix)
116 Unregisters namespace $prefix.
118 lookupNs
120 $uri = $xpc->lookupNs($prefix)
121 Returns namespace URI registered with $prefix. If $prefix is not
123 registered to any namespace URI returns undef.
124 registerVarLookupFunc
126 $xpc->registerVarLookupFunc($callback, $data)
127 Registers variable lookup function $prefix. The registered function
129 is executed by the XPath engine each time an XPath variable is
130 evaluated. It takes three arguments: $data, variable name, and
131 variable ns-URI and must return one value: a number or string or
132 any XML::LibXML:: object that can be a result of findnodes: Bool‐
133 ean, Literal, Number, Node (e.g. Document, Element, etc.), or
134 NodeList. For convenience, simple (non-blessed) array references
135 containing only XML::LibXML::Node objects can be used instead of a
136 XML::LibXML::NodeList.
137 getVarLookupData
139 $data = $xpc->getVarLookupData();
140 Returns the data that have been associated with a variable lookup
142 function during a previous call to registerVarLookupFunc.
143 getVarLookupFunc
145 $callback = $xpc->getVarLookupFunc();
146 Returns the variable lookup function previously registered with
148 registerVarLookupFunc.
149 unregisterVarLookupFunc
151 $xpc->unregisterVarLookupFunc($name);
152 Unregisters variable lookup function and the associated lookup
154 data.
155 registerFunctionNS
157 $xpc->registerFunctionNS($name, $uri, $callback)
158 Registers an extension function $name in $uri namespace. $callback
160 must be a CODE reference. The arguments of the callback function
161 are either simple scalars or XML::LibXML::* objects depending on
162 the XPath argument types. The function is responsible for checking
163 the argument number and types. Result of the callback code must be
164 a single value of the following types: a simple scalar (number,
165 string) or an arbitrary XML::LibXML::* object that can be a result
166 of findnodes: Boolean, Literal, Number, Node (e.g. Document, Ele‐
167 ment, etc.), or NodeList. For convenience, simple (non-blessed)
168 array references containing only XML::LibXML::Node objects can be
169 used instead of a XML::LibXML::NodeList.
170 unregisterFunctionNS
172 $xpc->unregisterFunctionNS($name, $uri)
173 Unregisters extension function $name in $uri namespace. Has the
175 same effect as passing undef as $callback to registerFunctionNS.
176 registerFunction
178 $xpc->registerFunction($name, $callback)
179 Same as registerFunctionNS but without a namespace.
181 unregisterFunction
183 $xpc->unregisterFunction($name)
184 Same as unregisterFunctionNS but without a namespace.
186 findnodes
188 @nodes = $xpc->findnodes($xpath)
189 @nodes = $xpc->findnodes($xpath, $context_node )
191 $nodelist = $xpc->findnodes($xpath, $context_node )
193 Performs the xpath statement on the current node and returns the
195 result as an array. In scalar context returns a
196 XML::LibXML::NodeList object. Optionally, a node may be passed as a
197 second argument to set the context node for the query.
198 find
200 $object = $xpc->find($xpath )
201 $object = $xpc->find($xpath, $context_node )
203 Performs the xpath expression using the current node as the context
205 of the expression, and returns the result depending on what type of
206 result the XPath expression had. For example, the XPath 1 * 3 + 52
207 results in a XML::LibXML::Number object being returned. Other
208 expressions might return a XML::LibXML::Boolean object, or a
209 XML::LibXML::Literal object (a string). Each of those objects uses
210 Perl's overload feature to ``do the right thing'' in different con‐
211 texts. Optionally, a node may be passed as a second argument to set
212 the context node for the query.
213 findvalue
215 $value = $xpc->findvalue($xpath )
216 $value = $xpc->findvalue($xpath, $context_node )
218 Is exactly equivalent to:
220 $node->find( $xpath )->to_literal;
222 That is, it returns the literal value of the results. This enables
224 you to ensure that you get a string back from your search, allowing
225 certain shortcuts. This could be used as the equivalent of
226 <xsl:value-of select=``some_xpath''/>. Optionally, a node may be
227 passed in the second argument to set the context node for the
228 query.
229 setContextNode
231 $xpc->setContextNode($node)
232 Set the current context node.
234 getContextNode
236 my $node = $xpc->getContextNode;
237 Get the current context node.
239 setContextPosition
241 $xpc->setContextPosition($position)
242 Set the current context position. By default, this value is -1 (and
244 evaluating XPath function position() in the initial context raises
245 an XPath error), but can be set to any value up to context size.
246 This usually only serves to cheat the XPath engine to return given
247 position when position() XPath function is called. Setting this
248 value to -1 restores the default behavior.
249 getContextPosition
251 my $position = $xpc->getContextPosition;
252 Get the current context position.
254 setContextSize
256 $xpc->setContextSize($size)
257 Set the current context size. By default, this value is -1 (and
259 evaluating XPath function last() in the initial context raises an
260 XPath error), but can be set to any non-negative value. This usu‐
261 ally only serves to cheat the XPath engine to return the given
262 value when last() XPath function is called. If context size is set
263 to 0, position is automatically also set to 0. If context size is
264 positive, position is automatically set to 1. Setting context size
265 to -1 restores the default behavior.
266 getContextSize
268 my $size = $xpc->getContextSize;
269 Get the current context size.
271 setContextNode
273 $xpc->setContextNode($node)
274 Set the current context node.
276
278 XML::LibXML::XPathContext objects are reentrant, meaning that you can
279 call methods of an XML::LibXML::XPathContext even from XPath extension
280 functions registered with the same object or from a variable lookup
281 function. On the other hand, you should rather avoid registering new
282 extension functions, namespaces and a variable lookup function from
283 within extension functions and a variable lookup function, unless you
284 want to experience untested behavior.
285
287 Ilya Martynov and Petr Pajas, based on XML::LibXML and XML::LibXSLT
288 code by Matt Sergeant and Christian Glahn.
289
291 Prior to XML::LibXML 1.61 this module was distributed separately for
292 maintanance reasons.
293
295 Matt Sergeant, Christian Glahn, Petr Pajas,
296
298 1.62
299
301 2001-2006, AxKit.com Ltd; 2002-2006 Christian Glahn; 2006 Petr Pajas,
302 All rights reserved.
303perl v5.8.8 2006-11-17 XML::LibXML::XPathContext(3)