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, tied, untie) and the full method menus per variable type are already documented on the 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 - TIESCALAR, FETCH, STORE, DESTROY. The smallest tie interface; start here to learn the shape of all the others.

  • Tied hashes - TIEHASH plus the iteration protocol (FIRSTKEY / NEXTKEY), EXISTS, DELETE, CLEAR, and SCALAR. The richest of the data types.

  • Tied arrays - TIEARRAY, the size protocol (FETCHSIZE / STORESIZE / EXTEND), and the mutators (PUSH, POP, SHIFT, UNSHIFT, SPLICE).

  • Tied 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 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.