22

✏️ Editing: Types::Serialiser.3pm

.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" 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 "Serialiser 3"
.TH Serialiser 3 "2020-12-01" "perl v5.26.3" "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"
Types::Serialiser \- simple data types for common serialisation formats
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides some extra datatypes that are used by common
serialisation formats such as \s-1JSON\s0 or \s-1CBOR.\s0 The idea is to have a
repository of simple/small constants and containers that can be shared by
different implementations so they become interoperable between each other.
.SH "SIMPLE SCALAR CONSTANTS"
.IX Header "SIMPLE SCALAR CONSTANTS"
Simple scalar constants are values that are overloaded to act like simple
Perl values, but have (class) type to differentiate them from normal Perl
scalars. This is necessary because these have different representations in
the serialisation formats.
.PP
In the following, functions with zero or one arguments have a prototype of
\&\f(CW\*(C`()\*(C'\fR and \f(CW\*(C`($)\*(C'\fR, respectively, so act as constants and unary operators.
.SS "\s-1BOOLEANS\s0 (Types::Serialiser::Boolean class)"
.IX Subsection "BOOLEANS (Types::Serialiser::Boolean class)"
This type has only two instances, true and false. A natural representation
for these in Perl is \f(CW1\fR and \f(CW0\fR, but serialisation formats need to be
able to differentiate between them and mere numbers.
.ie n .IP "$Types::Serialiser::true, Types::Serialiser::true" 4
.el .IP "\f(CW$Types::Serialiser::true\fR, Types::Serialiser::true" 4
.IX Item "$Types::Serialiser::true, Types::Serialiser::true"
This value represents the \*(L"true\*(R" value. In most contexts is acts like
the number \f(CW1\fR. It is up to you whether you use the variable form
(\f(CW$Types::Serialiser::true\fR) or the constant form (\f(CW\*(C`Types::Serialiser::true\*(C'\fR).
.Sp
The constant is represented as a reference to a scalar containing \f(CW1\fR \-
implementations are allowed to directly test for this.
.ie n .IP "$Types::Serialiser::false, Types::Serialiser::false" 4
.el .IP "\f(CW$Types::Serialiser::false\fR, Types::Serialiser::false" 4
.IX Item "$Types::Serialiser::false, Types::Serialiser::false"
This value represents the \*(L"false\*(R" value. In most contexts is acts like
the number \f(CW0\fR. It is up to you whether you use the variable form
(\f(CW$Types::Serialiser::false\fR) or the constant form (\f(CW\*(C`Types::Serialiser::false\*(C'\fR).
.Sp
The constant is represented as a reference to a scalar containing \f(CW0\fR \-
implementations are allowed to directly test for this.
.ie n .IP "Types::Serialiser::as_bool $value" 4
.el .IP "Types::Serialiser::as_bool \f(CW$value\fR" 4
.IX Item "Types::Serialiser::as_bool $value"
Converts a Perl scalar into a boolean, which is useful syntactic
sugar. Strictly equivalent to:
.Sp
.Vb 1
\&   $value ? $Types::Serialiser::true : $Types::Serialiser::false
.Ve
.ie n .IP "$is_bool = Types::Serialiser::is_bool $value" 4
.el .IP "\f(CW$is_bool\fR = Types::Serialiser::is_bool \f(CW$value\fR" 4
.IX Item "$is_bool = Types::Serialiser::is_bool $value"
Returns true iff the \f(CW$value\fR is either \f(CW$Types::Serialiser::true\fR or
\&\f(CW$Types::Serialiser::false\fR.
.Sp
For example, you could differentiate between a perl true value and a
\&\f(CW\*(C`Types::Serialiser::true\*(C'\fR by using this:
.Sp
.Vb 1
\&   $value && Types::Serialiser::is_bool $value
.Ve
.ie n .IP "$is_true = Types::Serialiser::is_true $value" 4
.el .IP "\f(CW$is_true\fR = Types::Serialiser::is_true \f(CW$value\fR" 4
.IX Item "$is_true = Types::Serialiser::is_true $value"
Returns true iff \f(CW$value\fR is \f(CW$Types::Serialiser::true\fR.
.ie n .IP "$is_false = Types::Serialiser::is_false $value" 4
.el .IP "\f(CW$is_false\fR = Types::Serialiser::is_false \f(CW$value\fR" 4
.IX Item "$is_false = Types::Serialiser::is_false $value"
Returns false iff \f(CW$value\fR is \f(CW$Types::Serialiser::false\fR.
.SS "\s-1ERROR\s0 (Types::Serialiser::Error class)"
.IX Subsection "ERROR (Types::Serialiser::Error class)"
This class has only a single instance, \f(CW\*(C`error\*(C'\fR. It is used to signal
an encoding or decoding error. In \s-1CBOR\s0 for example, and object that
couldn't be encoded will be represented by a \s-1CBOR\s0 undefined value, which
is represented by the error value in Perl.
.ie n .IP "$Types::Serialiser::error, Types::Serialiser::error" 4
.el .IP "\f(CW$Types::Serialiser::error\fR, Types::Serialiser::error" 4
.IX Item "$Types::Serialiser::error, Types::Serialiser::error"
This value represents the \*(L"error\*(R" value. Accessing values of this type
will throw an exception.
.Sp
The constant is represented as a reference to a scalar containing \f(CW\*(C`undef\*(C'\fR
\&\- implementations are allowed to directly test for this.
.ie n .IP "$is_error = Types::Serialiser::is_error $value" 4
.el .IP "\f(CW$is_error\fR = Types::Serialiser::is_error \f(CW$value\fR" 4
.IX Item "$is_error = Types::Serialiser::is_error $value"
Returns false iff \f(CW$value\fR is \f(CW$Types::Serialiser::error\fR.
.SH "NOTES FOR XS USERS"
.IX Header "NOTES FOR XS USERS"
The recommended way to detect whether a scalar is one of these objects
is to check whether the stash is the \f(CW\*(C`Types::Serialiser::Boolean\*(C'\fR or
\&\f(CW\*(C`Types::Serialiser::Error\*(C'\fR stash, and then follow the scalar reference to
see if it's \f(CW1\fR (true), \f(CW0\fR (false) or \f(CW\*(C`undef\*(C'\fR (error).
.PP
While it is possible to use an isa test, directly comparing stash pointers
is faster and guaranteed to work.
.PP
For historical reasons, the \f(CW\*(C`Types::Serialiser::Boolean\*(C'\fR stash is
just an alias for \f(CW\*(C`JSON::PP::Boolean\*(C'\fR. When printed, the classname
with usually be \f(CW\*(C`JSON::PP::Boolean\*(C'\fR, but isa tests and stash pointer
comparison will normally work correctly (i.e. Types::Serialiser::true \s-1ISA\s0
JSON::PP::Boolean, but also \s-1ISA\s0 Types::Serialiser::Boolean).
.SH "A GENERIC OBJECT SERIALIATION PROTOCOL"
.IX Header "A GENERIC OBJECT SERIALIATION PROTOCOL"
This section explains the object serialisation protocol used by
\&\s-1CBOR::XS\s0. It is meant to be generic enough to support any kind of
generic object serialiser.
.PP
This protocol is called \*(L"the Types::Serialiser object serialisation
protocol\*(R".
.SS "\s-1ENCODING\s0"
.IX Subsection "ENCODING"
When the encoder encounters an object that it cannot otherwise encode (for
example, \s-1CBOR::XS\s0 can encode a few special types itself, and will first
attempt to use the special \f(CW\*(C`TO_CBOR\*(C'\fR serialisation protocol), it will
look up the \f(CW\*(C`FREEZE\*(C'\fR method on the object.
.PP
Note that the \f(CW\*(C`FREEZE\*(C'\fR method will normally be called \fIduring\fR encoding,
and \fI\s-1MUST NOT\s0\fR change the data structure that is being encoded in any
way, or it might cause memory corruption or worse.
.PP
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 \s-1CBOR::XS\s0 uses \f(CW\*(C`CBOR\*(C'\fR, and the \s-1JSON\s0 and \s-1JSON::XS\s0 modules
(or any other \s-1JSON\s0 serialiser), would use \f(CW\*(C`JSON\*(C'\fR as second argument.
.PP
The \f(CW\*(C`FREEZE\*(C'\fR 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 \s-1CBOR\s0 for example, there is a
registered tag number for encoded perl objects.
.PP
The values that \f(CW\*(C`FREEZE\*(C'\fR 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
\&\s-1JSON\s0 data model). You can always use a more complex format for a specific
data model by checking the second argument, the data model.
.PP
The \*(L"data model\*(R" is not the same as the \*(L"data format\*(R" \- the data model
indicates what types and kinds of return values can be returned from
\&\f(CW\*(C`FREEZE\*(C'\fR. For example, in \f(CW\*(C`CBOR\*(C'\fR it is permissible to return tagged \s-1CBOR\s0
values, while \s-1JSON\s0 does not support these at all, so \f(CW\*(C`JSON\*(C'\fR would be a
valid (but too limited) data model name for \f(CW\*(C`CBOR::XS\*(C'\fR. similarly, a
serialising format that supports more or less the same data model as \s-1JSON\s0
could use \f(CW\*(C`JSON\*(C'\fR as data model without losing anything.
.SS "\s-1DECODING\s0"
.IX Subsection "DECODING"
When the decoder then encounters such an encoded perl object, it should
look up the \f(CW\*(C`THAW\*(C'\fR 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 \f(CW\*(C`FREEZE\*(C'\fR.
.SS "\s-1EXAMPLES\s0"
.IX Subsection "EXAMPLES"
See the \f(CW\*(C`OBJECT SERIALISATION\*(C'\fR section in the \s-1CBOR::XS\s0 manpage for
more details, an example implementation, and code examples.
.PP
Here is an example \f(CW\*(C`FREEZE\*(C'\fR/\f(CW\*(C`THAW\*(C'\fR method pair:
.PP
.Vb 2
\&   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)
\&   }
.Ve
.SH "BUGS"
.IX Header "BUGS"
The use of overload makes this module much heavier than it should be
(on my system, this module: 4kB \s-1RSS,\s0 overload: 260kB \s-1RSS\s0).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Currently, \s-1JSON::XS\s0 and \s-1CBOR::XS\s0 use these types.
.SH "AUTHOR"
.IX Header "AUTHOR"
.Vb 2
\& Marc Lehmann <schmorp@schmorp.de>
\& http://home.schmorp.de/
.Ve

MR SKB