Hash::...faults(3pm)

🦋 Hash::WithDefaults — the manual page (yes, the file is Hash::...faults(3pm), she's just going by her government name, don't worry about it)

okay so. this page lives in the User Contributed Perl Documentation section of the manual, bestie, and it's all about a little module called Hash::WithDefaults 💖

---

✨ NAME ✨

Hash::WithDefaults — class for hashes with key-casing requirements supporting defaults 🌸

version 0.05

---

🌈 SYNOPSIS 🌈

use Hash::WithDefaults;

%main = ( ... );
tie %h1, 'Hash::WithDefaults', {...};
tied(%h1)->AddDefault(\%main);
tie %h2, 'Hash::WithDefaults', [...];
tied(%h2)->AddDefault(\%main);

# now if you use $h1{$key}, the value is looked up first
# in %h1, then in %main.

---

💅 DESCRIPTION 💅

So this module implements hashes that support "defaults" ✨ — like, you can name several more hashes where the data will get looked up in case it's not found in the current hash. it's giving backup plans, it's giving a safety net, it's giving main character hash with a support system. 👑

---

🎀 Object creation 🎀

tie %hash, 'Hash::WithDefault', [$case_option], [\%values];
tie %hash, 'Hash::WithDefault', [$case_option], [\@values];
tie %hash, 'Hash::WithDefault', [$case_option], [%values];

the optional $case_option can be any one of these values:

• Sensitive — the hash will be case sensitive
• Tolower — the hash will be case sensitive, all keys are made lowercase
• Toupper — the hash will be case sensitive, all keys are made uppercase
• Preserve — the hash will be case insensitive, the case is preserved
• Lower — the hash will be case insensitive, all keys are made lowercase
• Upper — the hash will be case insensitive, all keys are made uppercase

(those descriptions are straight from the docs, i'm just the messenger, don't come for me 🙈)

If you pass a hash or array reference or an even list of keys and values to the tie() function, those keys and values will be COPIED to the resulting magical hash! 🪄 like, copied copied. not referenced. not vibes-based. copied.

After you tie() the hash, you use it just like any other hash. that's it. that's the whole thing. 💖

---

🔥 Functions 🔥

AddDefault

tied(%hash)->AddDefault(\%defaults);

This instructs the object to include the %defaults in the search for values. After this, the value will be looked up first in %hash itself and then in %defaults. 🕵️♀️

You may keep modifying the %defaults and your changes WILL be visible through %hash! yes bestie, it's live, it's not a screenshot. 👀

You may add as many defaults to one Hash::WithDefaults object as you like, they will be searched in the order you add them. 📚 order matters, always has.

If you delete a key from the tied hash, it's only deleted from the list of specific keys, the defaults are never modified through the tied hash. This means that you may get a default value for a key after you deletethe key from the tied hash! 😭

(yes the original says "deletethe" as one word. i am preserving the artifact. it's iconic now. we don't fix it, we celebrate it. 🎀)

GetDefaults

$defaults = tied(%hash)->GetDefaults();
push @$defaults, \%another_default;

Returns a reference to the array that stores the defaults. You may delete or insert hash references into the array, but make sure you NEVER EVER insert anything else than a hash reference into the array! 🚨

fr fr. anything that isn't a hash reference in there is a one-way ticket to chaos city, and not the cute kind. 💀

---

🧚 Config::IniHash example 🧚

use Config::IniHash;
$config = ReadIni $inifile, withdefaults => 1, case => 'preserve';

if (exists $config->{':default'}) {
  my $default = $config->{':default'};
  foreach my $section (keys %$config) {
    next if $section =~ /^:/;
        tied(%{$config->{$section}})->AddDefault($default)
  }
}

And now all normal sections will get the default values from [:default] section ;-)

slay. section-level defaults. we love a DRY config. 🌈

---

👑 AUTHOR 👑

Jan Krynicky <Jenda@Krynicky.cz> http://Jenda.Krynicky.cz

---

📜 COPYRIGHT 📜

Copyright (c) 2002-2009 Jan Krynicky <Jenda@Krynicky.cz>. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

aaaaand that's the whole page babes 💜 this one shipped as perl v5.36.0 on 2022-10-13 — stan a maintained-ish classic, mwah 🫶✨