.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" 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
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "Perl::Critic::Policy::Documentation::ProhibitUnbalancedParens 3pm"
.TH Perl::Critic::Policy::Documentation::ProhibitUnbalancedParens 3pm "2018-05-30" "perl v5.26.2" "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::Documentation::ProhibitUnbalancedParens \- don't leave an open bracket or paren
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This policy is part of the \f(CW\*(C`Perl::Critic::Pulp\*(C'\fR
add-on.  It reports unbalanced or mismatched parentheses, brackets and braces
in \s-1POD\s0 text paragraphs,
.PP
.Vb 1
\&    Blah blah (and something.    # bad
\&
\&    Blah blah ( [ ).             # bad
\&
\&    Blah blah brace }.           # bad
.Ve
.PP
This is only cosmetic and normally only a minor irritant to readability so
this policy is low severity and under the \*(L"cosmetic\*(R" theme (see
\&\*(L"\s-1POLICY THEMES\*(R"\s0 in Perl::Critic).
.PP
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,
.IP "\(bu" 4
Anything in \f(CW\*(C`C<>\*(C'\fR code markup is ignored
.Sp
.Vb 1
\&    In code C<anything [ is allowed>.  # ok
.Ve
.Sp
Perhaps this will change, though there'd have to be extra exceptions in
\&\f(CW\*(C`C<>\*(C'\fR, such as various backslashing.
.Sp
Sometimes a prematurely ending \f(CW\*(C`C<>\*(C'\fR may look like an unbalanced
paren, for example
.Sp
.Vb 1
\&    Call C<foo(key=>value)> ...    # bad
.Ve
.Sp
This is bad because the \f(CW\*(C`C<>\*(C'\fR ends at the \f(CW\*(C`=>\*(C'\fR, leaving
\&\*(L"value)\*(R" unbalanced plain text.  This is an easy mistake to make.  (The
author's \f(CW\*(C`perl\-pod\-gt.el\*(C'\fR can show warning face on this in Emacs.)
.IP "\(bu" 4
Quoted \*(L"(\*(R" is taken to be describing the char and is not an open or close.
.Sp
.Vb 1
\&    Any of "(" or \*(Aq[\*(Aq or "[{]".   # ok
.Ve
.Sp
This only applies to quoted parens alone (one or more), not larger quoted
text.
.IP "\(bu" 4
Item parens
.Sp
.Vb 1
\&    a) the first thing, or b) the second thing   # ok
\&
\&    1) one, 2) two     # ok
.Ve
.Sp
Exactly how much is recognised as an \*(L"a)\*(R" etc is not quite settled.  In the
current code a \*(L"1.5)\*(R" is recognised at the start of a paragraph, but in the
middle only \*(L"1)\*(R" style.
.IP "\(bu" 4
Smiley faces are an \*(L"optional\*(R" close,
.Sp
.Vb 1
\&    (Some thing :\-).                # ok
\&
\&    Bare smiley :).                 # ok
\&
\&    (Or smile :\-) and also close.)  # ok
.Ve
.IP "\(bu" 4
Sad smiley faces are not an opening paren,
.Sp
.Vb 1
\&    :( :\-(.     # ok
.Ve
.IP "\(bu" 4
Perl variables \f(CW$(\fR and \f(CW$[\fR are not opening parens,
.Sp
.Vb 1
\&    Default is group $( blah blah.  # ok
.Ve
.Sp
\&\f(CW${\fR brace is still an open and expected to have a matching close, because
it's likely to be a deref or delimiter,
.Sp
.Vb 1
\&    Deref with ${foo()} etc etc.
.Ve
.Sp
Variables or expressions like this will often be in \f(CW\*(C`C<>\*(C'\fR markup
and skipped for that reason instead, as described above.
.IP "\(bu" 4
\&\f(CW$)\fR and \f(CW$]\fR are optional closes, since they might be Perl variables to
skip, or might be \*(L"$\*(R" at the end of a parens,
.Sp
.Vb 1
\&   blah blah (which in TeX is $1\ecdot2$).
.Ve
.Sp
Perhaps the conditions for these will be restricted a bit, though again
\&\f(CW\*(C`C<>\*(C'\fR markup around sample code like this will be usual.
.IP "\(bu" 4
\&\f(CW\*(C`L<display|link>\*(C'\fR links are processed as the \*(L"display\*(R" text part.
The link target (\s-1POD\s0 document name and section) can have anything.
.PP
\&\f(CW\*(C`=begin :foo\*(C'\fR ... \f(CW\*(C`=end :foo\*(C'\fR sections with a format name \*(L":foo\*(R" starting
with a \*(L":\*(R" are \s-1POD\s0 markup and are processed accordingly.  Other \f(CW\*(C`=begin\*(C'\fR
sections are skipped.
.SS "Unrecognised Forms"
.IX Subsection "Unrecognised Forms"
A mathematical half-open range like the following is not recognised.
.PP
.Vb 1
\&    [1,2)             # bad, currently
.Ve
.PP
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 \f(CW\*(C`=for\*(C'\fR 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.
.PP
Parens spanning multiple paragraphs are not recognised,
.PP
.Vb 1
\&    (This is some     # bad
\&
\&    thing.)           # bad
.Ve
.PP
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.
.SS "Disabling"
.IX Subsection "Disabling"
If an unbalanced paren is intended you can add an \f(CW\*(C`=for\*(C'\fR to tell
\&\f(CW\*(C`ProhibitUnbalancedParens\*(C'\fR to allow it.
.PP
.Vb 1
\&    =for ProhibitUnbalancedParens allow next
\&
\&    Something ( deliberately unclosed.
.Ve
.PP
Or with a count of paragraphs to ignore,
.PP
.Vb 1
\&    =for ProhibitUnbalancedParens allow next 2
\&
\&    First deliberate [ unclosed.
\&
\&    Second (.
.Ve
.PP
The usual no critic
.PP
.Vb 1
\&    ## no critic (ProhibitUnbalancedParens)
.Ve
.PP
works too as a whole-file disable, but the annotation must be before any
\&\f(CW\*(C`_\|_END_\|_\*(C'\fR token, and if the \s-1POD\s0 is after the \f(CW\*(C`_\|_END_\|_\*(C'\fR then
\&\f(CW\*(C`Perl::Critic\*(C'\fR 1.112 up is required.  Individual \f(CW\*(C`=for\*(C'\fR has the advantage
of being with an exception.
.PP
As always if you don't care about this at all you can disable
\&\f(CW\*(C`ProhibitUnbalancedParens\*(C'\fR completely from your \fI.perlcriticrc\fR in
the usual way (see \*(L"\s-1CONFIGURATION\*(R"\s0 in Perl::Critic),
.PP
.Vb 1
\&    [\-Documentation::ProhibitUnbalancedParens]
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Perl::Critic::Pulp,
Perl::Critic
.PP
<http://user42.tuxfamily.org/perl\-pod\-gt/index.html>
.SH "HOME PAGE"
.IX Header "HOME PAGE"
http://user42.tuxfamily.org/perl\-critic\-pulp/index.html
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2011, 2012, 2013, 2014, 2015, 2016, 2017 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 <http://www.gnu.org/licenses/>.