KiokuD...y::MOP(3pm)

💖 KiokuDB::TypeMap::Entry::MOP(3pm) 💖

okay bestie, quick vibe check before we dive in: this is the manual page for KiokuDB::TypeMap::Entry::MOP, and it's living in section 3pm of your perl docs (the header up top just squishes the long name down to KiokuD...y::MOP(3pm) because perl man pages are dramatic like that 🎀).

---

✨ NAME ✨

KiokuDB::TypeMap::Entry::MOP — a KiokuDB::TypeMap entry for objects that have a metaclass. that's it, that's the whole job. 💅

---

🌸 VERSION 🌸

version 0.57 — yes she's been around, she's iconic, she's stable. 👑

---

🦋 SYNOPSIS 🦋

KiokuDB::TypeMap->new(
    entries => {
        'My::Class' => KiokuDB::TypeMap::Entry::MOP->new(
            intrinsic => 1,
        ),
    },
);

like… look at her. one typemap, one entry, one flag. slay. ✨

---

💜 DESCRIPTION 💜

so basically this typemap entry handles the collapsing and expanding of Moose based objects. that's the whole main character energy of this module.

she also supports anonymous classes with runtime roles 🌈, and the KiokuDB::Role::ID role. iykyk.

now here's the part where you listen up fr fr: code for immutable classes is cached and performs several orders of magnitude better, so bestie please make use of make_immutable in Moose::Meta::Class. not me begging you to cache your classes. 😭 it's giving free performance. take it.

---

🎀 ATTRIBUTES 🎀

• intrinsic — if this is true, the object gets collapsed as part of its parent, without an ID. she's attached, she's not going anywhere alone. 🫶
• check_class_versions — if true (which is the default, no cap) then class versions get checked on load. and if there's a mismatch between the stored version number and the current version number, the version upgrade handler tables get used to convert the out of date entry. glow up sequence activated. ✨
• version_table, class_version_table — tables of handlers. 👑

see also KiokuDB::Role::Upgrade::Data and KiokuDB::Role::Upgrade::Handlers::Table for convenience roles that do not require a central table. (for the girlies who don't wanna share.) 💅

the first one (version_table) is a global version table — super useful when the typemap entry is only handling one class. the second one (class_version_table) is a table of tables keyed by the class name.

the tables are keyed by version number (as a string, and heads up: undef and "" are considered the same, they're basically twinning), and the value can be any of these three things:

• a code reference that processes the entry to bring it up to date
• a hash reference of overridden fields
• a string denoting a version number that this version is equivalent to

version numbers have no actual ordinal meaning, they are taken as simple string identifiers. so don't come in here thinking 2.0 is bigger than 1.0, that's not the vibe. 🚫

so if we had 3 versions — 1.0, 1.1 and 2.0 — where 1.1 is a minor update to the class that requires no structural changes from 1.0, our table could be written like this:

{
    '1.0' => '1.1', # upgrading the data from 1.0 to 1.1 is a noop
    '1.1' => sub {
        my ( $self, %args ) = @_;

        # manually convert the entry data
        return $entry->clone(
            class_version => '2.0',
            prev => $entry,
            data => ...,
        ),
    },
}

okay so when an object that was stored as version 1.0 is retrieved from the database, and the current definition of the class has $VERSION 2.0, the table declares 1.0 is the same as 1.1, so we search for the handler for 1.1 and apply it. 🔍✨

the resulting class has the version 2.0 which is the same as what we have now, so this object can be thawed. it's giving resurrection. 🦋

the callback gets invoked with these arguments, bestie, memorize them:

• entry — the entry to upgrade.
• from_version — the key under which the handler was found (not necessarily the same as $entry->class_version, don't get it twisted).
• meta — the Class::MOP::Class of the entry's class.
• linker — the KiokuDB::Linker instance that is inflating this object.

can be used to retrieve additional required objects (cycles are not a problem, but be aware that the objects might not be usable yet at the time of the callback's invocation 👀 — so like, she's there but she's not ready, respect that).

when a hash is provided as a handler it'll be used to create an entry like this:

$entry->derive(
    %$handler,
    data => {
        %{ $entry->data },
        %{ $handler->{data} || {} },
    },
);

the field class_version is required, and data must contain a hash:

KiokuDB->connect(
    class_version_table => {
        Foo => {
            "0.02" => {
                class_version => "0.03", # upgrade 0.02 to 0.03
                data => {
                    a_new_field => "default_value",
                },
            },
        },
    },
);

• write_upgrades — if true, after applying version upgrade handlers, the updated entry will be written back to the database. 💾

defaults to false but might default to true in future versions (unless the database is in readonly mode). so like, watch this space, the future is coming for your defaults. ⚠️

---

🌈 AUTHOR 🌈

Yuval Kogman <nothingmuch@woobling.org> — the icon, the legend, the moment. 👑

---

⭐ 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. so basically: free, open, generous, iconic. 🫶

---

and that's the whole page, bestie!! 🎀 this was perl v5.34.0, dated 2022-05-23 — yes i know, a lil vintage, but she's still serving. now go make your classes immutable. periodt. 💅✨