Tangra...e::Dump(3pm)

💖 Tangram::Type::Dump 💖

okay bestie, so this is a page from the User Contributed Perl Documentation collection, and it's all about Tangram::Type::Dump — literally the handiest little toolkit for doing Pixie-style dumping of your data. no cap.

---

✨ NAME ✨

Tangram::Type::Dump — Handy functions for Pixie-like dumping of data 🎀

---

🦋 SYNOPSIS 🦋

use Tangram::Type::Dump qw(flatten unflatten UNflatten nuke);

use YAML qw(freeze thaw); # for instance

my $frozen = freeze flatten($storage, $structure);

# optional - remove circular references from flattened
# structure so that it is freed up properly.
nuke $frozen;

# save frozen somewhere...

# restore, but don't load objects straight away
my $reconstituted = unflatten($storage, thaw $frozen);

# restore, loading objects immediately
my $original = UNflatten($storage, $frozen);

# Alternative, quickly marshall a structure for saving
my $structure;
flatten($storage, $structure);
# ... do something with it ...

# restore to former glory; note that Tangram's cache will
# prevent unnecessary DB access.
unflatten($storage, $structure);

---

🌸 DESCRIPTION 🌸

so this module is packing functions that go traversing through your data structures — the ones that are not Tangram-registered objects — and swapping out every Tangram object they find for a Memento. cute, right? 😌

then, when you feed a similar data structure back into the reversal function, those mementos get filled in with on-demand references back to the real objects. the way it just... rehydrates them. iconic tbh. ✨

and listen — all these functions operate in place for maximum efficiency. no copying, no fuss, no extra memory vibes. she's efficient. 💅

---

👑 FUNCTIONS 👑

• flatten($storage, $structure) — this one walks all up and down $structure (traverses it, bestie) and replaces every known Tangram object — meaning ones that are already inserted — with references to them. fr fr.
• unflatten($storage, $structure) — this is the logical opposite of flatten, but lowkey only as far as a 'normal' user is concerned. and 'normal' users, obviously, do not care even a tiny bit that the data structure is being loaded from the database while they use it :). that's the whole magic trick. 🪄

---

💀 BUGS 💀

open question, and I'm just reporting it exactly as written: should this module just be an extension to Tangram::Storage? 👀 nobody knows. it's giving philosophical.

---

🫶 AUTHOR 🫶

Sam Vilain, samv@cpan.org. All rights reserved. This code is free software; you can use and/or modify it under the same terms as Perl itself.

---

and that's the whole page, babe — brought to you by perl v5.36.0, dated 2022-10-16, straight out of the Tangra...e::Dump(3pm) man page vault. go forth and flatten responsibly. 💜✨