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