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

FreeBSD Manual Pages

  
 
  

home | help
Perl::Critic::Perl::CrUser:ContributedcPerltDocumentationitUnbalancedParens(3)

NAME
       Perl::Critic::Policy::Documentation::ProhibitUnbalancedParens - don't
       leave an	open bracket or	paren

DESCRIPTION
       This policy is part of the "Perl::Critic::Pulp" add-on.	It reports
       unbalanced or mismatched	parentheses, brackets and braces in POD	text
       paragraphs,

	   Blah	blah (and something.	# bad

	   Blah	blah ( [ ).		# bad

	   Blah	blah brace }.		# bad

       This is only cosmetic and normally only a minor irritant	to readability
       so this policy is low severity and under	the "cosmetic" theme (see
       "POLICY THEMES" in Perl::Critic).

       Text and	command	paragraphs are checked,	but verbatim paragraphs	can
       have anything.  There are some exceptions to paren balancing.  The
       intention is to be forgiving of common or reasonable constructs.
       Currently this means,

       o   Anything in "C<>" code markup is ignored

	       In code C<anything [ is allowed>.  # ok

	   Perhaps this	will change, though there'd have to be extra
	   exceptions in "C<>",	such as	various	backslashing.

	   Sometimes a prematurely ending "C<>"	may look like an unbalanced
	   paren, for example

	       Call C<foo(key=>value)> ...    #	bad

	   This	is bad because the "C<>" ends at the "=>", leaving "value)"
	   unbalanced plain text.  This	is an easy mistake to make.  (The
	   author's "perl-pod-gt.el" can show warning face on this in Emacs.)

       o   Quoted "(" is taken to be describing	the char and is	not an open or
	   close.

	       Any of "(" or '[' or "[{]".   # ok

	   This	only applies to	quoted parens alone (one or more), not larger
	   quoted text.

       o   Item	parens

	       a) the first thing, or b) the second thing   # ok

	       1) one, 2) two	  # ok

	   Exactly how much is recognised as an	"a)" etc is not	quite settled.
	   In the current code a "1.5)"	is recognised at the start of a
	   paragraph, but in the middle	only "1)" style.

       o   Smiley faces	are an "optional" close,

	       (Some thing :-).		       # ok

	       Bare smiley :).		       # ok

	       (Or smile :-) and also close.)  # ok

       o   Sad smiley faces are	not an opening paren,

	       :( :-(.	   # ok

       o   Perl	variables $( and $[ are	not opening parens,

	       Default is group	$( blah	blah.  # ok

	   ${ brace is still an	open and expected to have a matching close,
	   because it's	likely to be a deref or	delimiter,

	       Deref with ${foo()} etc etc.

	   Variables or	expressions like this will often be in "C<>" markup
	   and skipped for that	reason instead,	as described above.

       o   $) and $] are optional closes, since	they might be Perl variables
	   to skip, or might be	"$" at the end of a parens,

	      blah blah	(which in TeX is $1\cdot2$).

	   Perhaps the conditions for these will be restricted a bit, though
	   again "C<>" markup around sample code like this will	be usual.

       o   "L<display|link>" links are processed as the	"display" text part.
	   The link target (POD	document name and section) can have anything.

       "=begin :foo" ... "=end :foo" sections with a format name ":foo"
       starting	with a ":" are POD markup and are processed accordingly.
       Other "=begin" sections are skipped.

   Unrecognised	Forms
       A mathematical half-open	range like the following is not	recognised.

	   [1,2)	     # bad, currently

       Perhaps just numbers like this would be unambiguous, but	if it's	an
       expression then it's hard to distinguish	a parens typo from some
       mathematics.  The suggestion for	now is an "=for" per below to flag it
       as an exception.	 Another way would be to write 1A <=A XA <A 2, which
       might be	clearer	to mathematically unsophisticated readers.

       Parens spanning multiple	paragraphs are not recognised,

	   (This is some     # bad

	   thing.)	     # bad

       Hopefully this is uncommon, and probably	better style not to be
       parenthetical about something so	big that it runs to multiple
       paragraphs or has a verbatim block in the middle	etc.

   Disabling
       If an unbalanced	paren is intended you can add an "=for"	to tell
       "ProhibitUnbalancedParens" to allow it.

	   =for	ProhibitUnbalancedParens allow next

	   Something ( deliberately unclosed.

       Or with a count of paragraphs to	ignore,

	   =for	ProhibitUnbalancedParens allow next 2

	   First deliberate [ unclosed.

	   Second (.

       The usual no critic

	   ## no critic	(ProhibitUnbalancedParens)

       works too as a whole-file disable, but the annotation must be before
       any "__END__" token, and	if the POD is after the	"__END__" then
       "Perl::Critic" 1.112 up is required.  Individual	"=for" has the
       advantage of being with an exception.

       As always if you	don't care about this at all you can disable
       "ProhibitUnbalancedParens" completely from your .perlcriticrc in	the
       usual way (see "CONFIGURATION" in Perl::Critic),

	   [-Documentation::ProhibitUnbalancedParens]

SEE ALSO
       Perl::Critic::Pulp, Perl::Critic

       <http://user42.tuxfamily.org/perl-pod-gt/index.html>

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

COPYRIGHT
       Copyright 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.1  Perl::Critic::Policy::Documentation::ProhibitUnbalancedParens(3)

NAME | DESCRIPTION | 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::Documentation::ProhibitUnbalancedParens&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help