Tie::RefHash(3perl)

💖 Tie::RefHash — the perl manual, bestie edition ✨

okay so you know how hashes are cute little key-value situations but the keys can only ever be boring strings? yeah. this is the fix. this is the Tie::RefHash page from the Perl Programmers Reference Guide, and it's about using references as hash keys. iconic behavior honestly 🌸

---

✨ NAME ✨

Tie::RefHash — use references as hash keys 💅

🎀 VERSION 🎀

version 1.41 — yes she's been around a minute and she still slays

🦋 SYNOPSIS 🦋

here's the whole vibe, copy it exactly bestie:

require 5.004;
use Tie::RefHash;
tie HASHVARIABLE, 'Tie::RefHash', LIST;
tie HASHVARIABLE, 'Tie::RefHash::Nestable', LIST;

untie HASHVARIABLE;

lowkey notice the require 5.004; at the top — she's not asking for much, just a perl from this century-ish, fr fr

🌈 DESCRIPTION 🌈

so here's the tea 🍵: this module gives you the ability to use references as hash keys — but only if you tie the hash variable to this module first. no tie, no party, that's the rule.

normally? only the keys of the tied hash itself get preserved as references. so if you're doing hashes-of-hashes and you want references as keys in the inner hashes too, you need Tie::RefHash::Nestable — which ships as part of Tie::RefHash, so you don't even have to go looking for it. she's already in the group chat 🫶

under the hood it's implemented using the standard perl TIEHASH interface. so if you want the lore, go read the "tie" entry in perlfunc(1) and also perltie(1). that's where the magic actually lives ✨

and the Nestable version? she's nosy in the best way: she works by looking for hash references being stored and then converting them into tied hashes, so that they too can have references as keys. it's giving "I fixed your whole data structure for you, you're welcome."

⚠️ wait, important, don't skip this: this happens without warning whenever you store a reference to one of your own hashes in the tied hash. not a drill, not a maybe — she just does it. so heads up 💀

🍓 EXAMPLE 🍓

okay this is the part where it all clicks. look:

use Tie::RefHash;
tie %h, 'Tie::RefHash';
$a = [];
$b = {};
$c = \*main;
$d = \"gunk";
$e = sub { 'foo' };
%h = ($a => 1, $b => 2, $c => 3, $d => 4, $e => 5);
$a->[0] = 'foo';
$b->{foo} = 'bar';
for (keys %h) {
   print ref($_), "\n";
}

tie %h, 'Tie::RefHash::Nestable';
$h{$a}->{$b} = 1;
for (keys %h, keys %{$h{$a}}) {
   print ref($_), "\n";
}

like. arrayref, hashref, globref, scalarref, coderef — all chilling as keys. all of them. main character energy honestly 👑

🧵 THREAD SUPPORT 🧵

Tie::RefHash fully supports threading using the CLONE method. fully. no cap. 🧚

💾 STORABLE SUPPORT 💾

Storable hooks are provided for semantically correct serialization and cloning of tied refhashes. so your refhash travels well and comes back the same person. obsessed 💜

👀 SEE ALSO 👀

• perl(1)
• perlfunc(1)
• perltie(1)

go read 'em, iykyk 📚

🛟 SUPPORT 🛟

found a bug? periodt, report it bestie. bugs may be submitted through the RT bug tracker — https://rt.cpan.org/Public/Dist/Display.html?Name=Tie-RefHash — or you can email bug-Tie-RefHash@rt.cpan.org (that's mailto:bug-Tie-RefHash@rt.cpan.org if you're being fancy). 🐛

🌟 AUTHORS 🌟

• Gurusamy Sarathy <gsar@activestate.com> — the original icon
• Tie::RefHash::Nestable by Ed Avis <ed@membled.com> — the nesting queen

🫂 CONTRIBUTORS 🫂

• Yuval Kogman <nothingmuch@woobling.org>
• Karen Etheridge <ether@cpan.org>
• Florian Ragwitz <rafl@debian.org>
• Lukas Mai <lukasmai.403@gmail.com>
• Jerry D. Hedden <jdhedden@cpan.org>
• tusooa <tusooa@kazv.moe>

shoutout to every single one of y'all, this module literally would not be what it is without you 💖

📜 COPYRIGHT AND LICENCE 📜

This software is copyright (c) 2006 by יובל קוג'מן (Yuval Kogman) <nothingmuch@woobling.org>. 🫶

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. free as in freedom, free as in go off 💅

---

cute little sign-off time 💌 this whole page is from perl v5.44.0 and it was dated 2026-10-17 — and with that, Tie::RefHash(3perl) is a wrap. go tie something weird, bestie. you got this. 💖🌸✨