.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" 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 .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Perl::Critic::Policy::CodeLayout::ProhibitFatCommaNewline 3pm" .TH Perl::Critic::Policy::CodeLayout::ProhibitFatCommaNewline 3pm "2021-02-28" "perl v5.32.1" "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::ProhibitFatCommaNewline \- keep a fat comma on the same line as its quoted word .SH "DESCRIPTION" .IX Header "DESCRIPTION" This policy is part of the \f(CW\*(C`Perl::Critic::Pulp\*(C'\fR add-on. It reports a newline between a fat comma and preceding bareword for Perl builtins, .PP .Vb 2 \& my %h = (caller # bad, builtin called as a function \& => \*(Aqabc\*(Aq); .Ve .PP And for all words when targeting Perl 5.6 and earlier, .PP .Vb 3 \& use 5.006; \& my %h = (foo # bad, all words in perl 5.6 and earlier \& => \*(Aqdef\*(Aq); .Ve .PP When there's a newline between the word and the fat comma like this the word executes as a function call (builtins always, and also user defined in Perl 5.6 and earlier), giving its return value rather than a word string. .PP Such a return value is probably not what was intended and on that basis this policy is under the \*(L"bugs\*(R" theme and medium severity (see \&\*(L"\s-1POLICY THEMES\*(R"\s0 in Perl::Critic). .SS "Builtins" .IX Subsection "Builtins" Perl builtin functions with a newline always execute and give their return value rather than a the quoted word. .PP .Vb 3 \& my %h = (print # bad, builtin print() executes \& => "abc"); \& # %h is key "1" value "abc" .Ve .PP The builtin is called with no arguments and that might provoke a warning from some, but others like \f(CW\*(C`print\*(C'\fR will quietly run. .PP Dashed builtin names such as \f(CW\*(C`\-print\*(C'\fR are also function calls, with a negate operator. .PP .Vb 3 \& my %h = (\-print # bad, print() call and negate \& => "123"); \& # h is key "\-1" value "123" .Ve .PP For the purposes of this policy the builtins are \f(CW\*(C`is_perl_builtin()\*(C'\fR from Perl::Critic::Utils. It's possible this is more builtins than the particular Perl in use, but guarding against all will help if going to a newer Perl in the future. .SS "Non-Builtins" .IX Subsection "Non-Builtins" In Perl 5.6 and earlier all words \f(CW\*(C`foo\*(C'\fR execute as a function call when there's a newline before the fat comma. .PP .Vb 6 \& sub foo { \& return 123 \& } \& my %h = (foo \& => "def"); \& # in Perl 5.6 and earlier %h is key "123" value "def" .Ve .PP Under \f(CW\*(C`use strict\*(C'\fR an error is thrown if no such function, in the usual way. A word builtin is a function call if it exists (with a warning about being interpreted that way), or a bareword if not. .PP This policy prohibits all words with newline before fat comma when targeting Perl 5.6 or earlier. This means either an explicit \f(CW\*(C`use 5.006\*(C'\fR or smaller, or no such minimum \f(CW\*(C`use\*(C'\fR at all. .PP One subtle way an executing word with newline before fat comma can go undetected (in 5.6 and earlier still) is an accidental redefinition of a constant, .PP .Vb 4 \& use constant FOO => "blah"; \& use constant FOO \& => "some value"; \& # makes a constant subr called blah (in Perl 5.6) .Ve .PP \&\f(CW\*(C`constant.pm\*(C'\fR might reject some return values from \f(CW\*(C`FOO()\*(C'\fR, eg. a number, but a string like \*(L"blah\*(R" here quietly expands and creates a constant \&\f(CW\*(C`blah()\*(C'\fR. .PP The difference between Perl 5.6 and later Perl is that in 5.6 the parser only looked as far as a newline for a possible quoting \f(CW\*(C`=>\*(C'\fR fat comma. In Perl 5.8 and later for non-builtins the lookahead continues beyond any newlines and comments. For Perl builtins the behaviour is the same, in all versions the lookahead stops at the newline. .SS "Avoiding Problems" .IX Subsection "Avoiding Problems" Putting the fat comma on the same line as the word ensures it quotes in all cases. .PP .Vb 2 \& my %h = (\-print => # ok, fat comma on same line quotes \& "123"); .Ve .PP If for layout purposes you do want a newline then the suggestion is to give a string or perhaps a parenthesized expression since that doesn't rely on the \f(CW\*(C`=>\*(C'\fR fat comma quoting. A fat comma can still emphasize a key/value pair. .PP .Vb 3 \& my %h = (\*(Aqprint\*(Aq # ok, string \& => \& 123); .Ve .PP Alternately if instead a function call is really what's intended (builtin or otherwise) then parens can be used in the normal way to ensure it's a call (as per perltrap the rule being \*(L"if it looks like a function, it is a function\*(R"). .PP .Vb 3 \& my %h = (foo() # ok, function call \& => \& 123); .Ve .SS "Disabling" .IX Subsection "Disabling" As always if you don't care about this then you can disable \&\f(CW\*(C`ProhibitFatCommaNewline\*(C'\fR from your \fI.perlcriticrc\fR in the usual way (see \*(L"\s-1CONFIGURATION\*(R"\s0 in Perl::Critic), .PP .Vb 1 \& [\-CodeLayout::ProhibitFatCommaNewline] .Ve .SH "SEE ALSO" .IX Header "SEE ALSO" Perl::Critic::Pulp, Perl::Critic, perlop .SH "HOME PAGE" .IX Header "HOME PAGE" .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright 2011, 2013, 2014, 2015, 2016, 2017, 2019, 2021 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 .