Provided by: libperl-critic-pulp-perl_96-1_all bug

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,

       ·   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.)

       ·   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.

       ·   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.

       ·   Smiley faces are an "optional" close,

               (Some thing :-).                # ok

               Bare smiley :).                 # ok

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

       ·   Sad smiley faces are not an opening paren,

               :( :-(.     # ok

       ·   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.

       ·   $) 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.

       ·   "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 1 <= X < 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.26.2                   Perl::Critic::Policy::Documentation::ProhibitUnbalancedParens(3pm)