.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "KiokuDB::Collapser 3pm"
.TH KiokuDB::Collapser 3pm "2022-05-23" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
KiokuDB::Collapser \- Collapse object hierarchies to entry data
.SH "VERSION"
.IX Header "VERSION"
version 0.57
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    # mostly internal
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The collapser simplifies real objects into KiokuDB::Entry objects to pass to
the backend.
.PP
Non object data is collapsed by walking it with Data::Visitor (which
KiokuDB::Collapser inherits from).
.PP
Object collapsing is detailed in \*(L"\s-1COLLAPSING STRATEGIES\*(R"\s0.
.PP
The object's data will be copied into the KiokuDB::Entry with references to
other data structures translated into KiokuDB::Reference objects.
.PP
Reference addresses are mapped to unique identifiers, which are generated as
necessary.
.SS "Compacting"
.IX Subsection "Compacting"
If \f(CW\*(C`compact\*(C'\fR is disabled then every reference is symbolic, and every data
structure has an entry.
.PP
If compacting is enabled (the default) the minimum number of entry objects
required for consistency is created.
.PP
Every blessed, shared or tied data structure requires an entry object, as does
every target of a weak reference. \*(L"Simple\*(R" structures, such as plain
hashes/arrays will be left inline as data intrinsic to the object it was found in.
.PP
Compacting is usually desirable, but sometimes isn't (for instance with an \s-1RDF\s0
like store).
.SH "COLLAPSING STRATEGIES"
.IX Header "COLLAPSING STRATEGIES"
Collapsing strategies are chosen based on the type of the object being
collapsed, using KiokuDB::TypeMap::Resolver.
.PP
The resolver consults the typemap (KiokuDB::TypeMap), and caches the results
as keyed by \f(CW\*(C`ref $object\*(C'\fR.
.PP
The typemap contains normal entries (keyed by \f(CW\*(C`ref $object eq $class\*(C'\fR) or isa
entries (filtered by \f(CW\*(C`$object\->isa($class)\*(C'\fR). The rationale is that a typemap
entry for a superclass might not support all subclasses as well.
.PP
Any strategy may be collapsed as a first class object, or intrinsically, inside
its parent (in which case it isn't assigned a \s-1UUID\s0). This is determined based
on the \f(CW\*(C`intrinsic\*(C'\fR attribute to the entry. For instance, if Path::Class
related objects should be collapsed as if they are values, the following
typemap entry can be used:
.PP
.Vb 7
\&    isa_entries => {
\&        \*(AqPath::Class::Entity\*(Aq => KiokuDB::TypeMap::Entry::Callback\->new(
\&            intrinsic => 1,
\&            collapse  => "stringify",
\&            expand    => "new",
\&        ),
\&    },
.Ve
.PP
If no typemap entry exists, KiokuDB::TypeMap::Entry::MOP is used by default.
See KiokuDB::TypeMap::Resolver for more details.
.PP
These are the strategies in brief:
.SS "\s-1MOP\s0"
.IX Subsection "MOP"
When the object has a Class::MOP registered metaclass (any Moose object,
but not only), the \s-1MOP\s0 is used to walk the object's attributes and construct
the simplified version without breaking encapsulation.
.PP
See KiokuDB::TypeMap::Entry::MOP.
.SS "Naive"
.IX Subsection "Naive"
This collapsing strategy simply walks the object's data using Data::Visitor.
.PP
This allows collapsing of Class::Accessor based objects, for instance, but
should be used with care.
.PP
See KiokuDB::TypeMap::Entry::Naive
.SS "Callback"
.IX Subsection "Callback"
This collapsing strategy allows callbacks to be used to map the types.
.PP
It is more limited than the other strategies, but very convenient for simple
values.
.PP
See KiokuDB::TypeMap::Entry::Callback for more details.
.SS "Passthrough"
.IX Subsection "Passthrough"
This delegates collapsing to the backend serialization. This is convenient for
when a backend uses e.g. Storable to serialize entries, and the object in
question already has a \f(CW\*(C`STORABLE_freeze\*(C'\fR and \f(CW\*(C`STORABLE_thaw\*(C'\fR method.
.SH "AUTHOR"
.IX Header "AUTHOR"
Yuval Kogman <nothingmuch@woobling.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2014 by Yuval Kogman, Infinity Interactive.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.