.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Regexp::Common::balanced 3pm"
.TH Regexp::Common::balanced 3pm "2022-10-15" "perl v5.34.0" "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"
Regexp::Common::balanced \-\- provide regexes for strings with balanced
parenthesized delimiters or arbitrary delimiters.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Regexp::Common qw /balanced/;
\&
\&    while (<>) {
\&        /$RE{balanced}{\-parens=>\*(Aq()\*(Aq}/
\&                                   and print q{balanced parentheses\en};
\&    }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Please consult the manual of Regexp::Common for a general description
of the works of this interface.
.PP
Do not use this module directly, but load it via \fIRegexp::Common\fR.
.ie n .SS "$RE{balanced}{\-parens}"
.el .SS "\f(CW$RE{balanced}{\-parens}\fP"
.IX Subsection "$RE{balanced}{-parens}"
Returns a pattern that matches a string that starts with the nominated
opening parenthesis or bracket, contains characters and properly nested
parenthesized subsequences, and ends in the matching parenthesis.
.PP
More than one type of parenthesis can be specified:
.PP
.Vb 1
\&        $RE{balanced}{\-parens=>\*(Aq(){}\*(Aq}
.Ve
.PP
in which case all specified parenthesis types must be correctly balanced within
the string.
.PP
Since version 2013030901, \f(CW$1\fR will always be set (to the entire
matched substring), regardless whether \f(CW\*(C`{\-keep}\*(C'\fR is used or not.
.ie n .SS "$RE{balanced}{\-begin => ""begin""}{\-end => ""end""}"
.el .SS "\f(CW$RE{balanced}{\-begin => ``begin''}{\-end => ``end''}\fP"
.IX Subsection "$RE{balanced}{-begin => ""begin""}{-end => ""end""}"
Returns a pattern that matches a string that is properly balanced
using the \fIbegin\fR and \fIend\fR strings as start and end delimiters.
Multiple sets of begin and end strings can be given by separating
them by \f(CW\*(C`|\*(C'\fRs (which can be escaped with a backslash).
.PP
.Vb 1
\&    qr/$RE{balanced}{\-begin => "do|if|case"}{\-end => "done|fi|esac"}/
.Ve
.PP
will match properly balanced strings that either start with \fIdo\fR and
end with \fIdone\fR, start with \fIif\fR and end with \fIfi\fR, or start with
\&\fIcase\fR and end with \fIesac\fR.
.PP
If \fI\-end\fR contains less cases than \fI\-begin\fR, the last case of \fI\-end\fR
is repeated. If it contains more cases than \fI\-begin\fR, the extra cases
are ignored. If either of \fI\-begin\fR or \fI\-end\fR isn't given, or is empty,
\&\fI\-begin => '('\fR and \fI\-end => ')'\fR are assumed.
.PP
Since version 2013030901, \f(CW$1\fR will always be set (to the entire
matched substring), regardless whether \f(CW\*(C`{\-keep}\*(C'\fR is used or not.
.SS "Note"
.IX Subsection "Note"
Since version 2013030901 the pattern will make of the recursive construct
\&\f(CW\*(C`(?\-1)\*(C'\fR, instead of using the problematic \f(CW\*(C`(??{ })\*(C'\fR construct.
This fixes an problem that was introduced in the 5.17 development track.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Regexp::Common for a general description of how to use this interface.
.SH "AUTHOR"
.IX Header "AUTHOR"
Damian Conway (damian@conway.org)
.SH "MAINTENANCE"
.IX Header "MAINTENANCE"
This package is maintained by Abigail (\fIregexp\-common@abigail.be\fR).
.SH "BUGS AND IRRITATIONS"
.IX Header "BUGS AND IRRITATIONS"
Bound to be plenty.
.PP
For a start, there are many common regexes missing.
Send them in to \fIregexp\-common@abigail.be\fR.
.SH "LICENSE and COPYRIGHT"
.IX Header "LICENSE and COPYRIGHT"
This software is Copyright (c) 2001 \- 2017, Damian Conway and Abigail.
.PP
This module is free software, and maybe used under any of the following
licenses:
.PP
.Vb 4
\& 1) The Perl Artistic License.     See the file COPYRIGHT.AL.
\& 2) The Perl Artistic License 2.0. See the file COPYRIGHT.AL2.
\& 3) The BSD License.               See the file COPYRIGHT.BSD.
\& 4) The MIT License.               See the file COPYRIGHT.MIT.
.Ve