local (the keyword) has NOTHING to do with local variables. In Perl, you use my (the keyword) to declare local (i.e., lexically scoped, or 'lexical') variables.

The keyword local localizes a variable, whether it's named or anonymous or global (i.e., package variables, which are in the symbol table). To localize a variable is to stash away its value in such a way that exiting the enclosing scope will result in its being restored. For example:

use vars qw( $x );      # a package global

$x = 'outer';

# this block:
{
  my $save_x = $x;      # localize $x by saving its  value
  $x = 'inner';         # change $x to hearts content

  some_sub( $x );       # some_sub() sees $x with value 'inner'

  $x = $save_x;         # restore original value just before exiting b
+lock
}

# is functionally identical to this block:
{
  local $x = 'inner';

  some_sub( $x );
}

# in both cases, some_sub() is called with the package global $x set
# to 'inner' and in both cases, the value of $x is restored when the
# block exits, except in the 'local' case, it is not necessary to
# explicitly restore $x
[download]

One example of its use is with the Perl global, $/. Often, (in a subroutine, for example) it is necessary to set $/ = undef;, but to do so may break code which assumes its default value.

# need to 'slurp' in an entire file
{
  local $/ = undef;

  # (read the file, etc.)
}
# $/ is now restored to whatever it was before
[download]

Hopefully, this explains WHEN to use local.

Update: Whoops! I stand corrected (thanks, shotgunefx)! Starting with Perl 5.5, it became possible to localize arbitrary anonymous variables (e.g., local $obj->get_handle()->{some_property}->get_param("param1");). I never actually had a use for (and therefore never tried) localize a lexical; I suppose I just assumed that they could.

Apologies to all for suggesting that localizing a lexical was possible.

dmm

Not according to the perl I use. The code below dies with Can't localize lexical variable $bar at pack.pl line 10.

#!/usr/bin/perl     -w


$main::foo = 'global';
my $bar = "my";
print "foo is ",$foo,"\n";
print "my is ",$bar,"\n";
{
    local $foo;
    local $bar;  # Dies here.

    print "foo is ",$foo,"\n";
    print "foo is ",$main::foo,"\n";
    print "bar is ",$bar,"\n";

}
print "foo is ",$foo,"\n";
print "my is ",$bar,"\n";
[download]



-Lee

"To be civilized is to deny one's nature."

My mistake, lexicals cannot be localized. However, pretty much everything else can (properties of objects, hash values and array elements, etc.).

dmm