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 or require on the same line as the $element. If none is found, simply returns undef.

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 previous use or require 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'. Given

    use constant 1.16 { FOO => 'bar', 'BAZ' => 'burfle' };

this will return a list of the PPI::Tokens containing 'FOO' and 'BAZ'. Similarly, given

    Readonly::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

cpanm PPIx::Utils

perl -MCPAN -e shell
install PPIx::Utils