--- name: "PPIx::Utils::Traversal" section: "3pm" platform: "linux" package: "perl-ppix-utils" version: "0.004-3" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/PPIx::Utils::Traversal" --- # PPIx::Utils::Traversal(3pm) Utility functions for traversing PPI documents ## 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 \, 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 \ Code originally from Perl::Critic::Utils by Jeffrey Ryan Thalhammer \, Perl::Critic::Utils::PPI and PPIx::Utilities::Node by Elliot Shank \, and PPIx::Utilities::Statement by Thomas R. Wyant, III \ ## 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