# References

A reference is a scalar that *points to* another value. References
are how Perl builds nested data structures — arrays of arrays,
hash of hashes, hash of arrays of hashes — because the basic
container types (arrays, hashes) flatten when they appear in lists,
and a reference is a single scalar that survives the flattening.

```perl
my @arr = (1, 2, 3);
my $ref = \@arr;             # take a reference to @arr
$$ref[0]                     # full deref form     — 1
$ref->[0]                    # arrow shorthand     — 1
@$ref                        # whole-array deref   — (1, 2, 3)
```

A reference is itself a scalar. It can be passed through any
list-flattening calling convention without losing its identity,
stored in arrays and hashes, returned from subs, weakened,
serialised — anywhere a scalar can go.

## Things you can reference

Seven things take a reference:

```perl
\$scalar             # SCALAR ref
\@array              # ARRAY ref
\%hash               # HASH ref
\&subroutine         # CODE ref
\*glob               # GLOB ref
\\$scalar            # REF (a reference to a reference)
\$file_handle        # IO ref (reference to a filehandle)
```

Plus the **anonymous** constructors, which build the value and
return a reference in one step:

```perl
my $aref = [1, 2, 3];                  # anonymous array
my $href = { name => 'Alice', age => 30 };  # anonymous hash
my $cref = sub { $_[0] * 2 };          # anonymous sub
```

The bracket-vs-paren distinction is essential: `(1, 2, 3)` is a
**list**, `[1, 2, 3]` is an **anonymous array reference**. The
first flattens; the second does not.

## Dereferencing

Four spellings, in increasing order of how often they appear in
modern code:

```perl
${$sref}             # full sigil-deref form
$$sref               # short sigil-deref form (only if name is simple)
$sref->{key}         # arrow form (postfix; for arrays and hashes)
$sref->[0]           # same, for arrays
```

The `->` arrow form is the idiomatic spelling for nested access:

```perl
$config->{database}{host}            # arrow elision between subscripts
$config->{database}->{host}          # explicit; same meaning
${$config->{database}}{host}         # full form; the same again
```

Between two consecutive subscripts the `->` is **optional** (the
”arrow elision“ rule); at the head of a chain it is required:

```perl
$ref->[0]                     # required arrow at the head
$ref->[0][1]                  # second arrow elided
$ref->[0]->[1]                # equivalent
[1,2,3]->[0]                  # required arrow on an anonymous ref
```

Whole-container deref:

```perl
@$aref                        # the whole array
%$href                        # the whole hash, as flat key/value list
&$cref(@args)                 # call the sub
$cref->(@args)                # idiomatic call form
```

Use the curly-braced form `@{ EXPR }` / `%{ EXPR }` when the deref
target is an expression more complex than a bare scalar variable:

```perl
my @found = @{ $config->{users} };   # deref a chain — needs braces
```

See [arrow](../perlop/arrow.md) for the operator and
[subscript](../perlop/subscript.md) for the bracket family.

## What `ref` returns

[`ref`](../perlfunc/ref.md) reports the kind of thing a reference
points to:

```perl
ref \$scalar         # 'SCALAR'
ref \@array          # 'ARRAY'
ref \%hash           # 'HASH'
ref \&sub            # 'CODE'
ref \*FH             # 'GLOB'
ref \\$scalar        # 'REF'    — a ref-to-ref
ref \$io_handle      # 'IO'     — wrapper around a file handle

ref [1, 2, 3]        # 'ARRAY'
ref { a => 1 }       # 'HASH'
ref sub {}           # 'CODE'

ref bless {}, 'Foo'  # 'Foo'    — blessed; class name not 'HASH'
ref 42               # ''       — not a reference at all
ref undef            # ''
```

For blessed objects, `ref` returns the class. To distinguish a
blessed hash-ref from a plain hash-ref, use
[`Scalar::Util::reftype`](../../Scalar/Util.md) (which always returns
the underlying container shape regardless of bless) or
[`isa`](../perlfunc/isa.md) (the inheritance-aware check).

## Postfix dereference (`@*`, `%*`, `$*`)

Perl 5.20+ added a postfix syntax that mirrors the arrow chain:

```perl
$ref->@*               # equivalent to @$ref
$ref->%*               # equivalent to %$ref
$ref->$*               # equivalent to $$ref

$ref->@[1, 3]          # array slice through ref — equivalent to @{$ref}[1,3]
$ref->%[1, 3]          # key/value slice
$ref->@{qw(a b)}       # hash slice
```

The postfix forms read left-to-right with the rest of an arrow
chain, which is often clearer when the deref target is itself
a chain:

```perl
$config->{users}->@*             # all users — chains naturally
@{$config->{users}}              # same; reads right-to-left
```

Pick the form that reads better in context. Postfix is the
clearer choice in chains; the leading-sigil form is shorter for
plain scalar refs.

## Autovivification

Reading or writing through a deref into a slot that doesn’t exist
yet auto-creates the intermediate structure:

```perl
my %h;
$h{a}{b}{c} = 1;
# %h is now (a => { b => { c => 1 } })  — three nested hashes built
```

The mechanism: when the assignment target is `$h{a}{b}{c}`, Perl
sees `$h{a}` is `undef`, the next subscript is `{b}` (a hash
subscript), so it makes `$h{a}` a fresh hash ref. Then `$h{a}{b}`
is `undef`, next subscript is `{c}` (also hash), so make it a
fresh hash ref. Then assign `1` to the leaf.

The same happens for array subscripts:

```perl
my %by_dept;
push @{ $by_dept{eng} }, 'Alice';
# $by_dept{eng} did not exist; the push autoviv'd it as an arrayref
```

Autoviv on the **left** of an assignment (or a `push`/`pop`/…
mutator) is what makes this work. Autoviv on the **right** of an
expression is more dangerous — *reading* `$h{a}{b}{c}` when `$h{a}`
is `undef` *also* autovivifies, populating the hash as a side
effect of inspection:

```perl
my %h;
exists $h{a}{b};         # accidentally creates $h{a} = {} as a hash!
                          # %h is now (a => {})
```

The fix when you genuinely just want to test: chain `exists`:

```perl
exists $h{a} && exists $h{a}{b};        # short-circuits if $h{a} absent
```

This is the most-bitten autoviv trap. Tests of nested existence
must short-circuit, or they leave hash slots behind.

## Hash of arrays — the canonical example

```perl
my @people = (
    { name => 'Alice', dept => 'eng'   },
    { name => 'Bob',   dept => 'sales' },
    { name => 'Carol', dept => 'eng'   },
    { name => 'Dan',   dept => 'sales' },
);

# Group by department:
my %by_dept;
for my $p (@people) {
    push @{ $by_dept{ $p->{dept} } }, $p->{name};
}
# %by_dept = (
#     eng   => ['Alice', 'Carol'],
#     sales => ['Bob', 'Dan'],
# )

# Iterate:
for my $dept (sort keys %by_dept) {
    print "$dept: @{ $by_dept{$dept} }\n";
}
# eng: Alice Carol
# sales: Bob Dan
```

The `@{ $by_dept{...} }` is the deref-with-braces form. It’s
necessary because the deref target is an expression
(`$by_dept{$dept}`), not a bare variable.

The same shape with the postfix form:

```perl
print "$dept: ", join(' ', $by_dept{$dept}->@*), "\n";
```

Pick whichever you find clearer; both are idiomatic in modern
Perl.

## Weak references and circular structures

A reference holds the referent alive (refcount-bumped) until the
reference itself goes out of scope. This becomes a problem when
two structures point at each other:

```perl
my $parent = { name => 'p' };
my $child  = { name => 'c', parent => $parent };
push @{ $parent->{children} }, $child;

# parent refers to child via the children arrayref
# child refers back to parent via the parent slot
# When both go out of scope, neither's refcount can reach 0 — leak.
```

The fix is a **weak reference** — a reference that doesn’t bump
the refcount. The `$child->{parent}` slot is the one that should
be weakened (the back-pointer):

```perl
use Scalar::Util qw(weaken);

my $parent = { name => 'p' };
my $child  = { name => 'c', parent => $parent };
weaken $child->{parent};                 # break the cycle
push @{ $parent->{children} }, $child;
```

After weakening, `$child->{parent}` reads as the parent while it
exists, and silently becomes `undef` when the parent is freed. The
canonical place for `weaken` is on every back-pointer in a tree
structure where children point back at their parent.

The [`Scalar::Util::isweak`](../../Scalar/Util.md) predicate tests
whether a given reference is weakened.

## Reference equality

Two references are equal (numerically `==`, stringwise `eq`) if and
only if they refer to the **same** underlying value:

```perl
my @a = (1, 2, 3);
my $r1 = \@a;
my $r2 = \@a;
my $r3 = [1, 2, 3];      # different anonymous array

$r1 == $r2               # TRUE — same address
$r1 == $r3               # FALSE — different array, even though contents match
```

Numeric comparison of refs effectively compares their machine
address. Two refs with the same content but different identities
compare unequal. Deep-equal needs a helper from `Test::More` or a
hand-rolled walker.

A reference stringifies to something like `ARRAY(0x55ab12cd)` —
class name plus hex address. Don’t rely on the format; use it
only as a debug print.

## See also

- [Arrays](arrays.md), [Hashes](hashes.md) — the two containers most
  references point at.
- [Typeglobs](typeglobs.md) — `*name`, the symbol-table entry that
  references-to-globs let you alias.
- [Arrow operator](../perlop/arrow.md) — `->`, the deref shorthand.
- [Subscript](../perlop/subscript.md) — `[]` and `{}` through a ref.
- [`ref`](../perlfunc/ref.md) — what kind of thing does this point at.
- [`bless`](../perlfunc/bless.md) — make a reference into an object.
- [`Scalar::Util`](../../Scalar/Util.md) — `weaken`, `isweak`,
  `reftype`, `blessed`, `looks_like_number`.
- [References tutorial](../../../tutorial/reference/index.md) —
  step-by-step companion to this terse reference.
- [Weak refs tutorial](../../../tutorial/reference/weak-refs.md) —
  the cycle problem in depth.