[perl-xml-cvs] CVS: XML-LibXML-XPathContext XPathContext.pm,1.7,1.8

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

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

Modified Files:
	XPathContext.pm 
Log Message:
Mention node locking and add examples to POD documentation


Index: XPathContext.pm
===================================================================
RCS file: /cvsroot/perl-xml/XML-LibXML-XPathContext/XPathContext.pm,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -d -r1.7 -r1.8
--- XPathContext.pm	20 Mar 2003 14:51:45 -0000	1.7
+++ XPathContext.pm	25 Mar 2003 21:05:33 -0000	1.8
@@ -114,7 +114,7 @@
     $xc->registerNs($prefix, $namespace_uri);
     $xc->registerFunction($name, sub { ... });
     $xc->registerFunctionNS($name, $namespace_uri, sub { ... });
-    $xc->registerVariableLookup(sub { ... },$data);
+    $xc->registerVariableLookup(sub { ... }, $data);
 
     my @nodes = $xc->findnodes($xpath);
     my $nodelist = $xc->findnodes($xpath);
@@ -129,9 +129,60 @@
 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
 
-=head2 Methods
+=over 4
+
+=item 1
+
+registering namespace prefixes,
+
+=item 2
+
+defining XPath functions in Perl,
+
+=item 3
+
+defining variable lookup functions in Perl.
+
+=back
+
+=head1 EXAMPLES
+
+=head2 Find all paragraph nodes in XHTML document
+
+This example demonstrates I<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');
+
+=head2 Find all nodes which names match a Perl regular expression
+
+This example demonstrates I<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")');
+
+=head1 METHODS
 
 =over 4
 
@@ -211,15 +262,27 @@
 
 =back
 
+=head1 BUGS AND CAVEATS
+
+L<XML::LibXML::XPathContext> objects are not reentrant. It means you
+cannot register a Perl function with a L<XML::LibXML::XPathContext>
+object if this Perl function uses itself same
+L<XML::LibXML::XPathContext> object internally.
+
+For example following code will not work:
+
+    my $xc = XML::LibXML::XPathContext->new($node);
+    $xc->registerFunction('func', sub { $xc->findvalue('1') });
+    my $result = $xc->findvalue('func()');
+
 =head1 AUTHORS
 
-Based on L<XML::LibXML> code by Matt Sergeant and Christian Glahn.
+Based on L<XML::LibXML> and L<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.
 
 =head1 SUPPORT