.\" 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::Subroutines::RequireArgUnpacking 3pm"
.TH Perl::Critic::Policy::Subroutines::RequireArgUnpacking 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::Subroutines::RequireArgUnpacking \- Always unpack "@_" first.
.SH "AFFILIATION"
.IX Header "AFFILIATION"
This Policy is part of the core Perl::Critic
distribution.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Subroutines that use \f(CW@_\fR directly instead of unpacking the arguments
to local variables first have two major problems.  First, they are
very hard to read.  If you're going to refer to your variables by
number instead of by name, you may as well be writing assembler code!
Second, \f(CW@_\fR contains aliases to the original variables!  If you
modify the contents of a \f(CW@_\fR entry, then you are modifying the
variable outside of your subroutine.  For example:
.PP
.Vb 7
\&   sub print_local_var_plus_one {
\&       my ($var) = @_;
\&       print ++$var;
\&   }
\&   sub print_var_plus_one {
\&       print ++$_[0];
\&   }
\&
\&   my $x = 2;
\&   print_local_var_plus_one($x); # prints "3", $x is still 2
\&   print_var_plus_one($x);       # prints "3", $x is now 3 !
\&   print $x;                     # prints "3"
.Ve
.PP
This is spooky action-at-a-distance and is very hard to debug if it's
not intentional and well-documented (like \f(CW\*(C`chop\*(C'\fR or \f(CW\*(C`chomp\*(C'\fR).
.PP
An exception is made for the usual delegation idiom \f(CW\*(C`$object\->SUPER::something( @_ )\*(C'\fR. Only \f(CW\*(C`SUPER::\*(C'\fR and \f(CW\*(C`NEXT::\*(C'\fR are
recognized (though this is configurable) and the argument list for the
delegate must consist only of \f(CW\*(C`( @_ )\*(C'\fR.
.SH "CONFIGURATION"
.IX Header "CONFIGURATION"
This policy is lenient for subroutines which have \f(CW\*(C`N\*(C'\fR or fewer
top-level statements, where \f(CW\*(C`N\*(C'\fR defaults to \s-1ZERO.\s0  You can override
this to set it to a higher number with the
\&\f(CW\*(C`short_subroutine_statements\*(C'\fR setting.  This is very much not
recommended but perhaps you \s-1REALLY\s0 need high performance.  To do this,
put entries in a \fI.perlcriticrc\fR file like this:
.PP
.Vb 2
\&  [Subroutines::RequireArgUnpacking]
\&  short_subroutine_statements = 2
.Ve
.PP
By default this policy does not allow you to specify array subscripts
when you unpack arguments (i.e. by an array slice or by referencing
individual elements).  Should you wish to permit this, you can do so
using the \f(CW\*(C`allow_subscripts\*(C'\fR setting. This defaults to false.  You can
set it true like this:
.PP
.Vb 2
\&  [Subroutines::RequireArgUnpacking]
\&  allow_subscripts = 1
.Ve
.PP
The delegation logic can be configured to allow delegation other than to
\&\f(CW\*(C`SUPER::\*(C'\fR or \f(CW\*(C`NEXT::\*(C'\fR. The configuration item is
\&\f(CW\*(C`allow_delegation_to\*(C'\fR, and it takes a space-delimited list of allowed
delegates. If a given delegate ends in a double colon, anything in the
given namespace is allowed. If it does not, only that subroutine is
allowed. For example, to allow \f(CW\*(C`next::method\*(C'\fR from \f(CW\*(C`Class::C3\*(C'\fR and
_delegate from the current namespace in addition to \s-1SUPER\s0 and \s-1NEXT,\s0 the
following configuration could be used:
.PP
.Vb 2
\&  [Subroutines::RequireArgUnpacking]
\&  allow_delegation_to = next::method _delegate
.Ve
.SH "CAVEATS"
.IX Header "CAVEATS"
\&\s-1PPI\s0 doesn't currently detect anonymous subroutines, so we don't check
those.  This should just work when \s-1PPI\s0 gains that feature.
.PP
We don't check for \f(CW@ARG\fR, the alias for \f(CW@_\fR from English.pm.  That's
deprecated anyway.
.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