.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Perl::Critic::Utils::PPI 3pm"
.TH Perl::Critic::Utils::PPI 3pm "2018-07-27" "perl v5.26.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Perl::Critic::Utils::PPI \- Utility functions for dealing with PPI objects.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Provides classification of PPI::Elements.
.SH "INTERFACE SUPPORT"
.IX Header "INTERFACE SUPPORT"
This is considered to be a public module.  Any changes to its
interface will go through a deprecation cycle.
.SH "IMPORTABLE SUBS"
.IX Header "IMPORTABLE SUBS"
.ie n .IP """is_ppi_expression_or_generic_statement( $element )""" 4
.el .IP "\f(CWis_ppi_expression_or_generic_statement( $element )\fR" 4
.IX Item "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 \f(CW\*(C`Expression\*(C'\fR.
.ie n .IP """is_ppi_generic_statement( $element )""" 4
.el .IP "\f(CWis_ppi_generic_statement( $element )\fR" 4
.IX Item "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.
.ie n .IP """is_ppi_statement_subclass( $element )""" 4
.el .IP "\f(CWis_ppi_statement_subclass( $element )\fR" 4
.IX Item "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.
.ie n .IP """is_ppi_simple_statement( $element )""" 4
.el .IP "\f(CWis_ppi_simple_statement( $element )\fR" 4
.IX Item "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.
.ie n .IP """is_ppi_constant_element( $element )""" 4
.el .IP "\f(CWis_ppi_constant_element( $element )\fR" 4
.IX Item "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.
.Sp
This subroutine does \fBnot\fR 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.
.Sp
This subroutine also does \fBnot\fR 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 (\fBnot\fR Mr. Shank or Mr. Thalhammer) lacks the
knowledge/expertise/gumption to put it in place.
.ie n .IP """is_subroutine_declaration( $element )""" 4
.el .IP "\f(CWis_subroutine_declaration( $element )\fR" 4
.IX Item "is_subroutine_declaration( $element )"
Is the parameter a subroutine declaration, named or not?
.ie n .IP """is_in_subroutine( $element )""" 4
.el .IP "\f(CWis_in_subroutine( $element )\fR" 4
.IX Item "is_in_subroutine( $element )"
Is the parameter a subroutine or inside one?
.ie n .IP """get_constant_name_element_from_declaring_statement($statement)""" 4
.el .IP "\f(CWget_constant_name_element_from_declaring_statement($statement)\fR" 4
.IX Item "get_constant_name_element_from_declaring_statement($statement)"
\&\fBThis subroutine is deprecated.\fR You should use
\&\*(L"\fIget_constant_name_elements_from_declaring_statement()\fR\*(R" in PPIx::Utilities::Statement
instead.
.Sp
Given a PPI::Statement, if the statement is a \f(CW\*(C`use
constant\*(C'\fR or Readonly declaration statement, return the name of
the thing being defined.
.Sp
Given
.Sp
.Vb 1
\&    use constant 1.16 FOO => \*(Aqbar\*(Aq;
.Ve
.Sp
this will return \*(L"\s-1FOO\*(R".\s0  Similarly, given
.Sp
.Vb 1
\&    Readonly::Hash my %FOO => ( bar => \*(Aqbaz\*(Aq );
.Ve
.Sp
this will return \*(L"%FOO\*(R".
.Sp
\&\fBCaveat:\fR in the case where multiple constants are declared using the same
\&\f(CW\*(C`use constant\*(C'\fR statement (e.g. \f(CW\*(C`use constant { FOO => 1, BAR => 2 };\*(C'\fR,
this subroutine will return the declaring
PPI::Structure::Constructor. In the case of
\&\f(CW\*(C`use constant 1.16 { FOO => 1, BAR => 2 };\*(C'\fR it may return a
PPI::Structure::Block instead of a
PPI::Structure::Constructor, due to a parse
error in \s-1PPI\s0.
.ie n .IP """get_next_element_in_same_simple_statement( $element )""" 4
.el .IP "\f(CWget_next_element_in_same_simple_statement( $element )\fR" 4
.IX Item "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 \fIis_ppi_simple_statement()\fR. If no
next element can be found, this subroutine simply returns.
.Sp
If the \f(CW$element\fR is undefined or unblessed, we simply return.
.Sp
If the \f(CW$element\fR satisfies \f(CW\*(C`is_ppi_simple_statement()\*(C'\fR, we return, \fBunless\fR
it has a parent which is a PPI::Structure::List.
.Sp
If the \f(CW$element\fR is the last significant element in its PPI::Node,
we replace it with its parent and iterate again.
.Sp
Otherwise, we return \f(CW\*(C`$element\->snext_sibling()\*(C'\fR.
.ie n .IP """get_previous_module_used_on_same_line( $element )""" 4
.el .IP "\f(CWget_previous_module_used_on_same_line( $element )\fR" 4
.IX Item "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 \f(CW\*(C`use\*(C'\fR or
\&\f(CW\*(C`require\*(C'\fR on the same line as the \f(CW$element\fR. If none is found, simply returns.
.Sp
For example, with the line
.Sp
.Vb 1
\&    use version; our $VERSION = ...;
.Ve
.Sp
given the PPI::Token::Symbol instance for \f(CW$VERSION\fR, this will return
\&\*(L"version\*(R".
.Sp
If the given element is in a \f(CW\*(C`use\*(C'\fR or <require>, the return is from the
previous \f(CW\*(C`use\*(C'\fR or \f(CW\*(C`require\*(C'\fR on the line, if any.
.SH "AUTHOR"
.IX Header "AUTHOR"
Elliot Shank <perl@galumph.com>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2007\-2011 Elliot Shank.
.PP
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 \s-1LICENSE\s0 file included with this module.