# Scoping: `my`, `our`, `local`, `state`

Inside a sub, four declarators control where a variable lives,
how long it lives, and who can see it. Pick the wrong one and
the sub leaks state, fails to capture properly in a closure, or
quietly clobbers something the caller relied on.

| Declarator   | Scope                    | Lifetime               | Typical use                              |
|--------------|--------------------------|------------------------|------------------------------------------|
| `my`         | lexical (the block)      | until the block ends   | the default; private locals              |
| `our`        | lexical alias to package | as long as the package | shared package globals with a short name |
| `local`      | dynamic (the call tree)  | until the block ends   | temporarily change a special variable    |
| `state`      | lexical (the block)      | program lifetime       | per-sub persistent state, init once      |

## `my` — lexical locals

`my` is the everyday declarator:

```perl
sub greet {
    my ($name) = @_;
    my $message = "Hello, $name!";
    return $message;
}
```

The variables exist for the duration of the call, are private
to the body, and are stored in the sub’s *pad* (one slot per
declared lexical). They are **not** visible to callers, callees,
or `eval`’d code that doesn’t textually nest inside the sub.

`my` variables are the only ones that close over correctly.
Closures capture *cells* in the surrounding pad, and only `my`
(and `state`) variables get pad cells.

## `our` — package globals with a lexical alias

```perl
package Counter;

sub increment {
    our $value;                  # alias to $Counter::value
    $value++;
    return $value;
}
```

`our $x` declares a *lexical alias* in the current scope to the
package variable `$Pkg::x`. The variable itself is global. If
two packages both `our`-declare `$VERSION`, they each get their
own — `our` prefixes with the current package name.

Use `our` when:

- You genuinely want a package-level shared variable.
- You want to silence `use strict 'vars';` complaints about a
  variable that *should* be a package global (`$VERSION`,
  `@ISA`, `@EXPORT`, `%ENV` aliases, …).

Do **not** use `our` to share state between subs in the same
file. That’s what `my` at file scope is for:

```perl
package Counter;

my $value = 0;                   # private to this package's file
sub increment { ++$value }
sub get       { $value   }
```

## `local` — dynamically-scoped temporary

`local` does *not* declare a new variable. It saves the current
value of an existing (typically global) variable, sets a new
value, and restores the old value when the enclosing block
exits — even on exception:

```perl
sub slurp {
    my ($path) = @_;
    open my $fh, '<', $path or die "open $path: $!";
    local $/;                    # slurp mode for this sub only
    return <$fh>;
}
```

Without the `local`, the caller’s `$/` would be permanently
clobbered. With it, the change is confined to the dynamic
extent of `slurp` — including any subs `slurp` happens to call.

`local` is the right tool for almost every special-variable
override (`$/`, `$\`, `$,`, `$_`, `$@`, signal handlers in
`%SIG`). It is rarely the right tool for ordinary user
variables — those want `my`.

For the full register, see [`local`](../perlfunc/local.md) and the
[error-state](../perlvar/error.md) and
[I/O](../perlvar/io.md) variable pages, which list which
specials want `local`-isation in which patterns.

## `state` — initialise once, keep forever

```perl
use feature 'state';

sub counter {
    state $n = 0;                # initialised once, ever
    return ++$n;
}

counter();                       # 1
counter();                       # 2
counter();                       # 3
```

`state` variables are lexicals that survive between calls. The
initialiser runs the first time control reaches the
declaration; subsequent calls skip it.

`state` is the right tool for:

- Per-sub caches and counters where the cost of constructing
  the data dominates and you don’t want a closure factory.
- One-time setup that depends on values not available at
  compile time:
  ```perl
  sub compiled_re {
      my ($pattern) = @_;
      state %cache;
      $cache{$pattern} //= qr/$pattern/;
      return $cache{$pattern};
  }
  ```

  (Note: this caches the *first* pattern only with a literal
  `state` of a single regex; the hash form generalises it.)

## Closures: capturing surrounding `my`

An anonymous sub captures every `my` (or `state`) variable from
its surrounding scope that it textually references:

```perl
sub make_adder {
    my ($n) = @_;
    return sub {
        my ($x) = @_;
        return $x + $n;          # captures $n
    };
}

my $add5 = make_adder(5);
my $add9 = make_adder(9);

$add5->(3);                      # 8
$add9->(3);                      # 12
```

Each call to `make_adder` creates a fresh `$n`, and the returned
closure references its own `$n`. Two calls produce two
independent counters / adders / state machines.

### The closure-over-loop-variable surprise

```perl
my @subs;
for my $i (1, 2, 3) {
    push @subs, sub { $i };
}

print $_->(), "\n" for @subs;
# 1
# 2
# 3   — fresh $i each iteration: each closure sees its own
```

This is the *correct* behaviour with `for my $i`: every
iteration declares a fresh `$i`, each closure captures its own.

The buggy shape is when `$i` is declared *outside* the loop:

```perl
my $i;
my @subs;
for $i (1, 2, 3) {               # NO `my` — same $i every iteration
    push @subs, sub { $i };
}

print $_->(), "\n" for @subs;
# 3
# 3
# 3   — all three closures share the one $i, and its final value is 3
```

Always declare loop variables with `my`. Closure capture
*follows the variable*, not the value, and «same variable» vs
«different variable» is decided at the `my` site.

### Capturing `our` and package globals

`our` aliases live for the whole package, so a closure
capturing `$Counter::value` shares state with every other
piece of code that touches `$Counter::value`. That’s almost
always not what you want — closures over package globals are a
sign that the design wants a `my` instead.

## Pad lifetime

Every active sub call has a **pad**, a slot per declared
lexical. The pad is what `my` writes into and what closures
hold a reference to. While a closure is alive, every pad it
captures is alive — even if the originating call has long
returned. This is how `make_adder`’s `$n` survives the call to
`make_adder` itself.

## See also

- [`my`](../perlfunc/my.md), [`our`](../perlfunc/our.md),
  [`local`](../perlfunc/local.md), [`state`](../perlfunc/state.md) —
  perlfunc detail pages for each declarator.
- [`@_`](../perlvar/default.md) — the one variable that’s *always*
  present in a sub regardless of declarators.
- [Declaration](declaration.md) — anonymous subs and the lexical
  `my sub` form.
- [Recursion](recursion.md) — closure-based trampolines and
  `__SUB__`.
- [Special variables](../perlvar.md) — almost every special wants
  `local`, not `my`.