Tie::Hash(3perl)

💖 Tie::Hash — bestie, we're tying hashes today 💖

okay so real talk: this is Tie::Hash, Tie::StdHash, and Tie::ExtraHash, and they're the base class definitions for tied hashes. Think of them as the blueprint besties that let you make a hash act however you want. tying hash classes? we're doing it. 🎀

---

✨ SYNOPSIS ✨

package NewHash;
require Tie::Hash;

@ISA = qw(Tie::Hash);

sub DELETE { ... }          # Provides needed method
sub CLEAR { ... }           # Overrides inherited method

package NewStdHash;
require Tie::Hash;

@ISA = qw(Tie::StdHash);

# All methods provided by default, define
# only those needing overrides
# Accessors access the storage in %{$_[0]};
# TIEHASH should return a reference to the actual storage
sub DELETE { ... }

package NewExtraHash;
require Tie::Hash;

@ISA = qw(Tie::ExtraHash);

# All methods provided by default, define
# only those needing overrides
# Accessors access the storage in %{$_[0][0]};
# TIEHASH should return an array reference with the first element
# being the reference to the actual storage
sub DELETE {
  $_[0][1]->('del', $_[0][0], $_[1]); # Call the report writer
  delete $_[0][0]->{$_[1]};           #  $_[0]->SUPER::DELETE($_[1])
}

package main;

tie %new_hash, 'NewHash';
tie %new_std_hash, 'NewStdHash';
tie %new_extra_hash, 'NewExtraHash',
    sub {warn "Doing \U$_[1]\E of $_[2].\n"};

---

🌸 DESCRIPTION 🌸

So this module hands you some skeletal methods for hash-tying classes. Like, the bones. The scaffolding. If you wanna know the full list of functions you need to actually tie a hash to a package, go read perltie, it's all there. 🦋

The basic Tie::Hash package gives you a new method, plus the methods TIEHASH, EXISTS and CLEAR. Then Tie::StdHash and Tie::ExtraHash come in and provide most of the methods for hashes that perltie describes — the exceptions being UNTIE and DESTROY, bestie, don't forget those two. 💀

What do they do? They make tied hashes behave exactly like standard hashes, and they let you selectively overwrite methods. Iconic behaviour honestly. 👑

Also, Tie::Hash has legacy support for the new method: it gets used if TIEHASH is not defined, in the case a class forgets to include a TIEHASH method. Yes, it's the backup plan, the "forgot my keys" moment. 🙈

---

🧚 For everyone writing their own tied hashes 🧚

If you're a dev who wants to write their own tied hashes, here are the required methods, briefly defined. The perltie section has the more detailed descriptions and example code, so go there if you want the full meal:

• TIEHASH classname, LIST — the method that the command tie %hash, classname invokes. It associates a new hash instance with the specified class. LIST is the extra arguments (like the ones AnyDBM_File and its compatriots take) that are needed to complete the association.
• STORE this, key, value — store the datum value into key for the tied hash this.
• FETCH this, key — retrieve the datum in key for the tied hash this.
• FIRSTKEY this — return the first key in the hash.
• NEXTKEY this, lastkey — return the next key in the hash.
• EXISTS this, key — verify that key exists with the tied hash this.

The Tie::Hash implementation is a stub that simply croaks. so like, don't count on it bestie 😭

• DELETE this, key — delete the key key from the tied hash this.
• CLEAR this — clear all values from the tied hash this.
• SCALAR this — returns what evaluating the hash in scalar context yields.

Tie::Hash does not implement this method (but Tie::StdHash and Tie::ExtraHash do). no cap.

---

🎀 Inheriting from Tie::StdHash 🎀

The accessor methods assume the actual storage for the data in the tied hash lives in the hash referenced by tied(%tiedhash). So your overwritten TIEHASH method should return a hash reference, and all the other methods should operate on the hash referenced by the first argument:

package ReportHash;
our @ISA = 'Tie::StdHash';

sub TIEHASH  {
  my $storage = bless {}, shift;
  warn "New ReportHash created, stored in $storage.\n";
  $storage
}
sub STORE    {
  warn "Storing data with key $_[1] at $_[0].\n";
  $_[0]{$_[1]} = $_[2]
}

---

🦋 Inheriting from Tie::ExtraHash 🦋

Same vibe, different storage spot. The accessor methods assume the actual storage for the data in the tied hash lives in the hash referenced by (tied(%tiedhash))->[0]. So your overwritten TIEHASH method should return an array reference with the first element being a hash reference, and all the remaining methods should operate on the hash %{ $_[0]->[0] }:

package ReportHash;
our @ISA = 'Tie::ExtraHash';

sub TIEHASH  {
  my $class = shift;
  my $storage = bless [{}, @_], $class;
  warn "New ReportHash created, stored in $storage.\n";
  $storage;
}
sub STORE    {
  warn "Storing data with key $_[1] at $_[0].\n";
  $_[0][0]{$_[1]} = $_[2]
}

The default TIEHASH method stores the "extra" arguments to tie() starting from offset 1 in the array referenced by tied(%tiedhash). That's the same storage algorithm as in the TIEHASH subroutine above, fr fr. Which means: a typical package inheriting from Tie::ExtraHash does not need to overwrite this method. free real estate. 💅

---

💜 SCALAR, UNTIE and DESTROY 💜

okay listen. The methods UNTIE and DESTROY are not defined in Tie::Hash, Tie::StdHash, or Tie::ExtraHash. Tied hashes don't require these methods to exist, but if you do define them, they'll be called in proper time — see perltie for that whole situation. ⭐

SCALAR is only defined in Tie::StdHash and Tie::ExtraHash.

If you need them, these methods should be defined by the package inheriting from Tie::Hash, Tie::StdHash, or Tie::ExtraHash. And if you're wondering what happens when SCALAR doesn't exist? Go read "SCALAR" in perltie, bestie, it's all explained there. 🫶

---

🌈 MORE INFORMATION 🌈

The packages relating to the various DBM-related implementations (DB_File, NDBM_File, etc.) show examples of general tied hashes — and so does the Config module. Do they use Tie::Hash? Lowkey no. But they serve as good working examples, so go look at them anyway. iykyk ✨

---

and that's the whole page, bestie!! this was written by perl v5.44.0 and dated 2026-10-17. slay, ate, no crumbs. 💖🎀🦋🌸💅👑🌈💜