NAME

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

DESCRIPTION

This policy is part of the Perl::Critic::Pulp|Perl::Critic::Pulp addon. 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 only normally a minor irritant to readability so this policy is low priority and under the "cosmetic" theme (see POLICY THEMES in Perl::Critic).

Text and command paragraphs are checked, but verbatim paragraphs can have anything. Not quite every paren must be balanced. The intention is to be forgiving of common or reasonable constructs. Currently this means,

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 longer 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 only a "1)" in the middle.

Smiley faces are only an "optional" close,

    (Some thing :-).                # ok

    Bare smiley :).                 # ok

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

Sad smiley faces are skipped, ie. are not an opening paren,
```
    :( :-(.     # ok
```
Perl variables $( and $[ are skipped, ie. not opening parens,
```
    Default is group $( blah blah.  # ok
```
${ brace is still an open and expected to have a matching close, as it's likely to be a deref or delimiter,
```
    Deref with ${foo()} etc etc.
```
Such variables or forms will often be in C<> markup and skipped for that reason per below.
$) and $] are optional closes, since they might be Perl variables to skip, or "$" 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 same code like this is probably usual.
Anything in C<> code markup is ignored
```
    In code C<anything [ is allowed>.  # ok
```
Perhaps this will change, though there'd have to be more 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
```
is bad because the C<> ends at the =>, leaving "value)" unbalanced plain text.
L<display|link<gt> links are treated as the "display" text part. The link target (POD document name and section) can have anything.

Unrecognised Forms

A mathematical half-open range like

    [1,2)             # bad

is not recognised. 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 anyway.

Parens spanning multiple paragraphs are not recognised,

    (This is some     # bad

    thing.)           # bad

Hopefully this is uncommon, and it may be better style not to be parenthetical about something big enough 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 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]

BUGS

What should be done for =begin ... =end sections? Skip probably?

HOME PAGE

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

COPYRIGHT

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