NAME

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

DESCRIPTION

       Provides classification of PPI::Elements.

INTERFACE SUPPORT

       This is considered to be a public module.  Any changes to its interface will go through a deprecation
       cycle.

IMPORTABLE SUBS

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

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

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

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

       "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?

       "is_in_subroutine( $element )"
           Is the parameter a subroutine or inside one?

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

perl v5.36.0                                       2023-10-27                      Perl::Critic::Utils::PPI(3pm)