.\" 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
.    \}
.\}
.\"
.\" 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::ProhibitCaptureWithoutTest 3pm"
.TH Perl::Critic::Policy::RegularExpressions::ProhibitCaptureWithoutTest 3pm "2018-07-27" "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::RegularExpressions::ProhibitCaptureWithoutTest \- Capture variable used outside conditional.
.SH "AFFILIATION"
.IX Header "AFFILIATION"
This Policy is part of the core Perl::Critic
distribution.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
If a regexp match fails, then any capture variables (\f(CW$1\fR, \f(CW$2\fR,
\&...) will be unaffected.  They will retain whatever old values they may
have had.  Therefore it's important to check the return value of a match
before using those variables.
.PP
.Vb 4
\&    \*(Aq12312123\*(Aq =~ /(2)/;
\&    print $1;    # Prints 2
\&    \*(Aq123123123\*(Aq =~ /(X)/;
\&    print $1;    # Prints 2, because $1 has not changed.
.Ve
.PP
Note that because the values of \f(CW$1\fR etc will be unaffected, you cannot
determine if a match succeeded by checking to see if the capture variables
have values.
.PP
.Vb 5
\&    # WRONG
\&    $str =~ /foo(.+)/;
\&    if ( $1 ) {
\&        print "I found $1 after \*(Aqfoo\*(Aq";
\&    }
.Ve
.PP
This policy checks that the previous regexp for which the capture
variable is in-scope is either in a conditional or causes an exception
or other control transfer (i.e. \f(CW\*(C`next\*(C'\fR, \f(CW\*(C`last\*(C'\fR, \f(CW\*(C`redo\*(C'\fR, \f(CW\*(C`return\*(C'\fR, or
sometimes \f(CW\*(C`goto\*(C'\fR) if the match fails.
.PP
A \f(CW\*(C`goto\*(C'\fR is only accepted by this policy if it is a co-routine call
(i.e.  \f(CW\*(C`goto &foo\*(C'\fR) or a \f(CW\*(C`goto LABEL\*(C'\fR where the label does not fall
between the \f(CW\*(C`goto\*(C'\fR and the capture variable in the scope of the
\&\f(CW\*(C`goto\*(C'\fR. A computed \f(CW\*(C`goto\*(C'\fR (i.e. something like \f(CW\*(C`goto (qw{foo bar
baz})[$i]\*(C'\fR) is not accepted by this policy because its target can not be
statically determined.
.PP
This policy does not check whether that conditional is actually
testing a regexp result, nor does it check whether a regexp actually
has a capture in it.  Those checks are too hard.
.PP
This policy also does not check arbitrarily complex conditionals guarding
regexp results, for pretty much the same reason.  Simple things like
.PP
.Vb 2
\& m/(foo)/ or die "No foo!";
\& die "No foo!" unless m/(foo)/;
.Ve
.PP
will be handled, but something like
.PP
.Vb 4
\& m/(foo)/ or do {
\&   ... lots of complicated calculations here ...
\&   die "No foo!";
\& };
.Ve
.PP
are beyond its scope.
.SH "CONFIGURATION"
.IX Header "CONFIGURATION"
By default, this policy considers \f(CW\*(C`die\*(C'\fR, \f(CW\*(C`croak\*(C'\fR, and \f(CW\*(C`confess\*(C'\fR to
throw exceptions. If you have additional subroutines or methods that may
be used in lieu of one of these, you can configure them in your
perlcriticrc as follows:
.PP
.Vb 2
\& [RegularExpressions::ProhibitCaptureWithoutTest]
\& exception_source = my_exception_generator
.Ve
.SH "BUGS"
.IX Header "BUGS"
This policy does not recognize named capture variables. Yet.
.SH "AUTHOR"
.IX Header "AUTHOR"
Chris Dolan <cdolan@cpan.org>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2006\-2017 Chris Dolan.
.PP
This program is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.