Tangra...plicity(3pm)

💖 Tangram::Complicity — a.k.a. Tangra...plicity(3pm) 🎀

okay bestie come closer because this one is a certified Perl Documentation Classic™ from the User Contributed Perl Documentation section, and the name is genuinely Tangram::Complicity (the header does a little "Tangra...plicity(3pm)" thing, it's giving ✨truncated✨, we move).

---

🌸 NAME 🌸

Tangram::Complicity — how to make Tangram-friendly classes 🫶

---

✨ SYNOPSIS ✨

package YourNastyXSClass;

sub px_freeze {
    return [ (shift)->gimme_as_perl ];
}

sub px_thaw {
    my $class = shift;
    my $self = $class->new( @_ );
}

1;

---

💅 DESCRIPTION 💅

okay so first thing, and I need you to sit down for this: Tangram::Complicity does not exist. 😭 not "it's undocumented", not "it's in a secret branch" — it is literally not a thing. and to make matters worse, it isn't even implemented. this page is, and I quote, "a big FIXME for the code it refers to". iconic behaviour, honestly. 💀

so what IS this page? it's the documentation of the API that classes must implement to be safely stored by Tangram::Type::Dump::flatten. that's the whole job. that's the gig. 🎀

now, important vibe check: to avoid unnecessary copying of memory structures from A to B, this method operates "in-place". 🫧

and because of that in-place situation, the reference type used in the return value has to be the same as the one in the real object. it's giving "no substitutions". this is explained later, under "reftype mismatch" — so hold that thought, bestie, we'll get there. 💖

so, for instance — for Set::Object objects, which have a px_freeze method of:

sub px_freeze {
    my $self = shift;
    return $self->members;
}

sub px_thaw {
    my $class = shift;
    return $class->new(@_);
}

[ note: this differs from the Storable API (STORABLE_freeze and STORABLE_thaw). This interface is actually reasonably sane — the Storable API required custom XS magic for Set::Object, for instance. Which has been implemented, but we've learned the lesson now :) ]

you have to respect the growth arc fr fr. 🌈

in essence, the px_freeze method means "marshall yourself to pure Perl data types". 🦋

and heads up — different serialisation tools will treat ties, overload and magic remaining on the structure in their own way. so if you really want to hang out-of-band information off them, create your own type of magic, à la Pixie::Info. you're the main character, go off. 👑

---

🧚 reftype mismatch 🧚

if you get a reftype mismatch error, bestie, here's why: your YourClass->px_thaw function returned a different type of reference than the one that was passed to store to YourClass->px_freeze. it's not personal, it's just type enforcement. 💅

good news though — this restriction only applies to the return value of the constructor px_thaw, so this is usually fine. the return value from px_freeze will be wrapped in a (blessed) container of the correct reference type, regardless of its return type. slay. ✨

ie. your function is called as:

%{ $object } = %{ YourClass->px_thaw(@icicle) };

@{ $object } = @{ YourClass->px_thaw(@icicle) };

${ $object } = ${ YourClass->px_thaw(@icicle) };

*{ $object } = *{ YourClass->px_thaw(@icicle) };

my $tmp = YourClass->px_thaw(@icicle);
$object = sub { goto $tmp };

now, this is an analogy — no temporary object is actually used in the scalar case, for instance, due to the use of tie. so don't come for me about it. 🙈

the reason for all this? to allow for circular and back-references in the data structure. those references that point back point to the real blessed object, so to avoid the overhead of a two-pass algorithm, this restriction is made. that's why the value is passed into STORABLE_thaw as $_[0]. for most people, it won't make a difference. 😌

however — and this is the part where we lowkey gasp — it does have a nasty side effect: serialisers that can't handle all types of pure Perl data structures (such as, all current versions of YAML) are unable to store blessed scalars (eg, Set::Object's). 😭 so if that's your situation, that's your situation. you've been warned, and the warning is very real. 🍓

---

and that's the whole page, bestie — written by way of perl v5.36.0, dated 2022-10-16 🫶 hope your px_freeze and px_thaw are iconic and your reftypes always match. mwah 💖🎀