Tie::Memoize(3perl)

💖 Tie::Memoize — it's a Perl manual page, bestie 💖

okay so this is Tie::Memoize from the Perl Programmers Reference Guide, and it's genuinely one of the cutest little modules ever. it lets a tied hash lazily load its values — like, it doesn't do the work until you actually ask for something. main character energy tbh. 🦋

---

✨ NAME ✨

Tie::Memoize — add data to hash when needed 💅

---

🌸 SYNOPSIS 🌸

require Tie::Memoize;
tie %hash, 'Tie::Memoize',
    \&fetch,                  # The rest is optional
    $DATA, \&exists,
    {%ini_value}, {%ini_existence};

see that "the rest is optional" comment? that's not me being cute, that's fr in the source. the only thing you gotta pass is that \&fetch coderef. 🫶

---

💜 DESCRIPTION 💜

so this package lets a tied hash autoload its values on the first access, and then it uses the cached value on all the following accesses. one and done, no cap. ✨

here's the tea: only read-accesses — like fetching the value or checking exists — actually trigger calls to your functions. the modify-accesses just happen like they would on a normal, boring, non-tied hash. so writes don't bother your callbacks at all. 💅

the required arguments when you call tie are:

• the hash itself,
• the package ('Tie::Memoize'),
• and the reference to the FETCHing function.

the optional arguments are:

• an arbitrary scalar $data,
• the reference to the EXISTS function,
• initial values of the hash,
• and initial values of the existence cache.

both the FETCHing function and the EXISTS function have the same signature: the arguments they get are $key, $data, and that $data is literally the same value you passed in during tie()ing. 🎀

both functions should return an empty list if the value does not exist!!

if the EXISTS function is different from the FETCHing function, it should return a TRUE value on success. and the FETCHing function should return the intended value if the key is valid. that's it, that's the contract. 🧚

---

🦋 Inheriting from Tie::Memoize 🦋

if you're subclassing this (go off, icon), the structure of the tied() data is an array reference with these elements:

0:  cache of known values
1:  cache of known existence of keys
2:  FETCH  function
3:  EXISTS function
4:  $data

the rest of the array is for internal usage of this package, so like, don't touch it. 🙈

in particular, if TIEHASH is overwritten, it should call SUPER::TIEHASH. do not skip this. this is the vibe check.

---

🔥 EXAMPLE 🔥

sub slurp {
  my ($key, $dir) = shift;
  open my $h, '<', "$dir/$key" or return;
  local $/; <$h>                      # slurp it all
}
sub exists { my ($key, $dir) = shift; return -f "$dir/$key" }

tie %hash, 'Tie::Memoize', \&slurp, $directory, \&exists,
    { fake_file1 => $content1, fake_file2 => $content2 },
    { pretend_does_not_exists => 0, known_to_exist => 1 };

okay so what's happening here — this example treats the slightly modified contents of $directory as a hash. the modifications are:

• the keys fake_file1 and fake_file2 fetch values $content1 and $content2 respectively,
• and pretend_does_not_exists will never be accessed.

additionally, the existence of known_to_exist is never checked — so if it does not exist when its content is needed, the user of %hash may be confused. 😭 that's literally what the manpage says and i'm not editorializing, it's just true.

---

💀 BUGS 💀

FIRSTKEY and NEXTKEY methods go through the keys which were already read, not all the possible keys of the hash. so if you're iterating, you're only seeing the ones that have been touched. that's the bug note, fr fr. 🙈

---

👑 AUTHOR 👑

Ilya Zakharevich <mailto:perl-module-hash-memoize@ilyaz.org>. 💖

---

and that's the whole thing, bestie!! this page came straight out of perl v5.44.0, dated 2026-10-17, and it lives at Tie::Memoize(3perl) in the Perl Programmers Reference Guide. slay, go memoize something. 💅✨🌈