1Serialiser(3) User Contributed Perl Documentation Serialiser(3)
2
6 Types::Serialiser - simple data types for common serialisation formats
7
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
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 BOOLEANS (Types::Serialiser::Boolean class)
23 This type has only two instances, true and false. A natural
24 representation for these in Perl is 1 and 0, but serialisation formats
25 need to be able to differentiate between them and mere numbers.
26 $Types::Serialiser::true, Types::Serialiser::true
28 This value represents the "true" value. In most contexts is acts
29 like the number 1. It is up to you whether you use the variable
30 form ($Types::Serialiser::true) or the constant form
31 ("Types::Serialiser::true").
32 The constant is represented as a reference to a scalar containing 1
34 - implementations are allowed to directly test for this.
35 $Types::Serialiser::false, Types::Serialiser::false
37 This value represents the "false" value. In most contexts is acts
38 like the number 0. It is up to you whether you use the variable
39 form ($Types::Serialiser::false) or the constant form
40 ("Types::Serialiser::false").
41 The constant is represented as a reference to a scalar containing 0
43 - implementations are allowed to directly test for this.
44 $is_bool = Types::Serialiser::is_bool $value
46 Returns true iff the $value is either $Types::Serialiser::true or
47 $Types::Serialiser::false.
48 For example, you could differentiate between a perl true value and
50 a "Types::Serialiser::true" by using this:
51 $value && Types::Serialiser::is_bool $value
53 $is_true = Types::Serialiser::is_true $value
55 Returns true iff $value is $Types::Serialiser::true.
56 $is_false = Types::Serialiser::is_false $value
58 Returns false iff $value is $Types::Serialiser::false.
59 ERROR (Types::Serialiser::Error class)
61 This class has only a single instance, "error". It is used to signal an
62 encoding or decoding error. In CBOR for example, and object that
63 couldn't be encoded will be represented by a CBOR undefined value,
64 which is represented by the error value in Perl.
65 $Types::Serialiser::error, Types::Serialiser::error
67 This value represents the "error" value. Accessing values of this
68 type will throw an exception.
69 The constant is represented as a reference to a scalar containing
71 "undef" - implementations are allowed to directly test for this.
72 $is_error = Types::Serialiser::is_error $value
74 Returns false iff $value is $Types::Serialiser::error.
75
77 The recommended way to detect whether a scalar is one of these objects
78 is to check whether the stash is the "Types::Serialiser::Boolean" or
79 "Types::Serialiser::Error" stash, and then follow the scalar reference
80 to see if it's 1 (true), 0 (false) or "undef" (error).
81 While it is possible to use an isa test, directly comparing stash
83 pointers is faster and guaranteed to work.
84 For historical reasons, the "Types::Serialiser::Boolean" stash is just
86 an alias for "JSON::PP::Boolean". When printed, the classname with
87 usually be "JSON::PP::Boolean", but isa tests and stash pointer
88 comparison will normally work correctly (i.e. Types::Serialiser::true
89 ISA JSON::PP::Boolean, but also ISA Types::Serialiser::Boolean).
90
92 This section explains the object serialisation protocol used by
93 CBOR::XS. It is meant to be generic enough to support any kind of
94 generic object serialiser.
95 This protocol is called "the Types::Serialiser object serialisation
97 protocol".
98 ENCODING
100 When the encoder encounters an object that it cannot otherwise encode
101 (for example, CBOR::XS can encode a few special types itself, and will
102 first attempt to use the special "TO_CBOR" serialisation protocol), it
103 will look up the "FREEZE" method on the object.
104 Note that the "FREEZE" method will normally be called during encoding,
106 and MUST NOT change the data structure that is being encoded in any
107 way, or it might cause memory corruption or worse.
108 If it exists, it will call it with two arguments: the object to
110 serialise, and a constant string that indicates the name of the data
111 model. For example CBOR::XS uses "CBOR", and the JSON and JSON::XS
112 modules (or any other JSON serialiser), would use "JSON" as second
113 argument.
114 The "FREEZE" method can then return zero or more values to identify the
116 object instance. The serialiser is then supposed to encode the class
117 name and all of these return values (which must be encodable in the
118 format) using the relevant form for Perl objects. In CBOR for example,
119 there is a registered tag number for encoded perl objects.
120 The values that "FREEZE" returns must be serialisable with the
122 serialiser that calls it. Therefore, it is recommended to use simple
123 types such as strings and numbers, and maybe array references and
124 hashes (basically, the JSON data model). You can always use a more
125 complex format for a specific data model by checking the second
126 argument, the data model.
127 The "data model" is not the same as the "data format" - the data model
129 indicates what types and kinds of return values can be returned from
130 "FREEZE". For example, in "CBOR" it is permissible to return tagged
131 CBOR values, while JSON does not support these at all, so "JSON" would
132 be a valid (but too limited) data model name for "CBOR::XS". similarly,
133 a serialising format that supports more or less the same data model as
134 JSON could use "JSON" as data model without losing anything.
135 DECODING
137 When the decoder then encounters such an encoded perl object, it should
138 look up the "THAW" method on the stored classname, and invoke it with
139 the classname, the constant string to identify the data model/data
140 format, and all the return values returned by "FREEZE".
141 EXAMPLES
143 See the "OBJECT SERIALISATION" section in the CBOR::XS manpage for more
144 details, an example implementation, and code examples.
145 Here is an example "FREEZE"/"THAW" method pair:
147 sub My::Object::FREEZE {
149 my ($self, $model) = @_;
150 ($self->{type}, $self->{id}, $self->{variant})
152 }
153 sub My::Object::THAW {
155 my ($class, $model, $type, $id, $variant) = @_;
156 $class->new (type => $type, id => $id, variant => $variant)
158 }
159
161 The use of overload makes this module much heavier than it should be
162 (on my system, this module: 4kB RSS, overload: 260kB RSS).
163
165 Currently, JSON::XS and CBOR::XS use these types.
166
168 Marc Lehmann <schmorp@schmorp.de>
169 http://home.schmorp.de/
170perl v5.32.0 2020-07-28 Serialiser(3)