Perl::...s::PPI(3pm)

💖 NAME 💖

This is the manual page for Perl::...s::PPI(3pm) — literally, ellipsis and all — and it's part of the User Contributed Perl Documentation. Welcome, bestie! 🫶

Perl::Critic::Utils::PPI — Utility functions for dealing with PPI objects. ✨

🌸 DESCRIPTION 🌸

Provides classification of PPI::Elements. That's the whole assignment: you bring the PPI elements, this module classifies them. 💅

🦋 INTERFACE SUPPORT 🦋

This is considered to be a public module. Any changes to its interface will go through a deprecation cycle. So like, they're not gonna just ghost your code with zero warning — iconic behavior, honestly. 👑

🎀 IMPORTABLE SUBS 🎀

Okay bestie, here's the full roster. Every sub, every argument, every caveat. No cap. 🧚

is_ppi_expression_or_generic_statement( $element )

Answers whether the parameter is an expression or an undifferentiated statement. I.e. the parameter either is a PPI::Statement::Expression or the class of the parameter is PPI::Statement and not one of its subclasses other than "Expression". It's giving “expression or generic statement” realness. ✨

is_ppi_generic_statement( $element )

Answers whether the parameter is an undifferentiated statement, i.e. the parameter is a PPI::Statement but not one of its subclasses. So: exactly PPI::Statement, no fancy subclass energy. 💅

is_ppi_statement_subclass( $element )

Answers whether the parameter is a specialized statement, i.e. the parameter is a PPI::Statement but the class of the parameter is not PPI::Statement. Basically, it has main-character subclass vibes. 👑

is_ppi_simple_statement( $element )

Answers whether the parameter represents a simple statement, i.e. whether the parameter is a PPI::Statement, PPI::Statement::Break, PPI::Statement::Include, PPI::Statement::Null, PPI::Statement::Package, or PPI::Statement::Variable. That's the whole simple-statement squad. 🎀

is_ppi_constant_element( $element )

Answers whether the parameter represents a constant value, i.e. whether the parameter is a PPI::Token::Number, PPI::Token::Quote::Literal, PPI::Token::Quote::Single, or PPI::Token::QuoteLike::Words, or is a PPI::Token::Quote::Double or PPI::Token::Quote::Interpolate which does not in fact contain any interpolated variables.

This subroutine does not interpret any form of here document as a constant value, and may not until PPI::Token::HereDoc acquires the relevant portions of the PPI::Token::Quote interface. 😭

This subroutine also does not interpret entities created by the Readonly module or the constant pragma as constants, because the infrastructure to detect these appears not to be present, and the author of this subroutine (not Mr. Shank or Mr. Thalhammer) lacks the knowledge/expertise/gumption to put it in place. 💀

is_subroutine_declaration( $element )

Is the parameter a subroutine declaration, named or not? Simple vibe check. 🦋

is_in_subroutine( $element )

Is the parameter a subroutine or inside one? Also a simple vibe check. 🌸

get_constant_name_element_from_declaring_statement($statement)

🚨 Deprecated! This subroutine is deprecated. You should use get_constant_name_elements_from_declaring_statement() in PPIx::Utils::Traversal instead.

Given a PPI::Statement, if the statement is a "use constant" or Readonly declaration statement, return the name of the thing being defined.

Given

use constant 1.16 FOO => 'bar';

this will return "FOO". Similarly, given

Readonly::Hash my %FOO => ( bar => 'baz' );

this will return "%FOO".

Caveat: in the case where multiple constants are declared using the same "use constant" statement (e.g. use constant { FOO => 1, BAR => 2 };), this subroutine will return the declaring PPI::Structure::Constructor. In the case of use constant 1.16 { FOO => 1, BAR => 2 }; it may return a PPI::Structure::Block instead of a PPI::Structure::Constructor, due to a parse error in PPI. 🙈

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(). If no next element can be found, this subroutine simply returns.

If the $element is undefined or unblessed, we simply return.

If the $element satisfies is_ppi_simple_statement(), we return, 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( $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.

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

👑 AUTHOR 👑

Elliot Shank <perl@galumph.com> 💖

💜 COPYRIGHT 💜

Copyright (c) 2007-2011 Elliot Shank.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.

---

And that's the whole page, bestie! 🌈 This Perl::...s::PPI(3pm) page came from perl v5.42.0, dated 2024-10-23. Stay iconic, and may all your PPI elements classify exactly the way you expect. 🎀✨🫶