perldoc > XML::LibXML::XPathContext

man perldoc info pydoc3 ri search

🏷️ NAME

XML::LibXML::XPathContext - XPath Evaluation

🚀 Quick Reference

Use Case	Command	Description
Create XPathContext	XML::LibXML::XPathContext->new()	Create a new context without a node
Create with context node	XML::LibXML::XPathContext->new($node)	Create with initial context node
Register namespace prefix	$xpc->registerNs($prefix, $namespace_uri)	Map prefix to namespace URI
Unregister namespace	$xpc->unregisterNs($prefix)	Remove a namespace mapping
Lookup namespace URI	$xpc->lookupNs($prefix)	Get URI for registered prefix
Find nodes (list)	$xpc->findnodes($xpath, $context_node)	Evaluate XPath, return node list
Find nodes (NodeList)	$xpc->findnodes($xpath, $context_node)	Scalar context returns XML::LibXML::NodeList
Find any XPath result	$xpc->find($xpath, $context_node)	Return number, string, boolean, or node set
Find value (string)	$xpc->findvalue($xpath, $context_node)	Return literal string result
Check node existence	$xpc->exists($xpath_expression, $context_node)	Returns 1 if node matched, 0 otherwise
Register custom XPath function	$xpc->registerFunction($name, $callback)	Extend XPath with a Perl subroutine
Register namespaced function	$xpc->registerFunctionNS($name, $uri, $callback)	Extension function in a namespace
Register variable lookup	$xpc->registerVarLookupFunc($callback, $data)	Resolve XPath variables via callback
Set context node	$xpc->setContextNode($node)	Change the current context node
Set context position	$xpc->setContextPosition($position)	Override position() value
Set context size	$xpc->setContextSize($size)	Override last() value

📋 SYNOPSIS

my $xpc = XML::LibXML::XPathContext->new();
my $xpc = XML::LibXML::XPathContext->new($node);
$xpc->registerNs($prefix, $namespace_uri)
$xpc->unregisterNs($prefix)
$uri = $xpc->lookupNs($prefix)
$xpc->registerVarLookupFunc($callback, $data)
$data = $xpc->getVarLookupData();
$callback = $xpc->getVarLookupFunc();
$xpc->unregisterVarLookupFunc($name);
$xpc->registerFunctionNS($name, $uri, $callback)
$xpc->unregisterFunctionNS($name, $uri)
$xpc->registerFunction($name, $callback)
$xpc->unregisterFunction($name)
@nodes = $xpc->findnodes($xpath)
@nodes = $xpc->findnodes($xpath, $context_node )
$nodelist = $xpc->findnodes($xpath, $context_node )
$object = $xpc->find($xpath )
$object = $xpc->find($xpath, $context_node )
$value = $xpc->findvalue($xpath )
$value = $xpc->findvalue($xpath, $context_node )
$bool = $xpc->exists( $xpath_expression, $context_node );
$xpc->setContextNode($node)
my $node = $xpc->getContextNode;
$xpc->setContextPosition($position)
my $position = $xpc->getContextPosition;
$xpc->setContextSize($size)
my $size = $xpc->getContextSize;
$xpc->setContextNode($node)

📖 DESCRIPTION

The XML::LibXML::XPathContext class provides an almost complete interface to libxml2's XPath implementation. With XML::LibXML::XPathContext, it is possible to evaluate XPath expressions in the context of arbitrary node, context size, and context position, with a user-defined namespace-prefix mapping, custom XPath functions written in Perl, and even a custom XPath variable resolver.

💡 EXAMPLES

🌐 Namespaces

This example demonstrates registerNs() method. It finds all paragraph nodes in an XHTML document.

my $xc = XML::LibXML::XPathContext->new($xhtml_doc);
$xc->registerNs('xhtml', 'http://www.w3.org/1999/xhtml');
my @nodes = $xc->findnodes('//xhtml:p');

🔧 Custom XPath functions

This example demonstrates registerFunction() method by defining a function filtering nodes based on a Perl regular expression:

sub grep_nodes {
  my ($nodelist,$regexp) =  @_;
  my $result = XML::LibXML::NodeList->new;
  for my $node ($nodelist->get_nodelist()) {
    $result->push($node) if $node->textContent =~ $regexp;
  }
  return $result;
};

my $xc = XML::LibXML::XPathContext->new($node);
$xc->registerFunction('grep_nodes', \&grep_nodes);
my @nodes = $xc->findnodes('//section[grep_nodes(para,"\bsearch(ing|es)?\b")]');

📦 Variables

This example demonstrates registerVarLookup() method. We use XPath variables to recycle results of previous evaluations:

sub var_lookup {
  my ($varname,$ns,$data)=@_;
  return $data->{$varname};
}

my $areas = XML::LibXML->new->parse_file('areas.xml');
my $empl = XML::LibXML->new->parse_file('employees.xml');

my $xc = XML::LibXML::XPathContext->new($empl);

my %variables = (
  A => $xc->find('/employees/employee[@salary>10000]'),
  B => $areas->find('/areas/area[district='Brooklyn']/street'),
);

# get names of employees from $A working in an area listed in $B
$xc->registerVarLookupFunc(\&var_lookup, \%variables);
my @nodes = $xc->findnodes('$A[work_area/street = $B]/name');

🧰 METHODS

• new() — Creates a new XML::LibXML::XPathContext object. Without argument: no context node. With argument: sets context node to $node.

  my $xpc = XML::LibXML::XPathContext->new();
  my $xpc = XML::LibXML::XPathContext->new($node);

• registerNs($prefix, $namespace_uri) — Registers namespace $prefix to $namespace_uri.
• unregisterNs($prefix) — Unregisters namespace $prefix.
• lookupNs($prefix) — Returns namespace URI registered with $prefix, or undef if not registered.
• registerVarLookupFunc($callback, $data) — Registers variable lookup function. The callback receives ($data, $varname, $ns_uri) and must return a number, string, or XML::LibXML::* object (Boolean, Literal, Number, Node, NodeList, or array ref of nodes).
• getVarLookupData() — Returns the data associated with the variable lookup function.
• getVarLookupFunc() — Returns the variable lookup function callback.
• unregisterVarLookupFunc($name) — Unregisters variable lookup function and associated data.
• registerFunctionNS($name, $uri, $callback) — Registers extension function $name in $uri namespace. $callback must be a CODE reference. Arguments are scalars or XML::LibXML::* objects. Must return a single value (scalar, XML::LibXML::* object, or array ref of nodes).
• unregisterFunctionNS($name, $uri) — Unregisters extension function $name in $uri namespace.
• registerFunction($name, $callback) — Same as registerFunctionNS but without a namespace.
• unregisterFunction($name) — Same as unregisterFunctionNS but without a namespace.
• findnodes($xpath [, $context_node]) — Performs XPath statement. In list context returns array of nodes; in scalar context returns XML::LibXML::NodeList. $xpath can be a string or XML::LibXML::XPathExpression object.
• find($xpath [, $context_node]) — Performs XPath expression and returns result as appropriate object (XML::LibXML::Number, XML::LibXML::Boolean, XML::LibXML::Literal, or node set).
• findvalue($xpath [, $context_node]) — Equivalent to $xpc->find($xpath)->to_literal. Returns the literal string value of the result.
• exists($xpath_expression, $context_node) — Returns boolean 1 if expression matches a node, 0 otherwise. May be faster than findnodes because evaluation can stop early. For non-node-set expressions, returns true if value is non-zero number or non-empty string.
• setContextNode($node) — Sets the current context node.
• getContextNode() — Gets the current context node.
• setContextPosition($position) — Sets the current context position (default -1, meaning position() raises error). Set to a positive value to override position().
• getContextPosition() — Gets the current context position.
• setContextSize($size) — Sets the current context size (default -1). Set to 0 to also set position to 0; set to positive to set position to 1. Set to -1 to restore default.
• getContextSize() — Gets the current context size.

🐛 BUGS AND CAVEATS

XML::LibXML::XPathContext objects are reentrant, meaning that you can call methods of an XML::LibXML::XPathContext even from XPath extension functions registered with the same object or from a variable lookup function. On the other hand, you should rather avoid registering new extension functions, namespaces and a variable lookup function from within extension functions and a variable lookup function, unless you want to experience untested behavior.

👤 AUTHORS

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

📜 HISTORICAL REMARK

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

👤 AUTHORS

Matt Sergeant, Christian Glahn, Petr Pajas

📌 VERSION

2.0134

©️ COPYRIGHT

2001-2007, AxKit.com Ltd.

2002-2006, Christian Glahn.

2006-2009, Petr Pajas.

📄 LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

🏷️ NAME 🚀 Quick Reference 📋 SYNOPSIS 📖 DESCRIPTION 💡 EXAMPLES 🧰 METHODS 🐛 BUGS AND CAVEATS 👤 AUTHORS 📜 HISTORICAL REMARK 👤 AUTHORS 📌 VERSION ©️ COPYRIGHT 📄 LICENSE