KiokuD...mposite(3pm)

💖 KiokuDB::TypeMap::Composite(3pm) — the group-chat edition 💖

okay bestie so this is KiokuDB::TypeMap::Composite, a role (from the User Contributed Perl Documentation section of the manual, 3pm, you know the vibe) that lets you build big fancy KiokuDB::TypeMap objects out of a bunch of lil smaller typemaps. it's giving ✨modular✨ and we're obsessed.

---

✨ VERSION ✨

version 0.57 — the version, the moment, the icon 👑

---

🦋 SYNOPSIS 🦋

no cap, this is how you do it:

package MyTypeMap;
use Moose;

extends qw(KiokuDB::TypeMap);

with qw(KiokuDB::TypeMap::Composite);

# declare typemaps to inherit from using the KiokuDB::TypeMap trait
# the 'includes' attribute will be built by collecting these attrs:

has foo_typemap => (
    traits => [qw(KiokuDB::TypeMap)], # register for inclusion
    does   => "KiokUDB::Role::TypeMap",
    is     => "ro",
    lazy_build => 1,
);

# this role also provides convenience methods for creating typemap objects
# easily:
sub _build_foo_typemap {
    my $self = shift;

    $self->_create_typemap(
        isa_entries => {
            $class => {
                type      => 'KiokuDB::TypeMap::Entry::Callback',
                intrinsic => 1,
                collapse  => "collapse",
                expand    => "new",
            },
        },
    );
}

sub _build_bar_typemap {
    my $self = shift;

    # create a typemap with one naive isa entry
    $self->_naive_isa_typemap("Class::Foo", @entry_args);
}

# you also get some construction time customization:

MyTypeMap->new(
    exclude => [qw(Class::Blort foo)],
    override => {
        "Class::Blah", => $alternate_entry,
    },
);

like, look at that. the traits => [qw(KiokuDB::TypeMap)] line is literally the "register me for inclusion bestie" button. 🫶

---

🌸 DESCRIPTION 🌸

this role is the declarative way to set values for KiokuDB::TypeMap's includes attribute — and you can customize it however you want. main character energy fr fr.

any class that consumes this role can declare attributes with the trait KiokuDB::TypeMap. that's it. that's the whole trick.

the result is a typemap instance that inherits from the specified typemap, in a way that's composable for the author and flexible for the user. everyone eats, nobody cries. 💅

fun fact to tell at parties: KiokuDB::TypeMap::Default is built using this very role. iconic behaviour, honestly.

---

🎀 ATTRIBUTES 🎀

exclude

an array reference containing typemap attribute names (like path_class in the default typemap, iykyk) — or a class name to exclude. basically a little no-thanks list.

class exclusions are handled by _create_typemap and do not apply to already constructed typemaps. so like, if it's already built, too late bestie. 😭

override

a hash reference of classes to KiokuDB::TypeMap::Entry objects. your little "actually, use this one instead" map.

class overrides are also handled by _create_typemap and do not apply to already constructed typemaps. same energy, same rule.

classes which don't have a definition will not be merged into the resulting typemap — so if that's what you want, just go make your own typemap and inherit from it. periodt. ⭐

---

🧚 METHODS 🧚

_create_typemap %args

creates a new typemap. fresh out the oven, no cap. 🔥

the entry arguments get converted before being passed to new in KiokuDB::TypeMap:

$self->_create_typemap(
    entries => {
        Foo => {
            type => "KiokuDB::TypeMap::Entry::Naive",
            intrinsic => 1,
        },
    },
);

so in this example, that nested hashref is gonna be used as the arguments to new in KiokuDB::TypeMap::Entry::Naive. cute, right? 🌈

and yes — exclude and override are taken into account by the hashref conversion code. they're in the room with us. 👀

_naive_isa_typemap $class, %entry_args

the convenience method of your dreams: makes a one entry typemap with a single inherited entry for $class, of the type KiokuDB::TypeMap::Entry::Naive. one entry, zero drama. ✨

this is so useful when you've got a base class you want KiokuDB to persist automatically:

sub _build_my_class_typemap {
    shift->_naive_isa_typemap( "My::Class::Base" );
}

look at how short that is. the efficiency. the elegance. we love to see it. 🦋

---

👑 AUTHOR 👑

Yuval Kogman <nothingmuch@woobling.org> — shoutout to the author, absolute legend, thank you for your service 🫶

---

💜 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. free as in slay, bestie. 🎀

---

and that's the whole page fr fr — this doc came to you from the User Contributed Perl Documentation crew, perl v5.34.0, dated 2022-05-23, and honestly? it ate. bye babes 💖✨🌸