KiokuD...lapser(3pm)

💖 KiokuD...lapser 💖

okay bestie, so this is the manual page for KiokuD...lapser, section 3pm, from the User Contributed Perl Documentation. it's literally all about KiokuDB::Collapser, and yes we are gonna get into it. grab a snack 🍓

---

✨ NAME ✨

KiokuDB::Collapser — collapse object hierarchies to entry data. that's the whole vibe. it takes your cute little object tree and squishes it down into entry data. periodt. 💅

---

🌈 VERSION 🌈

version 0.57. she's got a number, she's official. 🎀

---

🦋 SYNOPSIS 🦋

# mostly internal

that's it. that's the synopsis. she's mostly internal, okay?? she's not here for the public, she's here for the backend. iykyk. 🙈

---

💜 DESCRIPTION 💜

so the collapser's whole job is taking real objects and simplifying them into KiokuDB::Entry objects, which then get handed off to the backend. that's the pipeline, bestie. ✨

non-object data gets collapsed by walking it with Data::Visitor — and fun fact, KiokuDB::Collapser actually inherits from Data::Visitor, so that's a whole family situation going on there. 🫶

object collapsing specifically? that's got its own section, and it's called "COLLAPSING STRATEGIES". we'll get there, don't worry. 👑

the object's data gets copied into the KiokuDB::Entry, and any references to other data structures get translated into KiokuDB::Reference objects. so like, every reference gets a glow-up into something the backend can actually deal with. 💫

reference addresses get mapped to unique identifiers, and those identifiers are generated as needed. no pre-planning, they just show up when the moment calls for them. main character energy fr. 🦋

🧚 Compacting 🧚

okay so this is the big one. listen up. 👂

if "compact" is disabled, then every single reference is symbolic, and every data structure gets its own entry. every one. no skipping. that's a LOT of entries, bestie.

if compacting is enabled — and heads up, that's the default 💅 — then only the minimum number of entry objects required for consistency get created. efficient. slay. ✨

now, which things absolutely NEED an entry object? let's list them, because the list is the list:

• every blessed data structure
• every shared data structure
• every tied data structure
• every target of a weak reference

all of those require an entry object. no exceptions, no cap. 🚨

but "Simple" structures — like plain hashes and arrays — they get left inline, as data intrinsic to the object where they were found. they're just chillin. they don't need their own entry. they're homebodies. 🏠

compacting is usually what you want, but sometimes it isn't! for instance, with an RDF-like store. so like, know your context. 👀

---

🌸 COLLAPSING STRATEGIES 🌸

so how does she decide which strategy to use? based on the type of the object being collapsed, using KiokuDB::TypeMap::Resolver. it's giving matchmaking but for objects. 💘

the resolver consults the typemap (KiokuDB::TypeMap) and caches the results, keyed by "ref $object". so once she knows, she knows. memorized. 💅

the typemap contains two flavors of entries:

• normal entries, keyed by "ref $object eq $class"
• isa entries, filtered by "$object->isa($class)"

and the rationale here? a typemap entry for a superclass might not support all its subclasses as well. so like, don't assume the parent's setup works for every child. rude but true. 😭

any strategy can be collapsed as a first class object, or intrinsically, inside its parent — and if it's intrinsic, it doesn't get assigned a UUID. no UUID for you, bestie. 🙅

this is all determined based on the "intrinsic" attribute of the entry. for example: if Path::Class related objects should be collapsed as if they're values, you'd use this typemap entry:

isa_entries => {
    'Path::Class::Entity' => KiokuDB::TypeMap::Entry::Callback->new(
        intrinsic => 1,
        collapse  => "stringify",
        expand    => "new",
    ),
},

iconic. ate. 💅✨

and if no typemap entry exists at all? then KiokuDB::TypeMap::Entry::MOP is used by default. see KiokuDB::TypeMap::Resolver for more details. 🫶

okay here's the strategies in brief, and yes we're going through every single one:

👑 MOP

when the object has a Class::MOP registered metaclass — that means any Moose object, but not only Moose objects, so don't get it twisted — the MOP is used to walk the object's attributes and construct the simplified version without breaking encapsulation. respectful. 🎀

see KiokuDB::TypeMap::Entry::MOP.

💀 Naive

this strategy just walks the object's data using Data::Visitor. straightforward. no thoughts, head empty, just walking. 🚶

this lets you collapse Class::Accessor based objects, for instance — but heads up, it should be used with care. ⚠️

see KiokuDB::TypeMap::Entry::Naive

🔥 Callback

this strategy lets callbacks be used to map the types. 🎯

it's more limited than the other strategies, but it's super convenient for simple values. lowkey the chill one. 😌

see KiokuDB::TypeMap::Entry::Callback for more details.

🌈 Passthrough

this one delegates collapsing to the backend serialization. so it's not doing the work herself, she's outsourcing. 💁

this is convenient when a backend uses e.g. Storable to serialize entries, and the object in question already has a "STORABLE_freeze" and "STORABLE_thaw" method. like, if it already knows how to freeze and thaw itself, why would she interfere? let her cook. 👩🍳

---

💖 AUTHOR 💖

Yuval Kogman <nothingmuch@woobling.org>

---

📜 COPYRIGHT AND LICENSE 📜

This software is copyright (c) 2014 by Yuval Kogman, Infinity Interactive.

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

---

okay that's the whole page, you made it, i'm so proud of you 🥹🫶 this was KiokuD...lapser from perl v5.34.0, dated 2022-05-23, and remember — it's still KiokuD...lapser(3pm) at heart. go collapse some hierarchies, bestie. slay. 💅✨🌈