summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authordakkar <dakkar@thenautilus.net>2016-08-29 16:49:43 +0100
committerdakkar <dakkar@thenautilus.net>2016-08-29 16:50:42 +0100
commit4f1cac99ee7d88b95db6065fc9412553bcffcf36 (patch)
treed4df8cad51f276a98434316f14a90a47a5ad0ad3
parentre-arrange POD (we're now using Pod::Weaver) (diff)
downloadPPIx-XPath-4f1cac99ee7d88b95db6065fc9412553bcffcf36.tar.gz
PPIx-XPath-4f1cac99ee7d88b95db6065fc9412553bcffcf36.tar.bz2
PPIx-XPath-4f1cac99ee7d88b95db6065fc9412553bcffcf36.zip
pod & comments
-rw-r--r--Changes1
-rw-r--r--lib/PPIx/XPath.pm59
2 files changed, 55 insertions, 5 deletions
diff --git a/Changes b/Changes
index 7f70ed9..ae0d039 100644
--- a/Changes
+++ b/Changes
@@ -1,3 +1,4 @@
{{$NEXT}}
- fixed example code as per RT#116737, thanks Alastair Cooke
+ - more documentation
- switched to Dist::Zilla
diff --git a/lib/PPIx/XPath.pm b/lib/PPIx/XPath.pm
index 4853fe6..a4e7609 100644
--- a/lib/PPIx/XPath.pm
+++ b/lib/PPIx/XPath.pm
@@ -57,6 +57,15 @@ initial C<PPI::>, with C<::> replaced by C<->. That is:
=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 {
@@ -80,9 +89,22 @@ sub new {
return bless {doc=>$doc},$class;
}
-# PPIx::XPath 1.0.0 allowed the use of partial package names as node names;
-# this collides with the axis specification of proper XPath.
-# Here we change the "old-style" node names into the new names
+=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;
sub clean_xpath_expr {
@@ -95,6 +117,7 @@ sub new {
my @PPI_Packs;
# taken from Devel::Symdump
+ # breadth-first search of packages under C<PPI>
my @packages=('PPI');
while (my $pack=shift(@packages)) {
my %pack_symbols = do {
@@ -102,15 +125,20 @@ sub new {
%{*{"$pack\::"}}
};
while (my ($key,$val)=each(%pack_symbols)) {
+ # that {HASH} lookup is special for typeglobs, so we have
+ # to alias a local typeglob to make it work
local *ENTRY=$val;
+ # does this symbol table entry look like a sub-package?
if (defined $val && defined *ENTRY{HASH} && $key=~/::$/
&& $key !~ /^::/
&& $key ne 'main::' && $key ne '<none>::') {
+ # add it to the search list
my $p = "$pack\::$key";$p =~ s{::$}{};
push @packages,$p;
- $p =~ s{^PPI::}{};
+ # and add it to the map of names
+ $p =~ s{^PPI::}{};
next unless $p=~/::/;
my $newname=$p;
@@ -120,12 +148,34 @@ sub new {
}
}
}
+
+ # @PPI_Packs now contains all the old-style names, build a regex
+ # to match them (the sort is important, we want to match longer
+ # names first!)
$legacy_names_rx='\b('.join(q{|},
sort {length($b) <=> length($a)} @PPI_Packs
).')\b';
$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) = @_;
@@ -134,7 +184,6 @@ sub match {
Tree::XPathEngine->new()->findnodes($expr,$self->{doc});
}
-
=head1 BUGS and LIMITATIONS
=for :list