NAME

PPIx::XPath - an XPath implementation for the PDOM

VERSION

version 2.02

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 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");

DESCRIPTION

This module augments PPI's classes with the methods required by Tree::XPathEngine, allowing you to perform complex XPath matches against any PDOM tree.

See Tree::XPathEngine for details about its methods.

Mapping the PDOM to the XPath data model

• 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 PPI::, with :: replaced by -. 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 not mapped

METHODS

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 PPIx::XPath tied to the given document.

clean_xpath_expr

  my $new_xpath_expr = $pxp->clean_xpath_expr($old_xpath_expr);

PPIx::XPath version 1.0.0 allowed the use of partial package names (like Token::Number) as element names: this collides with the axis specification of proper XPath. For this reason, in newer version of PPIx::XPath, the element name is the class name of the PDOM node, minus the initial PPI::, with :: replaced by - (like Token-Number).

This method replaces all occurrences of PPI package names in the given string with the new names.

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 findnodes instead:

  my $xpath = Tree::XPathEngine->new();
  my @subs = $xpath->findnodes('//Statement-Sub',$pdom);
  my @vars = $xpath->findnodes('//Token-Symbol',$pdom);

BUGS and LIMITATIONS

• "here-docs" contents are 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

SEE ALSO

PPI

Tree::XPathEngine

http://www.w3.org/TR/xpath (the XPath specification)

AUTHORS

Dan Brook <cpan@broquaint.com> original author

Gianni Ceccarelli <dakkar@thenautilus.net> Tree::XPathEngine-based re-implementation

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.

cpanm PPIx::XPath

perl -MCPAN -e shell
install PPIx::XPath