diff options
Diffstat (limited to 'lib/PPIx/XPath.pm')
| -rw-r--r-- | lib/PPIx/XPath.pm | 265 |
1 files changed, 153 insertions, 112 deletions
diff --git a/lib/PPIx/XPath.pm b/lib/PPIx/XPath.pm index a4e7609..8fc6b95 100644 --- a/lib/PPIx/XPath.pm +++ b/lib/PPIx/XPath.pm @@ -6,67 +6,10 @@ use Carp; use Scalar::Util qw(reftype blessed); use Tree::XPathEngine; use 5.006; -# VERSION +our $VERSION = '2.02'; # VERSION # ABSTRACT: an XPath implementation for the PDOM -=head1 SYNOPSIS - - use PPI; - use PPIx::XPath; - use Tree::XPathEngine; - - my $pdom = PPI::Document->new('some_code.pl'); - my $xpath = Tree::XPathEngine->new(); - my @subs = $xpath->findnodes('//Statement-Sub',$pdom); - my @vars = $xpath->findnodes('//Token-Symbol',$pdom); - -Deprecated interface, backward-compatible with C<PPIx::XPath> version -1: - - use PPIx::XPath; - - my $pxp = PPIx::XPath->new("some_code.pl"); - my @subs = $pxp->match("//Statement::Sub"); - my $vars = $pxp->match("//Token::Symbol"); - -=head1 DESCRIPTION - -This module augments L<PPI>'s classes with the methods required by -L<Tree::XPathEngine>, allowing you to perform complex XPath matches -against any PDOM tree. - -See L<Tree::XPathEngine> for details about its methods. - -=head2 Mapping the PDOM to the XPath data model - -=begin :list - -* Each node in the PDOM is an element as seen by XPath - -* The name of the element is the class name of the node, minus the -initial C<PPI::>, with C<::> replaced by C<->. That is: - - ($xpath_name = substr($pdom_node->class,5)) =~ s/::/-/g; - -* Only "significant" nodes are seen by XPath - -* all scalar-valued accessors of PDOM nodes are visible as attributes - -* "here-docs" contents are I<not> mapped - -=end :list - -=method C<new> - - my $pxp = PPIx::XPath->new("some_code.pl"); - - my $pxp = PPIx::XPath->new($pdom); - -Only useful for the backward-compatible, and deprecated, interface. -Returns an instance of C<PPIx::XPath> tied to the given document. - -=cut sub new { my ($class,$source) = @_; @@ -89,21 +32,6 @@ sub new { return bless {doc=>$doc},$class; } -=method C<clean_xpath_expr> - - my $new_xpath_expr = $pxp->clean_xpath_expr($old_xpath_expr); - -C<PPIx::XPath> version 1.0.0 allowed the use of partial package names -(like C<Token::Number>) as element names: this collides with the axis -specification of proper XPath. For this reason, in newer version of -C<PPIx::XPath>, the element name is the class name of the PDOM node, -minus the initial C<PPI::>, with C<::> replaced by C<-> (like -C<Token-Number>). - -This method replaces all occurrences of PPI package names in the given -string with the new names. - -=cut { my $legacy_names_rx;my %new_name_for; @@ -158,23 +86,6 @@ string with the new names. $legacy_names_rx=qr{$legacy_names_rx}; } -=method C<match> - - my @subs = $pxp->match("//Statement::Sub"); - my $vars = $pxp->match("//Token::Symbol"); - -Only useful for the backward-compatible, and deprecated, -interface. From the document this instance was built against, returns -the nodes that match the given XPath expression. - -You should not use this method, you should call L<< -C<findnodes>|Tree::XPathEngine/findnodes >> instead: - - my $xpath = Tree::XPathEngine->new(); - my @subs = $xpath->findnodes('//Statement-Sub',$pdom); - my @vars = $xpath->findnodes('//Token-Symbol',$pdom); - -=cut sub match { my ($self,$expr) = @_; @@ -184,28 +95,6 @@ sub match { Tree::XPathEngine->new()->findnodes($expr,$self->{doc}); } -=head1 BUGS and LIMITATIONS - -=for :list -* "here-docs" contents are I<not> mapped -* node ordering is slow, because I could not find a way in PPI to -compare two nodes for document order; suggestions are most welcome - -=head1 SEE ALSO - -L<PPI> - -L<Tree::XPathEngine> - -L<http://www.w3.org/TR/xpath> (the XPath specification) - -=head1 AUTHORS - -Dan Brook <cpan@broquaint.com> original author - -Gianni Ceccarelli <dakkar@thenautilus.net> Tree::XPathEngine-based re-implementation - -=cut package PPI::Element; ## no critic(ProhibitMultiplePackages) use strict; @@ -507,3 +396,155 @@ sub xpath_cmp { } 1; + +__END__ + +=pod + +=encoding UTF-8 + +=head1 NAME + +PPIx::XPath - an XPath implementation for the PDOM + +=head1 VERSION + +version 2.02 + +=head1 SYNOPSIS + + use PPI; + use PPIx::XPath; + use Tree::XPathEngine; + + my $pdom = PPI::Document->new('some_code.pl'); + my $xpath = Tree::XPathEngine->new(); + my @subs = $xpath->findnodes('//Statement-Sub',$pdom); + my @vars = $xpath->findnodes('//Token-Symbol',$pdom); + +Deprecated interface, backward-compatible with C<PPIx::XPath> version +1: + + use PPIx::XPath; + + my $pxp = PPIx::XPath->new("some_code.pl"); + my @subs = $pxp->match("//Statement::Sub"); + my $vars = $pxp->match("//Token::Symbol"); + +=head1 DESCRIPTION + +This module augments L<PPI>'s classes with the methods required by +L<Tree::XPathEngine>, allowing you to perform complex XPath matches +against any PDOM tree. + +See L<Tree::XPathEngine> for details about its methods. + +=head2 Mapping the PDOM to the XPath data model + +=over 4 + +=item * + +Each node in the PDOM is an element as seen by XPath + +=item * + +The name of the element is the class name of the node, minus the + +initial C<PPI::>, with C<::> replaced by C<->. That is: + + ($xpath_name = substr($pdom_node->class,5)) =~ s/::/-/g; + +=item * + +Only "significant" nodes are seen by XPath + +=item * + +all scalar-valued accessors of PDOM nodes are visible as attributes + +=item * + +"here-docs" contents are I<not> mapped + +=back + +=head1 METHODS + +=head2 C<new> + + my $pxp = PPIx::XPath->new("some_code.pl"); + + my $pxp = PPIx::XPath->new($pdom); + +Only useful for the backward-compatible, and deprecated, interface. +Returns an instance of C<PPIx::XPath> tied to the given document. + +=head2 C<clean_xpath_expr> + + my $new_xpath_expr = $pxp->clean_xpath_expr($old_xpath_expr); + +C<PPIx::XPath> version 1.0.0 allowed the use of partial package names +(like C<Token::Number>) as element names: this collides with the axis +specification of proper XPath. For this reason, in newer version of +C<PPIx::XPath>, the element name is the class name of the PDOM node, +minus the initial C<PPI::>, with C<::> replaced by C<-> (like +C<Token-Number>). + +This method replaces all occurrences of PPI package names in the given +string with the new names. + +=head2 C<match> + + my @subs = $pxp->match("//Statement::Sub"); + my $vars = $pxp->match("//Token::Symbol"); + +Only useful for the backward-compatible, and deprecated, +interface. From the document this instance was built against, returns +the nodes that match the given XPath expression. + +You should not use this method, you should call L<< +C<findnodes>|Tree::XPathEngine/findnodes >> instead: + + my $xpath = Tree::XPathEngine->new(); + my @subs = $xpath->findnodes('//Statement-Sub',$pdom); + my @vars = $xpath->findnodes('//Token-Symbol',$pdom); + +=head1 BUGS and LIMITATIONS + +=over 4 + +=item * + +"here-docs" contents are I<not> mapped + +=item * + +node ordering is slow, because I could not find a way in PPI to + +compare two nodes for document order; suggestions are most welcome + +=back + +=head1 SEE ALSO + +L<PPI> + +L<Tree::XPathEngine> + +L<http://www.w3.org/TR/xpath> (the XPath specification) + +=head1 AUTHORS + +Dan Brook <cpan@broquaint.com> original author + +Gianni Ceccarelli <dakkar@thenautilus.net> Tree::XPathEngine-based re-implementation + +=head1 COPYRIGHT AND LICENSE + +This software is copyright (c) 2016 by Gianni Ceccarelli <dakkar@thenautilus.net>. + +This is free software; you can redistribute it and/or modify it under +the same terms as the Perl 5 programming language system itself. + +=cut |