NAME

       KiokuDB::TypeMap::Entry::MOP - A KiokuDB::TypeMap entry for objects with a metaclass.

VERSION

       version 0.57

SYNOPSIS

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

DESCRIPTION

       This typemap entry handles collapsing and expanding of Moose based objects.

       It supports anonymous classes with runtime roles, the KiokuDB::Role::ID role.

       Code for immutable classes is cached and performs several orders of magnitude better, so make use of
       "make_immutable" in Moose::Meta::Class.

ATTRIBUTES

       intrinsic
           If true the object will be collapsed as part of its parent, without an ID.

       check_class_versions
           If  true (the default) then class versions will be checked on load and if there is a mismatch between
           the stored version number and the current version number, the version upgrade handler tables will  be
           used to convert the out of date entry.

       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.

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

           The tables are keyed by version number (as a string, "undef" and "" are considered the same), and the
           value  can  be  either  a  code  reference  that  processes  the entry to bring it up to date, a hash
           reference of overridden fields, or 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.

           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 => ...,
                       ),
                   },
               }

           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, 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.

           The callback is invoked with the following arguments:

           entry
               The entry to upgrade.

           from_version
               The key under which the handler was found (not necessarily the same as "$entry->class_version").

           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).

           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).

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.

perl v5.34.0                                       2022-05-23                  KiokuDB::TypeMap::Entry::MOP(3pm)