GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

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

PPIx::Utils::Traversal - Utility functions for traversing PPI documents

    use PPIx::Utils::Traversal ':all';

This package is a component of PPIx::Utils that contains functions for traversal of PPI documents.

All functions can be imported by name, or with the tag ":all".

    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.

    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).

    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'

    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()".

    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.

    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'.

    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.)

Report any issues on the public bugtracker.

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>

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.

Perl::Critic::Utils, Perl::Critic::Utils::PPI, PPIx::Utilities
2019-04-26 perl v5.32.1

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.