1Serialiser(3)         User Contributed Perl Documentation        Serialiser(3)
2
3
4

NAME

6       Types::Serialiser - simple data types for common serialisation formats
7

SYNOPSIS

DESCRIPTION

10       This module provides some extra datatypes that are used by common
11       serialisation formats such as JSON or CBOR. The idea is to have a
12       repository of simple/small constants and containers that can be shared
13       by different implementations so they become interoperable between each
14       other.
15

SIMPLE SCALAR CONSTANTS

17       Simple scalar constants are values that are overloaded to act like
18       simple Perl values, but have (class) type to differentiate them from
19       normal Perl scalars. This is necessary because these have different
20       representations in the serialisation formats.
21
22       In the following, functions with zero or one arguments have a prototype
23       of "()" and "($)", respectively, so act as constants and unary
24       operators.
25
26   BOOLEANS (Types::Serialiser::Boolean class)
27       This type has only two instances, true and false. A natural
28       representation for these in Perl is 1 and 0, but serialisation formats
29       need to be able to differentiate between them and mere numbers.
30
31       $Types::Serialiser::true, Types::Serialiser::true
32           This value represents the "true" value. In most contexts is acts
33           like the number 1. It is up to you whether you use the variable
34           form ($Types::Serialiser::true) or the constant form
35           ("Types::Serialiser::true").
36
37           The constant is represented as a reference to a scalar containing 1
38           - implementations are allowed to directly test for this.
39
40       $Types::Serialiser::false, Types::Serialiser::false
41           This value represents the "false" value. In most contexts is acts
42           like the number 0. It is up to you whether you use the variable
43           form ($Types::Serialiser::false) or the constant form
44           ("Types::Serialiser::false").
45
46           The constant is represented as a reference to a scalar containing 0
47           - implementations are allowed to directly test for this.
48
49       Types::Serialiser::as_bool $value
50           Converts a Perl scalar into a boolean, which is useful syntactic
51           sugar. Strictly equivalent to:
52
53              $value ? $Types::Serialiser::true : $Types::Serialiser::false
54
55       $is_bool = Types::Serialiser::is_bool $value
56           Returns true iff the $value is either $Types::Serialiser::true or
57           $Types::Serialiser::false.
58
59           For example, you could differentiate between a perl true value and
60           a "Types::Serialiser::true" by using this:
61
62              $value && Types::Serialiser::is_bool $value
63
64       $is_true = Types::Serialiser::is_true $value
65           Returns true iff $value is $Types::Serialiser::true.
66
67       $is_false = Types::Serialiser::is_false $value
68           Returns false iff $value is $Types::Serialiser::false.
69
70   ERROR (Types::Serialiser::Error class)
71       This class has only a single instance, "error". It is used to signal an
72       encoding or decoding error. In CBOR for example, and object that
73       couldn't be encoded will be represented by a CBOR undefined value,
74       which is represented by the error value in Perl.
75
76       $Types::Serialiser::error, Types::Serialiser::error
77           This value represents the "error" value. Accessing values of this
78           type will throw an exception.
79
80           The constant is represented as a reference to a scalar containing
81           "undef" - implementations are allowed to directly test for this.
82
83       $is_error = Types::Serialiser::is_error $value
84           Returns false iff $value is $Types::Serialiser::error.
85

NOTES FOR XS USERS

87       The recommended way to detect whether a scalar is one of these objects
88       is to check whether the stash is the "Types::Serialiser::Boolean" or
89       "Types::Serialiser::Error" stash, and then follow the scalar reference
90       to see if it's 1 (true), 0 (false) or "undef" (error).
91
92       While it is possible to use an isa test, directly comparing stash
93       pointers is faster and guaranteed to work.
94
95       For historical reasons, the "Types::Serialiser::Boolean" stash is just
96       an alias for "JSON::PP::Boolean". When printed, the classname with
97       usually be "JSON::PP::Boolean", but isa tests and stash pointer
98       comparison will normally work correctly (i.e. Types::Serialiser::true
99       ISA JSON::PP::Boolean, but also ISA Types::Serialiser::Boolean).
100

A GENERIC OBJECT SERIALIATION PROTOCOL

102       This section explains the object serialisation protocol used by
103       CBOR::XS. It is meant to be generic enough to support any kind of
104       generic object serialiser.
105
106       This protocol is called "the Types::Serialiser object serialisation
107       protocol".
108
109   ENCODING
110       When the encoder encounters an object that it cannot otherwise encode
111       (for example, CBOR::XS can encode a few special types itself, and will
112       first attempt to use the special "TO_CBOR" serialisation protocol), it
113       will look up the "FREEZE" method on the object.
114
115       Note that the "FREEZE" method will normally be called during encoding,
116       and MUST NOT change the data structure that is being encoded in any
117       way, or it might cause memory corruption or worse.
118
119       If it exists, it will call it with two arguments: the object to
120       serialise, and a constant string that indicates the name of the data
121       model. For example CBOR::XS uses "CBOR", and the JSON and JSON::XS
122       modules (or any other JSON serialiser), would use "JSON" as second
123       argument.
124
125       The "FREEZE" method can then return zero or more values to identify the
126       object instance. The serialiser is then supposed to encode the class
127       name and all of these return values (which must be encodable in the
128       format) using the relevant form for Perl objects. In CBOR for example,
129       there is a registered tag number for encoded perl objects.
130
131       The values that "FREEZE" returns must be serialisable with the
132       serialiser that calls it. Therefore, it is recommended to use simple
133       types such as strings and numbers, and maybe array references and
134       hashes (basically, the JSON data model). You can always use a more
135       complex format for a specific data model by checking the second
136       argument, the data model.
137
138       The "data model" is not the same as the "data format" - the data model
139       indicates what types and kinds of return values can be returned from
140       "FREEZE". For example, in "CBOR" it is permissible to return tagged
141       CBOR values, while JSON does not support these at all, so "JSON" would
142       be a valid (but too limited) data model name for "CBOR::XS". similarly,
143       a serialising format that supports more or less the same data model as
144       JSON could use "JSON" as data model without losing anything.
145
146   DECODING
147       When the decoder then encounters such an encoded perl object, it should
148       look up the "THAW" method on the stored classname, and invoke it with
149       the classname, the constant string to identify the data model/data
150       format, and all the return values returned by "FREEZE".
151
152   EXAMPLES
153       See the "OBJECT SERIALISATION" section in the CBOR::XS manpage for more
154       details, an example implementation, and code examples.
155
156       Here is an example "FREEZE"/"THAW" method pair:
157
158          sub My::Object::FREEZE {
159             my ($self, $model) = @_;
160
161             ($self->{type}, $self->{id}, $self->{variant})
162          }
163
164          sub My::Object::THAW {
165             my ($class, $model, $type, $id, $variant) = @_;
166
167             $class->new (type => $type, id => $id, variant => $variant)
168          }
169

BUGS

171       The use of overload makes this module much heavier than it should be
172       (on my system, this module: 4kB RSS, overload: 260kB RSS).
173

SEE ALSO

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

AUTHOR

178        Marc Lehmann <schmorp@schmorp.de>
179        http://home.schmorp.de/
180
181
182
183perl v5.36.0                      2023-01-20                     Serialiser(3)
Impressum