-
-
26 Apr 2019 14:49:02 UTC
- Distribution: PPIx-Utils
- Module version: 0.003
- Source (raw)
- Browse (raw)
- Changes
- Homepage
- How to Contribute
- Repository
- Issues (0)
- Testers (3386 / 0 / 0)
- Kwalitee
Bus factor: 1- 73.35% Coverage
- License: perl_5
- Perl: v5.6.0
- Activity
24 month- Tools
- Download (37.14KB)
- MetaCPAN Explorer
- Permissions
- Subscribe to distribution
- Permalinks
- This version
- Latest version
NAME
PPIx::Utils::Traversal - Utility functions for traversing PPI documents
SYNOPSIS
use PPIx::Utils::Traversal ':all';
DESCRIPTION
This package is a component of PPIx::Utils that contains functions for traversal of PPI documents.
FUNCTIONS
All functions can be imported by name, or with the tag
:all
.first_arg
my $first_arg = first_arg($element);
Given a PPI::Element that is presumed to be a function call (which is usually a PPI::Token::Word), return the first argument. This is similar of "parse_arg_list" and follows the same logic. Note that for the code:
int($x + 0.5)
this function will return just the
$x
, not the whole expression. This is different from the behavior of "parse_arg_list". Another caveat is:int(($x + $y) + 0.5)
which returns
($x + $y)
as a PPI::Structure::List instance.parse_arg_list
my @args = parse_arg_list($element);
Given a PPI::Element that is presumed to be a function call (which is usually a PPI::Token::Word), splits the argument expressions into arrays of tokens. Returns a list containing references to each of those arrays. This is useful because parentheses are optional when calling a function, and PPI parses them very differently. So this method is a poor-man's parse tree of PPI nodes. It's not bullet-proof because it doesn't respect precedence. In general, I don't like the way this function works, so don't count on it to be stable (or even present).
split_nodes_on_comma
my @args = split_nodes_on_comma(@nodes);
This has the same return type as "parse_arg_list" but expects to be passed the nodes that represent the interior of a list, like:
'foo', 1, 2, 'bar'
get_next_element_in_same_simple_statement
my $element = get_next_element_in_same_simple_statement($element);
Given a PPI::Element, this subroutine returns the next element in the same simple statement as defined by "is_ppi_simple_statement" in PPIx::Utils::Classification. If no next element can be found, this subroutine simply returns
undef
.If the $element is undefined or unblessed, we simply return
undef
.If the $element satisfies "is_ppi_simple_statement" in PPIx::Utils::Classification, we return
undef
, unless it has a parent which is a PPI::Structure::List.If the $element is the last significant element in its PPI::Node, we replace it with its parent and iterate again.
Otherwise, we return
$element->snext_sibling()
.get_previous_module_used_on_same_line
my $element = get_previous_module_used_on_same_line($element);
Given a PPI::Element, returns the PPI::Element representing the name of the module included by the previous
use
orrequire
on the same line as the $element. If none is found, simply returnsundef
.For example, with the line
use version; our $VERSION = ...;
given the PPI::Token::Symbol instance for
$VERSION
, this will return "version".If the given element is in a
use
or <require>, the return is from the previoususe
orrequire
on the line, if any.get_constant_name_elements_from_declaring_statement
my @constants = get_constant_name_elements_from_declaring_statement($statement);
Given a PPI::Statement, if the statement is a Readonly, ReadonlyX, or Const::Fast declaration statement or a
use constant
, returns the names of the things being defined.Given
use constant 1.16 FOO => 'bar';
this will return the PPI::Token::Word containing
'FOO'
. Givenuse constant 1.16 { FOO => 'bar', 'BAZ' => 'burfle' };
this will return a list of the PPI::Tokens containing
'FOO'
and'BAZ'
. Similarly, givenReadonly::Hash my %FOO => ( bar => 'baz' );
or
const my %FOO => ( bar => 'baz' );
this will return the PPI::Token::Symbol containing
'%FOO'
.split_ppi_node_by_namespace
my $subtrees = split_ppi_node_by_namespace($node);
Returns the sub-trees for each namespace in the node as a reference to a hash of references to arrays of PPI::Nodes. Say we've got the following code:
#!perl my $x = blah(); package Foo; my $y = blah_blah(); { say 'Whee!'; package Bar; something(); } thingy(); package Baz; da_da_da(); package Foo; foreach ( blrfl() ) { ... }
Calling this function on a PPI::Document for the above returns a value that looks like this, using multi-line string literals for the actual code parts instead of PPI trees to make this easier to read:
{ main => [ q< #!perl my $x = blah(); >, ], Foo => [ q< package Foo; my $y = blah_blah(); { say 'Whee!'; } thingy(); >, q< package Foo; foreach ( blrfl() ) { ... } >, ], Bar => [ q< package Bar; something(); >, ], Baz => [ q< package Baz; da_da_da(); >, ], }
Note that the return value contains copies of the original nodes, and not the original nodes themselves due to the need to handle namespaces that are not file-scoped. (Notice how the first element for "Foo" above differs from the original code.)
BUGS
Report any issues on the public bugtracker.
AUTHOR
Dan Book <dbook@cpan.org>
Code originally from Perl::Critic::Utils by Jeffrey Ryan Thalhammer <jeff@imaginative-software.com>, Perl::Critic::Utils::PPI and PPIx::Utilities::Node by Elliot Shank <perl@galumph.com>, and PPIx::Utilities::Statement by Thomas R. Wyant, III <wyant@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2005-2011 Imaginative Software Systems, 2007-2011 Elliot Shank, 2009-2010 Thomas R. Wyant, III, 2017 Dan Book.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
SEE ALSO
Perl::Critic::Utils, Perl::Critic::Utils::PPI, PPIx::Utilities
Module Install Instructions
To install PPIx::Utils, copy and paste the appropriate command in to your terminal.
cpanm PPIx::Utils
perl -MCPAN -e shell install PPIx::Utils
For more information on module installation, please visit the detailed CPAN module installation guide.