summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/XML/LibXML/XPathContext.pod
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl/lib/XML/LibXML/XPathContext.pod')
-rwxr-xr-xMaster/tlpkg/tlperl/lib/XML/LibXML/XPathContext.pod372
1 files changed, 372 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl/lib/XML/LibXML/XPathContext.pod b/Master/tlpkg/tlperl/lib/XML/LibXML/XPathContext.pod
new file mode 100755
index 00000000000..80ceff6435e
--- /dev/null
+++ b/Master/tlpkg/tlperl/lib/XML/LibXML/XPathContext.pod
@@ -0,0 +1,372 @@
+=head1 NAME
+
+XML::LibXML::XPathContext - XPath Evaluation
+
+=head1 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)
+The XML::LibXML::XPathContext class provides an almost complete interface to
+libxml2's XPath implementation. With XML::LibXML::XPathContext is 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.
+
+
+=head1 EXAMPLES
+
+
+=head2 Namespaces
+
+This example demonstrates C<<<<<< 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');
+
+
+=head2 Custom XPath functions
+
+This example demonstrates C<<<<<< 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")]');
+
+
+=head2 Variables
+
+This example demonstrates C<<<<<< 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');
+
+
+=head1 METHODS
+
+=over 4
+
+=item new
+
+ my $xpc = XML::LibXML::XPathContext->new();
+
+Creates a new XML::LibXML::XPathContext object without a context node.
+
+ my $xpc = XML::LibXML::XPathContext->new($node);
+
+Creates a new XML::LibXML::XPathContext object with the context node set to C<<<<<< $node >>>>>>.
+
+
+=item registerNs
+
+ $xpc->registerNs($prefix, $namespace_uri)
+
+Registers namespace C<<<<<< $prefix >>>>>> to C<<<<<< $namespace_uri >>>>>>.
+
+
+=item unregisterNs
+
+ $xpc->unregisterNs($prefix)
+
+Unregisters namespace C<<<<<< $prefix >>>>>>.
+
+
+=item lookupNs
+
+ $uri = $xpc->lookupNs($prefix)
+
+Returns namespace URI registered with C<<<<<< $prefix >>>>>>. If C<<<<<< $prefix >>>>>> is not registered to any namespace URI returns C<<<<<< undef >>>>>>.
+
+
+=item registerVarLookupFunc
+
+ $xpc->registerVarLookupFunc($callback, $data)
+
+Registers variable lookup function C<<<<<< $prefix >>>>>>. The registered function is executed by the XPath engine each time an XPath
+variable is evaluated. It takes three arguments: C<<<<<< $data >>>>>>, variable name, and variable ns-URI and must return one value: a number or
+string or any C<<<<<< XML::LibXML:: >>>>>> object that can be a result of findnodes: Boolean, Literal, Number, Node (e.g.
+Document, Element, etc.), or NodeList. For convenience, simple (non-blessed)
+array references containing only L<<<<<< XML::LibXML::Node >>>>>> objects can be used instead of a L<<<<<< XML::LibXML::NodeList >>>>>>.
+
+
+=item getVarLookupData
+
+ $data = $xpc->getVarLookupData();
+
+Returns the data that have been associated with a variable lookup function
+during a previous call to C<<<<<< registerVarLookupFunc >>>>>>.
+
+
+=item getVarLookupFunc
+
+ $callback = $xpc->getVarLookupFunc();
+
+Returns the variable lookup function previously registered with C<<<<<< registerVarLookupFunc >>>>>>.
+
+
+=item unregisterVarLookupFunc
+
+ $xpc->unregisterVarLookupFunc($name);
+
+Unregisters variable lookup function and the associated lookup data.
+
+
+=item registerFunctionNS
+
+ $xpc->registerFunctionNS($name, $uri, $callback)
+
+Registers an extension function C<<<<<< $name >>>>>> in C<<<<<< $uri >>>>>> namespace. C<<<<<< $callback >>>>>> must be a CODE reference. The arguments of the callback function are either
+simple scalars or C<<<<<< XML::LibXML::* >>>>>> objects depending on the XPath argument types. The function is responsible for
+checking the argument number and types. Result of the callback code must be a
+single value of the following types: a simple scalar (number, string) or an
+arbitrary C<<<<<< XML::LibXML::* >>>>>> object that can be a result of findnodes: Boolean, Literal, Number, Node (e.g.
+Document, Element, etc.), or NodeList. For convenience, simple (non-blessed)
+array references containing only L<<<<<< XML::LibXML::Node >>>>>> objects can be used instead of a L<<<<<< XML::LibXML::NodeList >>>>>>.
+
+
+=item unregisterFunctionNS
+
+ $xpc->unregisterFunctionNS($name, $uri)
+
+Unregisters extension function C<<<<<< $name >>>>>> in C<<<<<< $uri >>>>>> namespace. Has the same effect as passing C<<<<<< undef >>>>>> as C<<<<<< $callback >>>>>> to registerFunctionNS.
+
+
+=item registerFunction
+
+ $xpc->registerFunction($name, $callback)
+
+Same as C<<<<<< registerFunctionNS >>>>>> but without a namespace.
+
+
+=item unregisterFunction
+
+ $xpc->unregisterFunction($name)
+
+Same as C<<<<<< unregisterFunctionNS >>>>>> but without a namespace.
+
+
+=item findnodes
+
+ @nodes = $xpc->findnodes($xpath)
+
+ @nodes = $xpc->findnodes($xpath, $context_node )
+
+ $nodelist = $xpc->findnodes($xpath, $context_node )
+
+Performs the xpath statement on the current node and returns the result as an
+array. In scalar context returns a L<<<<<< XML::LibXML::NodeList >>>>>> object. Optionally, a node may be passed as a second argument to set the
+context node for the query.
+
+The xpath expression can be passed either as a string or or as a L<<<<<< XML::LibXML::XPathExpression >>>>>> object.
+
+
+=item find
+
+ $object = $xpc->find($xpath )
+
+ $object = $xpc->find($xpath, $context_node )
+
+Performs the xpath expression using the current node as the context of the
+expression, and returns the result depending on what type of result the XPath
+expression had. For example, the XPath C<<<<<< 1 * 3 + 52 >>>>>> results in a 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
+the right thing'' in different contexts. Optionally, a node may be passed as a
+second argument to set the context node for the query.
+
+The xpath expression can be passed either as a string or or as a L<<<<<< XML::LibXML::XPathExpression >>>>>> object.
+
+
+=item findvalue
+
+ $value = $xpc->findvalue($xpath )
+
+ $value = $xpc->findvalue($xpath, $context_node )
+
+Is exactly equivalent to:
+
+
+
+ $xpc->find( $xpath, $context_node )->to_literal;
+
+That is, it returns the literal value of the results. This enables you to
+ensure that you get a string back from your search, allowing certain shortcuts.
+This could be used as the equivalent of <xsl:value-of select=``some_xpath''/>.
+Optionally, a node may be passed in the second argument to set the context node
+for the query.
+
+The xpath expression can be passed either as a string or or as a L<<<<<< XML::LibXML::XPathExpression >>>>>> object.
+
+
+=item exists
+
+ $bool = $xpc->exists( $xpath_expression, $context_node );
+
+This method behaves like I<<<<<< findnodes >>>>>>, except that it only returns a boolean value (1 if the expression matches a
+node, 0 otherwise) and may be faster than I<<<<<< findnodes >>>>>>, because the XPath evaluation may stop early on the first match (this is true
+for libxml2 >= 2.6.27).
+
+For XPath expressions that do not return node-set, the method returns true if
+the returned value is a non-zero number or a non-empty string.
+
+
+=item setContextNode
+
+ $xpc->setContextNode($node)
+
+Set the current context node.
+
+
+=item getContextNode
+
+ my $node = $xpc->getContextNode;
+
+Get the current context node.
+
+
+=item setContextPosition
+
+ $xpc->setContextPosition($position)
+
+Set the current context position. By default, this value is -1 (and evaluating
+XPath function C<<<<<< position() >>>>>> in the initial context raises an XPath error), but can be set to any value up
+to context size. This usually only serves to cheat the XPath engine to return
+given position when C<<<<<< position() >>>>>> XPath function is called. Setting this value to -1 restores the default
+behavior.
+
+
+=item getContextPosition
+
+ my $position = $xpc->getContextPosition;
+
+Get the current context position.
+
+
+=item setContextSize
+
+ $xpc->setContextSize($size)
+
+Set the current context size. By default, this value is -1 (and evaluating
+XPath function C<<<<<< last() >>>>>> in the initial context raises an XPath error), but can be set to any
+non-negative value. This usually only serves to cheat the XPath engine to
+return the given value when C<<<<<< last() >>>>>> XPath function is called. If context size is set to 0, position is
+automatically also set to 0. If context size is positive, position is
+automatically set to 1. Setting context size to -1 restores the default
+behavior.
+
+
+=item getContextSize
+
+ my $size = $xpc->getContextSize;
+
+Get the current context size.
+
+
+=item setContextNode
+
+ $xpc->setContextNode($node)
+
+Set the current context node.
+
+
+
+=back
+
+
+=head1 BUGS AND CAVEATS
+
+XML::LibXML::XPathContext objects I<<<<<< 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.
+
+
+=head1 AUTHORS
+
+Ilya Martynov and Petr Pajas, based on XML::LibXML and XML::LibXSLT code by
+Matt Sergeant and Christian Glahn.
+
+
+=head1 HISTORICAL REMARK
+
+Prior to XML::LibXML 1.61 this module was distributed separately for
+maintenance reasons.
+
+=head1 AUTHORS
+
+Matt Sergeant,
+Christian Glahn,
+Petr Pajas
+
+
+=head1 VERSION
+
+1.70
+
+=head1 COPYRIGHT
+
+2001-2007, AxKit.com Ltd.
+
+2002-2006, Christian Glahn.
+
+2006-2009, Petr Pajas.
+
+=cut