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