# Tying variables

A **tied** variable looks like an ordinary scalar, array, hash, or
filehandle, but every read, write, and iteration on it is rerouted
through methods you write. The variable is the public face; a class
of your design is the machinery behind it. Assigning to a tied
scalar calls your `STORE`; reading a tied hash key calls your
`FETCH`; running `keys` over a tied hash drives your `FIRSTKEY` and
`NEXTKEY`. The caller writes plain Perl and never sees the class.

That indirection is what makes tie powerful. A hash can be a façade
over an on-disk database. A scalar can recompute itself on every
read. A filehandle can collect everything printed to it into a
string. The code using the variable does not change; only the class
behind it does.

This guide is about **writing the class** - the part `perltie`
calls the implementation. The built-in side ([`tie`](../../p5/core/perlfunc/tie),
[`tied`](../../p5/core/perlfunc/tied), [`untie`](../../p5/core/perlfunc/untie))
and the full method menus per variable type are already documented
on the [`tie`](../../p5/core/perlfunc/tie) reference page. This guide
links there for signatures and concentrates on what those pages do
not teach: how to build a working tie class, what each method must
return, and exactly when the runtime calls it.

## Which chapter you want

Each variable type has its own constructor and its own method set.
Read the chapter that matches the sigil in front of you.

- [Tied scalars](scalars) - `TIESCALAR`, `FETCH`, `STORE`,
  `DESTROY`. The smallest tie interface; start here to learn the
  shape of all the others.
- [Tied hashes](hashes) - `TIEHASH` plus the iteration protocol
  (`FIRSTKEY` / `NEXTKEY`), `EXISTS`, `DELETE`, `CLEAR`, and
  `SCALAR`. The richest of the data types.
- [Tied arrays](arrays) - `TIEARRAY`, the size protocol
  (`FETCHSIZE` / `STORESIZE` / `EXTEND`), and the mutators
  (`PUSH`, `POP`, `SHIFT`, `UNSHIFT`, `SPLICE`).
- [Tied filehandles](filehandles) - `TIEHANDLE` and the I/O hooks
  (`PRINT`, `PRINTF`, `WRITE`, `READLINE`, `READ`, `GETC`, and
  friends).

## How each chapter is built

Every chapter follows the same shape:

- **The contract by example.** Rather than restate the method menu
  (the [`tie`](../../p5/core/perlfunc/tie) reference page already
  lists every signature), each chapter builds one complete, runnable
  class and explains each method as it appears.
- **Call timing.** The non-obvious part of tie is *when* the runtime
  invokes each hook - which operator triggers which method, in which
  context, with which arguments. Each chapter spells this out.
- **Minimum viable vs. full.** The fewest methods you can define and
  still have a usable tie, then the rest of the menu and what each
  one buys you.
- **The easy way.** Each data type ships a `Tie::*` base class that
  implements the tedious methods in terms of a few core ones.
  Inherit from it and override only the interesting hooks.

## What ties cost

Every operation on a tied variable is a method call. A tied hash
lookup is a `FETCH` dispatch where a plain hash lookup is a single
memory access - visibly slower in a tight loop. Tie is the right
tool when the indirection earns its keep (a variable backed by a
file, a computed value, a logging façade), not when you simply want
a fancier hash. For bulk work over a tied container, read it into a
plain array or hash once, operate, and write back.

## Differences from upstream

The tie mechanism is Perl 5.42's own, so tie classes behave exactly as
they do on upstream Perl.

```{toctree}
:maxdepth: 1
:hidden:

scalars
hashes
arrays
filehandles
```