Serialiser(3)

💅 Serialiser(3) — like, the whole manual page, bestie

okay so bestie, welcome to Serialiser(3), a page from the User Contributed Perl Documentation era (yes, that era). Sit down, grab a strawberry 🍓, because we're about to get into some small-but-mighty datatypes.

✨ NAME ✨

Types::Serialiser — simple data types for common serialisation formats. that's the whole vibe. small module, big main character energy 💅

📜 SYNOPSIS 📜

ngl, the original page has literally nothing here. empty. void. a little blank space doing absolutely nothing 😭 so we move on. slay, I guess.

🌸 DESCRIPTION 🌸

This module hands you some extra datatypes that get used by common serialisation formats like JSON or CBOR. The whole idea? Have a lil repository of simple/small constants and containers that different implementations can share, so they become interoperable with each other. it's giving community, it's giving collaboration, it's giving 🫶.

💖 SIMPLE SCALAR CONSTANTS 💖

So these are values that are overloaded to act like simple Perl values, but they've got a (class) type so you can tell them apart from normal Perl scalars. Which is necessary, because these have different representations in the serialisation formats. they're not like other scalars. 👑

Quick note: in the following, functions with zero or one arguments have a prototype of () and ($), respectively, so they act as constants and unary operators.

🦋 BOOLEANS (Types::Serialiser::Boolean class)

This type has only two instances: true and false. A natural representation for these in Perl is 1 and 0, but serialisation formats need to be able to tell them apart from mere numbers. rude of numbers, honestly, but okay.

• $Types::Serialiser::true, Types::Serialiser::true — this value represents the "true" value. In most contexts it acts like the number 1. It is up to you whether you use the variable form ($Types::Serialiser::true) or the constant form ("Types::Serialiser::true"). The constant is represented as a reference to a scalar containing 1 — implementations are allowed to directly test for this. she's a reference, she's a scalar, she contains one. iconic ✨
• $Types::Serialiser::false, Types::Serialiser::false — this value represents the "false" value. In most contexts it acts like the number 0. It is up to you whether you use the variable form ($Types::Serialiser::false) or the constant form ("Types::Serialiser::false"). The constant is represented as a reference to a scalar containing 0 — implementations are allowed to directly test for this. 🎀
• Types::Serialiser::as_bool $value — converts a Perl scalar into a boolean, which is useful syntactic sugar. Strictly equivalent to:

$value ? $Types::Serialiser::true : $Types::Serialiser::false

• $is_bool = Types::Serialiser::is_bool $value — returns true iff $value is either $Types::Serialiser::true or $Types::Serialiser::false. For example, you could differentiate between a perl true value and a "Types::Serialiser::true" by using this:

$value && Types::Serialiser::is_bool $value

• $is_true = Types::Serialiser::is_true $value — returns true iff $value is $Types::Serialiser::true. ☑️
• $is_false = Types::Serialiser::is_false $value — returns false iff $value is $Types::Serialiser::false. yes, that's what it says. false. that's the manual page's words, not mine, bestie 🙈

💀 ERROR (Types::Serialiser::Error class)

This class has only a single instance, "error". It's used to signal an encoding or decoding error. In CBOR for example, an object that couldn't be encoded will be represented by a CBOR undefined value, which is represented by the error value in Perl. it's the "oop something went wrong" of the Perl scalar world 😭

• $Types::Serialiser::error, Types::Serialiser::error — this value represents the "error" value. Accessing values of this type will throw an exception. The constant is represented as a reference to a scalar containing "undef" — implementations are allowed to directly test for this. 🚨
• $is_error = Types::Serialiser::is_error $value — returns false iff $value is $Types::Serialiser::error. (again, false. that is literally what it says. keep your eyes peeled, don't @ me 💀)

🧚 NOTES FOR XS USERS 🧚

The recommended way to detect whether a scalar is one of these objects: check whether the stash is the "Types::Serialiser::Boolean" or "Types::Serialiser::Error" stash, and then follow the scalar reference to see if it's 1 (true), 0 (false) or "undef" (error). that's the whole check, bestie, no cap.

While it is possible to use an isa test, directly comparing stash pointers is faster and guaranteed to work. faster and guaranteed? we love a consistent queen. 👑

For historical reasons, the "Types::Serialiser::Boolean" stash is just an alias for "JSON::PP::Boolean". When printed, the classname will usually be "JSON::PP::Boolean", but isa tests and stash pointer comparison will normally work correctly (i.e. Types::Serialiser::true ISA JSON::PP::Boolean, but also ISA Types::Serialiser::Boolean). it's giving aliases, it's giving both/and, it's giving bi-con classname representation 🌈

🎀 A GENERIC OBJECT SERIALIATION PROTOCOL 🎀

This section explains the object serialisation protocol used by CBOR::XS. It is meant to be generic enough to support any kind of generic object serialiser.

This protocol is called "the Types::Serialiser object serialisation protocol". yes it has a name. yes it's a whole moment. periodt.

🔥 ENCODING

When the encoder encounters an object that it cannot otherwise encode (for example, CBOR::XS can encode a few special types itself, and will first attempt to use the special "TO_CBOR" serialisation protocol), it will look up the "FREEZE" method on the object. 🧊

⚠️ real talk: note that the "FREEZE" method will normally be called during encoding, and MUST NOT change the data structure that is being encoded in any way, or it might cause memory corruption or worse. "or worse" is the scary part. do not touch. hands off. 🙅‍♀️

If it exists, it will call it with two arguments: the object to serialise, and a constant string that indicates the name of the data model. For example CBOR::XS uses "CBOR", and the JSON and JSON::XS modules (or any other JSON serialiser), would use "JSON" as second argument.

The "FREEZE" method can then return zero or more values to identify the object instance. The serialiser is then supposed to encode the class name and all of these return values (which must be encodable in the format) using the relevant form for Perl objects. In CBOR for example, there is a registered tag number for encoded perl objects. cute little tag number, doing her job 💅

The values that "FREEZE" returns must be serialisable with the serialiser that calls it. Therefore, it is recommended to use simple types such as strings and numbers, and maybe array references and hashes (basically, the JSON data model). You can always use a more complex format for a specific data model by checking the second argument, the data model.

The "data model" is not the same as the "data format" — the data model indicates what types and kinds of return values can be returned from "FREEZE". For example, in "CBOR" it is permissible to return tagged CBOR values, while JSON does not support these at all, so "JSON" would be a valid (but too limited) data model name for CBOR::XS. similarly, a serialising format that supports more or less the same data model as JSON could use "JSON" as data model without losing anything.

🧊 DECODING

When the decoder then encounters such an encoded perl object, it should look up the "THAW" method on the stored classname, and invoke it with the classname, the constant string to identify the data model/data format, and all the return values returned by "FREEZE". freeze, thaw, we stay silly ✨

🌈 EXAMPLES 🌈

See the "OBJECT SERIALISATION" section in the CBOR::XS manpage for more details, an example implementation, and code examples.

Here is an example "FREEZE"/"THAW" method pair, verbatim, character for character, because I would never do you dirty like that:

sub My::Object::FREEZE {
   my ($self, $model) = @_;

   ($self->{type}, $self->{id}, $self->{variant})
}

sub My::Object::THAW {
   my ($class, $model, $type, $id, $variant) = @_;

   $class->new (type => $type, id => $id, variant => $variant)
}

look at them. a matched set. soulmates, honestly 🫶

😭 BUGS 😭

The use of overload makes this module much heavier than it should be (on my system, this module: 4kB RSS, overload: 260kB RSS). yes, you read that right. 260kB. the overload is eating. not in the good way. 🍽️💀

👑 SEE ALSO 👑

Currently, JSON::XS and CBOR::XS use these types.

💜 AUTHOR 💜

Marc Lehmann <schmorp@schmorp.de> http://home.schmorp.de/

---

and that's the page, bestie 🎀 this was Serialiser(3), fresh from perl v5.42.0 and dated 2020-12-01, still shipped in the User Contributed Perl Documentation. go forth and serialise responsibly. mwah 💋✨