NAME

       Perl::Critic::Policy::Subroutines::RequireArgUnpacking - Always unpack "@_" first.

AFFILIATION

       This Policy is part of the core Perl::Critic distribution.

DESCRIPTION

       Subroutines that use @_ 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, @_ contains aliases to the original variables!  If you modify the contents
       of a @_ entry, then you are modifying the variable outside of your subroutine.  For
       example:

          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"

       This is spooky action-at-a-distance and is very hard to debug if it's not intentional and
       well-documented (like "chop" or "chomp").

       An exception is made for the usual delegation idiom "$object->SUPER::something( @_ )".
       Only "SUPER::" and "NEXT::" are recognized (though this is configurable) and the argument
       list for the delegate must consist only of "( @_ )".

CONFIGURATION

       This policy is lenient for subroutines which have "N" or fewer top-level statements, where
       "N" defaults to ZERO.  You can override this to set it to a higher number with the
       "short_subroutine_statements" setting.  This is very much not recommended but perhaps you
       REALLY need high performance.  To do this, put entries in a .perlcriticrc file like this:

         [Subroutines::RequireArgUnpacking]
         short_subroutine_statements = 2

       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 "allow_subscripts" setting. This defaults to
       false.  You can set it true like this:

         [Subroutines::RequireArgUnpacking]
         allow_subscripts = 1

       The delegation logic can be configured to allow delegation other than to "SUPER::" or
       "NEXT::". The configuration item is "allow_delegation_to", 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 "next::method" from "Class::C3" and _delegate from the current namespace in
       addition to SUPER and NEXT, the following configuration could be used:

         [Subroutines::RequireArgUnpacking]
         allow_delegation_to = next::method _delegate

       Argument validation tools such as Params::Validate generate a closure which is used to
       unpack and validate the arguments of a subroutine. In order to recognize closures as a
       valid way to unpack arguments you must enable them explicitly:

         [Subroutines::RequireArgUnpacking]
         allow_closures = 1

CAVEATS

       PPI doesn't currently detect anonymous subroutines, so we don't check those.  This should
       just work when PPI gains that feature.

       We don't check for @ARG, the alias for @_ from English.pm.  That's deprecated anyway.

CREDITS

       Initial development of this policy was supported by a grant from the Perl Foundation.

AUTHOR

       Chris Dolan <cdolan@cpan.org>

COPYRIGHT

       Copyright (c) 2007-2023 Chris Dolan

       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 LICENSE file
       included with this module

perl v5.36.0                          Perl::Critic::Policy::Subroutines::RequireArgUnpacking(3pm)