[perl-xml-cvs] CVS: XML-LibXML-XPathContext README,1.1.1.1,1.2

[Ilya M. <m_...@us...>]

Update of /cvsroot/perl-xml/XML-LibXML-XPathContext
In directory sc8-pr-cvs1:/tmp/cvs-serv27879

Modified Files:
	README 
Log Message:
Updated


Index: README
===================================================================
RCS file: /cvsroot/perl-xml/XML-LibXML-XPathContext/README,v
retrieving revision 1.1.1.1
retrieving revision 1.2
diff -u -d -r1.1.1.1 -r1.2
--- README	14 Mar 2003 14:32:04 -0000	1.1.1.1
+++ README	26 Mar 2003 21:24:26 -0000	1.2
@@ -7,19 +7,90 @@
         my $xc = XML::LibXML::XPathContext->new($node);
 
         $xc->registerNs($prefix, $namespace_uri);
+        $xc->registerFunction($name, sub { ... });
+        $xc->registerFunctionNS($name, $namespace_uri, sub { ... });
+        $xc->registerVarLookupFunc(sub { ... }, $data);
+
+        $xc->unregisterNs($prefix);
+        $xc->unregisterFunction($name);
+        $xc->unregisterFunctionNS($name, $namespace_uri);
+        $xc->unregisterVarLookupFunc($name);
 
         my @nodes = $xc->findnodes($xpath);
         my $nodelist = $xc->findnodes($xpath);
         my $result = $xc->find($xpath);
         my $value = $xc->findvalue($xpath);
 
+        my $node = $xc->getContextNode;
+        $xc->setContextNode($node);
+
 DESCRIPTION
     This module augments XML::LibXML by providing Perl interface to
     libxml2's xmlXPathContext structure. Besides just performing xpath
     statements on XML::LibXML's node trees it allows redefining certaint
-    aspects of xpath engine.
+    aspects of XPath engine. This modules allows
 
-  Methods
+    1   registering namespace prefixes,
+
+    2   defining XPath functions in Perl,
+
+    3   defining variable lookup functions in Perl.
+
+EXAMPLES
+  Find all paragraph nodes in XHTML document
+    This example demonstrates *registerNs()* usage:
+
+        my $xc = XML::LibXML::XPathContext->new($xhtml_doc);
+        $xc->registerNs('xhtml', 'http://www.w3.org/1999/xhtml');
+        my @nodes = $xc->findnodes('//xhtml:p');
+
+  Find all nodes whose names match a Perl regular expression
+    This example demonstrates *registerFunction()* usage:
+
+        my $perlmatch = sub {
+            die "Not a nodelist"
+                unless $_[0]->isa('XML::LibXML::NodeList');
+            die "Missing a regular expression"
+                unless defined $_[1];
+
+            my $nodelist = XML::LibXML::NodeList->new;
+            my $i = 0;
+            while(my $node = $_[0]->get_node($i)) {
+                $nodelist->push($node) if $node->nodeName =~ $_[1];
+                $i ++;
+            }
+
+            return $nodelist;
+        };
+
+        my $xc = XML::LibXML::XPathContext->new($node);
+        $xc->registerFunction('perlmatch', $perlmatch);
+        my @nodes = $xc->findnodes('perlmatch(//*, "foo|bar")');
+
+  Use XPath variables to recycle results of previous evaluations
+    This example demonstrates *registerVarLookup()* usage:
+
+        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 %results =
+          (
+           A => $xc->find('/employees/employee[@salary>10000]'),
+           B => $areas->find('/areas/area[district='Brooklyn']/street'),
+          );
+
+        # get names of employees from $A woring in an area listed in $B
+        $xc->registerVarLookupFunc(\&var_lookup,\%results);
+        my @nodes = $xc->findnodes('$A[work_area/street = $B]/name');
+
+METHODS
     new($node)
         Creates a new XML::LibXML::XPathContext object with current node set
         to *$node*.
@@ -27,6 +98,50 @@
     registerNs($prefix, $namespace_uri)
         Registers namespace *$prefix* to *$namespace_uri*.
 
+    unregisterNs($prefix)
+        Unregisters namespace *$prefix*.
+
+    registerVarLookupFunc($callback, $data)
+        Registers variable lookup function *$prefix*. The registered
+        function is executed by the XPath engine each time an XPath variable
+        is evaluated. It takes three arguments: *$data*, variable name, and
+        variable ns-URI and must return one value: a number or string or any
+        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 XML::LibXML::Node objects can be used instead of a
+        XML::LibXML::NodeList.
+
+    getVarLookupData()
+        Returns the data that have been associated with a variable lookup
+        function during a previous call to *registerVarLookupFunc*.
+
+    unregisterVarLookupFunc()
+        Unregisters variable lookup function and the associated lookup data.
+
+    registerFunctionNS($name, $uri, $callback)
+        Registers an extension function *$name* in *$uri* namespace.
+        *$callback* must be a CODE reference. The arguments of the callback
+        function are either simple scalars or XML::LibXML::NodeList 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 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 XML::LibXML::Node objects can be
+        used instead of a XML::LibXML::NodeList.
+
+    unregisterFunctionNS($name, $uri)
+        Unregisters extension function *$name* in *$uri* namespace. Has the
+        same effect as passing "undef" as *$callback* to registerFunctionNS.
+
+    registerFunction($name, $callback)
+        Same as *registerFunctionNS* but without a namespace.
+
+    unregisterFunction($name)
+        Same as *unregisterFunctionNS* but without a namespace.
+
     findnodes($xpath)
         Performs the xpath statement on the current node and returns the
         result as an array. In scalar context returns a
@@ -52,14 +167,31 @@
         certain shortcuts. This could be used as the equivalent of
         <xsl:value-of select="some_xpath"/>.
 
+    getContextNode()
+        Get the current context node.
+
+    setContextNode($node)
+        Set the current context node.
+
+BUGS AND CAVEATS
+    XML::LibXML::XPathContext objects are not reentrant. It means you cannot
+    register a Perl function with a XML::LibXML::XPathContext object if this
+    Perl function uses itself the same XML::LibXML::XPathContext object
+    internally.
+
+    For example, the following code will not work:
+
+        my $xc = XML::LibXML::XPathContext->new($node);
+        $xc->registerFunction('func', sub { $xc->findvalue('1') });
+        my $result = $xc->findvalue('func()');
+
 AUTHORS
-    Based on XML::LibXML code by Matt Sergeant and Christian Glahn.
+    Based on XML::LibXML and XML::XSLT code by Matt Sergeant and Christian
+    Glahn.
 
     Maintained by Ilya Martynov and Petr Pajas.
 
-    Copyright 2001-2002 AxKit.com Ltd, All rights reserved.
-
-    Copyright 2003 Ilya Martynov, All rights reserved.
+    Copyright 2001-2003 AxKit.com Ltd, All rights reserved.
 
 SUPPORT
     For suggestions, bugreports etc. you may contact the maintainers
@@ -69,5 +201,5 @@
     the perl XML mailing list (per...@li...).
 
 SEE ALSO
-    XML::LibXML
+    XML::LibXML, XML::XSLT