.\" Automatically generated by Pod::Man 4.11 (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
..
.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
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Perl::Critic::Policy::RegularExpressions::ProhibitUnusedCapture 3pm"
.TH Perl::Critic::Policy::RegularExpressions::ProhibitUnusedCapture 3pm "2020-05-17" "perl v5.30.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"
Perl::Critic::Policy::RegularExpressions::ProhibitUnusedCapture \- Only use a capturing group if you plan to use the captured value.
.SH "AFFILIATION"
.IX Header "AFFILIATION"
This Policy is part of the core Perl::Critic
distribution.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Perl regular expressions have multiple types of grouping syntax.  The
basic parentheses (e.g. \f(CW\*(C`m/(foo)/\*(C'\fR) captures into the magic variable
\&\f(CW$1\fR.  Non-capturing groups (e.g. \f(CW\*(C`m/(?:foo)/\*(C'\fR are useful because
they have better runtime performance and do not copy strings to the
magic global capture variables.
.PP
It's also easier on the maintenance programmer if you consistently use
capturing vs. non-capturing groups, because that programmer can tell
more easily which regexps can be refactored without breaking
surrounding code which may use the captured values.
.SH "CONFIGURATION"
.IX Header "CONFIGURATION"
This Policy is not configurable except for the standard options.
.SH "CAVEATS"
.IX Header "CAVEATS"
.ie n .SS """qr//"" interpolation"
.el .SS "\f(CWqr//\fP interpolation"
.IX Subsection "qr// interpolation"
This policy can be confused by interpolation of \f(CW\*(C`qr//\*(C'\fR elements, but
those are always false negatives.  For example:
.PP
.Vb 2
\&    my $foo_re = qr/(foo)/;
\&    my ($foo) = m/$foo_re (bar)/x;
.Ve
.PP
A human can tell that this should be a violation because there are two
captures but only the first capture is used, not the second.  The
policy only notices that there is one capture in the regexp and
remains happy.
.ie n .SS """@\-"", ""@+"", $LAST_MATCH_START and $LAST_MATCH_END"
.el .SS "\f(CW@\-\fP, \f(CW@+\fP, \f(CW$LAST_MATCH_START\fP and \f(CW$LAST_MATCH_END\fP"
.IX Subsection "@-, @+, $LAST_MATCH_START and $LAST_MATCH_END"
This policy will only recognize capture groups referred to by these
variables if the use is subscripted by a literal integer.
.ie n .SS "$^N and $LAST_SUBMATCH_RESULT"
.el .SS "\f(CW$^N\fP and \f(CW$LAST_SUBMATCH_RESULT\fP"
.IX Subsection "$^N and $LAST_SUBMATCH_RESULT"
This policy will not recognize capture groups referred to only by these
variables, because there is in general no way by static analysis to
determine which capture group is referred to.  For example,
.PP
.Vb 1
\&    m/ (?: (A[[:alpha:]]+) | (N\ed+) ) (?{$foo=$^N}) /smx
.Ve
.PP
makes use of the first capture group if it matches, or the second
capture group if the first does not match but the second does.
.SH "CREDITS"
.IX Header "CREDITS"
Initial development of this policy was supported by a grant from the
Perl Foundation.
.SH "AUTHOR"
.IX Header "AUTHOR"
Chris Dolan <cdolan@cpan.org>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2007\-2011 Chris Dolan.  Many rights reserved.
.PP
This program is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.  The full text of this license
can be found in the \s-1LICENSE\s0 file included with this module