Hash::Flatten(3pm)

✨ Hash::Flatten — the manual page, but make it a vibe ✨

okay bestie, gather round, because we're talking about Hash::Flatten 💖 a Perl module that does exactly one glorious thing: it smooshes your big ol' nested data hashes flat, and then un-smooshes them back. Flatten/unflatten complex data hashes, periodt. 🫶

---

🌸 SYNOPSIS 🌸

here's the whole thing at a glance, no cap:

# Exported functions
use Hash::Flatten qw(:all);
$flat_hash = flatten($nested_hash);
$nested_hash = unflatten($flat_hash);

# OO interface
my $o = new Hash::Flatten({
        HashDelimiter => '->',
        ArrayDelimiter => '=>',
        OnRefScalar => 'warn',
});
$flat_hash = $o->flatten($nested_hash);
$nested_hash = $o->unflatten($flat_hash);

like, pick your lane: exported functions OR the OO interface. both iconic. 💅

---

🦋 DESCRIPTION 🦋

so what does it even DO? it converts back and forth between a nested hash structure and a flat hash of delimited key-value pairs. literally back and forth. 🔁

and why would you want that? because some protocols are lowkey simple and only support key-value pairs — think CGI and DBMs. they don't do nesting. they could never. so we flatten it for them. ✨

🎀 Functional interface

• $flat_hash = flatten($nested_hash, \%options) — squishes a nested data-structure down into key-value form. the top-level container must be a hashref, no exceptions bestie. like this:

$nested = {
        'x' => 1,
        'y' => {
                'a' => 2,
                'b' => 3
        },
        'z' => [
                'a', 'b', 'c'
        ]
}

$flat = flatten($nested);
use Data::Dumper;
print Dumper($flat);

$VAR1 = {
        'y.a' => 2,
        'x' => 1,
        'y.b' => 3,
        'z:0' => 'a',
        'z:1' => 'b',
        'z:2' => 'c'
};

see how pretty that is?? 😭 the nested stuff just becomes dotted/colon'd keys. and that \%options hashref? that's your override card — use it to change the default behaviour (go peek at "OPTIONS" below, it's giving options).

• $nested_hash = unflatten($flat_hash, \%options) — takes the flattened hash and hands you back the original nested hash. main character energy: it reverses the whole thing. (tho pls check "CAVEATS" first, there are receipts.)

🧚 OO interface

• $o = new Hash::Flatten(\%options) — you can squirrel your options away inside an object instead of passing them around every time (see "OPTIONS"). living that tidy life. 🐿️
• $flat = $o->flatten($nested) — flatten the structure using the options stored in the object.
• $nested = $o->unflatten($flat) — unflatten the structure using the options stored in the object.

---

👑 OPTIONS 👑

• HashDelimiter and ArrayDelimiter — by default, hash dereferences are denoted by a dot, and array dereferences are denoted by a colon. but bestie, you may change these characters to any string you want, because you don't want there to be any confusion as to which part of a string is the 'key' and which is the 'delimiter'. and yes, you may use multicharacter strings if you prefer. go off. 💅
• OnRefScalar and OnRefRef and OnRefGlob — this is the behaviour if a reference of this type is encountered during flattening. possible values are 'die', 'warn' (default behaviour but warns), or a coderef which is passed the reference and should return the flattened value. by default, references to references, and references to scalars, are followed silently. 🤫
• EscapeSequence — this is the character or sequence of characters that will be used to escape the hash and array delimiters. the default escape sequence is '\\'. the escaping strategy is to place the escape sequence in front of delimiter sequences; the escape sequence itself is escaped by replacing it with two instances. (yes it's escaping all the way down, it's iconic like that 🌈)
• DisableEscapes — stop the escaping from happening. no escape sequences will be added to flattened output, nor interpreted on the way back.

WARNING: if your structure has keys that contain the delimiter characters, it will not be possible to unflatten the structure correctly. 💀 so like... be careful. seriously.

---

😭 CAVEATS 😭

any blessings will be discarded during flattening, so that if you flatten an object you must re-bless() it on unflattening. the vibes get flattened, the class does not survive. 🙈

note that there is no delimiter for scalar references, or references to references. if your structure to be flattened contains scalar, or reference, references these will be followed by default, i.e. 'foo' => \\\\\\$foo will be collapsed to 'foo' => $foo. you can override this behaviour using the OnRefScalar and OnRefRef constructor option.

recursive structures are detected and cause a fatal error. 🔥 no infinite loops on this account, we don't do that here.

---

🌈 SEE ALSO 🌈

the perlmonks site has a helpful introduction to when and why you might want to flatten a hash: http://www.perlmonks.org/index.pl?node_id=234186

• CGI::Expand — unflattens hashes using "." as a delimiter, similar to Template::Toolkit's behaviour.
• Tie::MultiDim — this provides a tie interface to unflattening a data structure if you specify a "template" for the structure of the data.
• MLDBM — this also provides a tie interface but reduces a nested structure to key-value form by serialising the values below the top level.

---

⭐ VERSION ⭐

$Id: Flatten.pm,v 1.19 2009/05/09 12:42:02 jamiel Exp $

---

💜 AUTHOR 💜

John Alden & P Kent <cpan _at_ bbc _dot_ co _dot_ uk>

---

🍓 COPYRIGHT 🍓

(c) BBC 2005. This program is free software; you can redistribute it and/or modify it under the GNU GPL.

See the file COPYING in this distribution, or http://www.gnu.org/licenses/gpl.txt

---

okay that's the whole page bestie, you ate it up 🎀 this was perl v5.36.0, dated 2022-12-07, and it's Hash::Flatten(3pm) — go flatten something. byeee 💖✨🦋