.\" 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
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "Perl::Critic::Policy::CodeLayout::RequireTrailingCommaAtNewline 3pm"
.TH Perl::Critic::Policy::CodeLayout::RequireTrailingCommaAtNewline 3pm "2018-05-30" "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::Policy::CodeLayout::RequireTrailingCommaAtNewline \- comma at end of list at newline
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This policy is part of the \f(CW\*(C`Perl::Critic::Pulp\*(C'\fR
add-on.  It asks you to put a comma at the end of a list etc when it ends
with a newline,
.PP
.Vb 3
\&    @array = ($one,
\&              $two     # bad
\&             );
\&
\&    @array = ($one,
\&              $two,    # ok
\&             );
.Ve
.PP
This makes no difference to how the code runs, so the policy is low severity
and under the \*(L"cosmetic\*(R" theme (see \*(L"\s-1POLICY THEMES\*(R"\s0 in Perl::Critic).
.PP
The idea is to make it easier when editing the code since you don't have to
remember to add a comma to a preceding item when extending or re-arranging
lines.
.PP
If the closing bracket is on the same line as the last element then no comma
is required.  It can be be present if desired, but is not required.
.PP
.Vb 2
\&    $hashref = { abc => 123,
\&                 def => 456 };   # ok
.Ve
.PP
Parens around an expression are not a list, so nothing is demanded in for
instance
.PP
.Vb 4
\&    $foo = (
\&            1
\&            + 2        # ok, an expression not a list
\&           );
.Ve
.PP
But a single element paren expression is a list when it's in an array
assignment or a function or method call.
.PP
.Vb 4
\&    @foo = (
\&            1
\&            + 2        # bad, list of one value
\&           );
\&            
\&
\&    @foo = (
\&            1
\&            + 2,       # ok
\&           );
.Ve
.SS "Return Statement"
.IX Subsection "Return Statement"
A \f(CW\*(C`return\*(C'\fR statement with a single value is considered an expression so a
trailing comma is not required.
.PP
.Vb 3
\&    return ($x
\&            + $y    # ok
\&            );
.Ve
.PP
Whether such code is a single-value expression or a list of only one value
depends on how the function is specified.  There's nothing in the text (nor
even at runtime) which would say for sure.
.PP
It's handy to included parens around a single-value expression to make it
clear some big arithmetic is all part of the return, especially if you can't
remember precedence levels.  In such an expression a newline before the
final \*(L")\*(R" can help keep a comment together with a term for a cut and paste,
or not lose a paren if commenting the last line, etc.  So for now the policy
is lenient.  Would an option be good though?
.SS "Here Documents"
.IX Subsection "Here Documents"
An exception is made for a single expression ending with a here-document.
This is slightly experimental, and might become an option, but the idea is
that a newline is necessary for a here-document within parens and so
shouldn't demand a comma.
.PP
.Vb 4
\&    foo(<<HERE      # ok
\&    some text
\&    HERE
\&       );
.Ve
.PP
This style is a little unusual but some people like the whole here-document
at the place its string result will expand.  If the code is all on one line
(see \*(L"<<\s-1EOF\*(R"\s0 in perlop) then trailing comma considerations don't
apply.  But both forms work and so are a matter of personal preference.
.PP
.Vb 3
\&    foo(<<HERE);
\&    some text
\&    HERE
.Ve
.PP
Multiple values still require a final comma.  Multiple values suggests a
list and full commas guards against forgetting to add a comma if extending
or rearranging.
.PP
.Vb 7
\&    foo(<<HERE,
\&    one
\&    HERE
\&        <<HERE      # bad
\&    two
\&    HERE
\&       );
.Ve
.SS "Disabling"
.IX Subsection "Disabling"
If you don't care about trailing commas like this you can as always disable
from \fI.perlcriticrc\fR in the usual way (see \*(L"\s-1CONFIGURATION\*(R"\s0 in Perl::Critic),
.PP
.Vb 1
\&    [\-CodeLayout::RequireTrailingCommaAtNewline]
.Ve
.SH "CONFIGURATION"
.IX Header "CONFIGURATION"
.ie n .IP """except_function_calls"" (boolean, default false)" 4
.el .IP "\f(CWexcept_function_calls\fR (boolean, default false)" 4
.IX Item "except_function_calls (boolean, default false)"
If true then function calls and method calls are not checked, allowing for
instance
.Sp
.Vb 4
\&    foo (
\&      1,
\&      2     # ok under except_function_calls
\&    );
.Ve
.Sp
The idea is that if \f(CW\*(C`foo()\*(C'\fR takes only two arguments then you don't want to
write a trailing comma as it might suggest something more could be added.
.Sp
Whether you write calls spread out this way is a matter of personal
preference.  If you do then enable \f(CW\*(C`except_function_calls\*(C'\fR with the
following in your \fI.perlcriticrc\fR file,
.Sp
.Vb 2
\&    [CodeLayout::RequireTrailingCommaAtNewline]
\&    except_function_calls=1
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Perl::Critic::Pulp,
Perl::Critic,
Perl::Critic::Policy::CodeLayout::RequireTrailingCommas
.SS "Other Ways to Do It"
.IX Subsection "Other Ways to Do It"
This policy is a variation of \f(CW\*(C`CodeLayout::RequireTrailingCommas\*(C'\fR.  That
policy doesn't apply to function calls or hashref constructors, and you may
find its requirement for a trailing comma in even one-line lists like
\&\f(CW\*(C`@x=(1,2,)\*(C'\fR too much.
.SH "HOME PAGE"
.IX Header "HOME PAGE"
<http://user42.tuxfamily.org/perl\-critic\-pulp/index.html>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017 Kevin Ryde
.PP
Perl-Critic-Pulp is free software; you can redistribute it and/or modify it
under the terms of the \s-1GNU\s0 General Public License as published by the Free
Software Foundation; either version 3, or (at your option) any later
version.
.PP
Perl-Critic-Pulp is distributed in the hope that it will be useful, but
\&\s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of \s-1MERCHANTABILITY\s0
or \s-1FITNESS FOR A PARTICULAR PURPOSE.\s0  See the \s-1GNU\s0 General Public License for
more details.
.PP
You should have received a copy of the \s-1GNU\s0 General Public License along with
Perl-Critic-Pulp.  If not, see <http://www.gnu.org/licenses>.