PPIx::Utils::Traversal(3)                  User Contributed Perl Documentation


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

perl v5.38.0                      2023-07-26         PPIx::Utils::Traversal(3)