Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Perl::CriticPerl::CritUserPContributedLPerltDocumentationlingCommaAtNewline(3)

NAME
       Perl::Critic::Policy::CodeLayout::RequireTrailingCommaAtNewline - comma
       at end of list at newline

DESCRIPTION
       This policy is part of the "Perl::Critic::Pulp" add-on.	It asks	you to
       put a comma at the end of a list	etc when it ends with a	newline,

	   @array = ($one,
		     $two     #	bad
		    );

	   @array = ($one,
		     $two,    #	ok
		    );

       This makes no difference	to how the code	runs, so the policy is low
       severity	and under the "cosmetic" theme (see "POLICY THEMES" in
       Perl::Critic).

       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.

       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.

	   $hashref = {	abc => 123,
			def => 456 };	# ok

       Parens around an	expression are not a list, so nothing is demanded in
       for instance

	   $foo	= (
		   1
		   + 2	      #	ok, an expression not a	list
		  );

       But a single element paren expression is	a list when it's in an array
       assignment or a function	or method call.

	   @foo	= (
		   1
		   + 2	      #	bad, list of one value
		  );

	   @foo	= (
		   1
		   + 2,	      #	ok
		  );

   Return Statement
       A "return" statement with a single value	is considered an expression so
       a trailing comma	is not required.

	   return ($x
		   + $y	   # ok
		   );

       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.

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

   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.

	   foo(<<HERE	   # ok
	   some	text
	   HERE
	      );

       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 "<<EOF" in perlop) then trailing comma
       considerations don't apply.  But	both forms work	and so are a matter of
       personal	preference.

	   foo(<<HERE);
	   some	text
	   HERE

       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.

	   foo(<<HERE,
	   one
	   HERE
	       <<HERE	   # bad
	   two
	   HERE
	      );

   Disabling
       If you don't care about trailing	commas like this you can as always
       disable from .perlcriticrc in the usual way (see	"CONFIGURATION"	in
       Perl::Critic),

	   [-CodeLayout::RequireTrailingCommaAtNewline]

CONFIGURATION
       "except_function_calls" (boolean, default false)
	   If true then	function calls and method calls	are not	checked,
	   allowing for	instance

	       foo (
		 1,
		 2     # ok under except_function_calls
	       );

	   The idea is that if "foo()" takes only two arguments	then you don't
	   want	to write a trailing comma as it	might suggest something	more
	   could be added.

	   Whether you write calls spread out this way is a matter of personal
	   preference.	If you do then enable "except_function_calls" with the
	   following in	your .perlcriticrc file,

	       [CodeLayout::RequireTrailingCommaAtNewline]
	       except_function_calls=1

SEE ALSO
       Perl::Critic::Pulp, Perl::Critic,
       Perl::Critic::Policy::CodeLayout::RequireTrailingCommas

   Other Ways to Do It
       This policy is a	variation of "CodeLayout::RequireTrailingCommas".
       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 "@x=(1,2,)" too much.

HOME PAGE
       <http://user42.tuxfamily.org/perl-critic-pulp/index.html>

COPYRIGHT
       Copyright 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017 Kevin
       Ryde

       Perl-Critic-Pulp	is free	software; you can redistribute it and/or
       modify it under the terms of the	GNU General Public License as
       published by the	Free Software Foundation; either version 3, or (at
       your option) any	later version.

       Perl-Critic-Pulp	is distributed in the hope that	it will	be useful, but
       WITHOUT ANY WARRANTY; without even the implied warranty of
       MERCHANTABILITY or FITNESS FOR A	PARTICULAR PURPOSE.  See the GNU
       General Public License for more details.

       You should have received	a copy of the GNU General Public License along
       with Perl-Critic-Pulp.  If not, see <http://www.gnu.org/licenses>.

perl v5.24.1Perl::Critic::Policy::CodeLayout::RequireTrailingCommaAtNewline(3)

NAME | DESCRIPTION | CONFIGURATION | SEE ALSO | HOME PAGE | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Perl::Critic::Policy::CodeLayout::RequireTrailingCommaAtNewline&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help