1 |
=head1 NAME |
2 |
|
3 |
Types::Serialiser - simple data types for common serialisation formats |
4 |
|
5 |
=encoding utf-8 |
6 |
|
7 |
=head1 SYNOPSIS |
8 |
|
9 |
=head1 DESCRIPTION |
10 |
|
11 |
This module provides some extra datatypes that are used by common |
12 |
serialisation formats such as JSON or CBOR. The idea is to have a |
13 |
repository of simple/small constants and containers that can be shared by |
14 |
different implementations so they become interoperable between each other. |
15 |
|
16 |
=cut |
17 |
|
18 |
package Types::Serialiser; |
19 |
|
20 |
use common::sense; # required to suppress annoying warnings |
21 |
|
22 |
our $VERSION = 0.03; |
23 |
|
24 |
=head1 SIMPLE SCALAR CONSTANTS |
25 |
|
26 |
Simple scalar constants are values that are overloaded to act like simple |
27 |
Perl values, but have (class) type to differentiate them from normal Perl |
28 |
scalars. This is necessary because these have different representations in |
29 |
the serialisation formats. |
30 |
|
31 |
=head2 BOOLEANS (Types::Serialiser::Boolean class) |
32 |
|
33 |
This type has only two instances, true and false. A natural representation |
34 |
for these in Perl is C<1> and C<0>, but serialisation formats need to be |
35 |
able to differentiate between them and mere numbers. |
36 |
|
37 |
=over 4 |
38 |
|
39 |
=item $Types::Serialiser::true, Types::Serialiser::true |
40 |
|
41 |
This value represents the "true" value. In most contexts is acts like |
42 |
the number C<1>. It is up to you whether you use the variable form |
43 |
(C<$Types::Serialiser::true>) or the constant form (C<Types::Serialiser::true>). |
44 |
|
45 |
The constant is represented as a reference to a scalar containing C<1> - |
46 |
implementations are allowed to directly test for this. |
47 |
|
48 |
=item $Types::Serialiser::false, Types::Serialiser::false |
49 |
|
50 |
This value represents the "false" value. In most contexts is acts like |
51 |
the number C<0>. It is up to you whether you use the variable form |
52 |
(C<$Types::Serialiser::false>) or the constant form (C<Types::Serialiser::false>). |
53 |
|
54 |
The constant is represented as a reference to a scalar containing C<0> - |
55 |
implementations are allowed to directly test for this. |
56 |
|
57 |
=item $is_bool = Types::Serialiser::is_bool $value |
58 |
|
59 |
Returns true iff the C<$value> is either C<$Types::Serialiser::true> or |
60 |
C<$Types::Serialiser::false>. |
61 |
|
62 |
For example, you could differentiate between a perl true value and a |
63 |
C<Types::Serialiser::true> by using this: |
64 |
|
65 |
$value && Types::Serialiser::is_bool $value |
66 |
|
67 |
=item $is_true = Types::Serialiser::is_true $value |
68 |
|
69 |
Returns true iff C<$value> is C<$Types::Serialiser::true>. |
70 |
|
71 |
=item $is_false = Types::Serialiser::is_false $value |
72 |
|
73 |
Returns false iff C<$value> is C<$Types::Serialiser::false>. |
74 |
|
75 |
=back |
76 |
|
77 |
=head2 ERROR (Types::Serialiser::Error class) |
78 |
|
79 |
This class has only a single instance, C<error>. It is used to signal |
80 |
an encoding or decoding error. In CBOR for example, and object that |
81 |
couldn't be encoded will be represented by a CBOR undefined value, which |
82 |
is represented by the error value in Perl. |
83 |
|
84 |
=over 4 |
85 |
|
86 |
=item $Types::Serialiser::error, Types::Serialiser::error |
87 |
|
88 |
This value represents the "error" value. Accessing values of this type |
89 |
will throw an exception. |
90 |
|
91 |
The constant is represented as a reference to a scalar containing C<undef> |
92 |
- implementations are allowed to directly test for this. |
93 |
|
94 |
=item $is_error = Types::Serialiser::is_error $value |
95 |
|
96 |
Returns false iff C<$value> is C<$Types::Serialiser::error>. |
97 |
|
98 |
=back |
99 |
|
100 |
=cut |
101 |
|
102 |
BEGIN { |
103 |
# for historical reasons, and to avoid extra dependencies in JSON::PP, |
104 |
# we alias *Types::Serialiser::Boolean with JSON::PP::Boolean. |
105 |
package JSON::PP::Boolean; |
106 |
|
107 |
*Types::Serialiser::Boolean:: = *JSON::PP::Boolean::; |
108 |
} |
109 |
|
110 |
{ |
111 |
# this must done before blessing to work around bugs |
112 |
# in perl < 5.18 (it seems to be fixed in 5.18). |
113 |
package Types::Serialiser::BooleanBase; |
114 |
|
115 |
use overload |
116 |
"0+" => sub { ${$_[0]} }, |
117 |
"++" => sub { $_[0] = ${$_[0]} + 1 }, |
118 |
"--" => sub { $_[0] = ${$_[0]} - 1 }, |
119 |
fallback => 1; |
120 |
|
121 |
@Types::Serialiser::Boolean::ISA = Types::Serialiser::BooleanBase::; |
122 |
} |
123 |
|
124 |
our $true = do { bless \(my $dummy = 1), Types::Serialiser::Boolean:: }; |
125 |
our $false = do { bless \(my $dummy = 0), Types::Serialiser::Boolean:: }; |
126 |
our $error = do { bless \(my $dummy ), Types::Serialiser::Error:: }; |
127 |
|
128 |
sub true () { $true } |
129 |
sub false () { $false } |
130 |
sub error () { $error } |
131 |
|
132 |
sub is_bool ($) { UNIVERSAL::isa $_[0], Types::Serialiser::Boolean:: } |
133 |
sub is_true ($) { $_[0] && UNIVERSAL::isa $_[0], Types::Serialiser::Boolean:: } |
134 |
sub is_false ($) { !$_[0] && UNIVERSAL::isa $_[0], Types::Serialiser::Boolean:: } |
135 |
sub is_error ($) { UNIVERSAL::isa $_[0], Types::Serialiser::Error:: } |
136 |
|
137 |
package Types::Serialiser::Error; |
138 |
|
139 |
sub error { |
140 |
require Carp; |
141 |
Carp::croak ("caught attempt to use the Types::Serialiser::error value"); |
142 |
}; |
143 |
|
144 |
use overload |
145 |
"0+" => \&error, |
146 |
"++" => \&error, |
147 |
"--" => \&error, |
148 |
fallback => 1; |
149 |
|
150 |
=head1 NOTES FOR XS USERS |
151 |
|
152 |
The recommended way to detect whether a scalar is one of these objects |
153 |
is to check whether the stash is the C<Types::Serialiser::Boolean> or |
154 |
C<Types::Serialiser::Error> stash, and then follow the scalar reference to |
155 |
see if it's C<1> (true), C<0> (false) or C<undef> (error). |
156 |
|
157 |
While it is possible to use an isa test, directly comparing stash pointers |
158 |
is faster and guaranteed to work. |
159 |
|
160 |
For historical reasons, the C<Types::Serialiser::Boolean> stash is |
161 |
just an alias for C<JSON::PP::Boolean>. When printed, the classname |
162 |
withh usually be C<JSON::PP::Boolean>, but isa tests and stash pointer |
163 |
comparison will normally work correctly (i.e. Types::Serialiser::true ISA |
164 |
JSON::PP::Boolean, but also ISA Types::Serialiser::Boolean). |
165 |
|
166 |
=head1 A GENERIC OBJECT SERIALIATION PROTOCOL |
167 |
|
168 |
This section explains the object serialisation protocol used by |
169 |
L<CBOR::XS>. It is meant to be generic enough to support any kind of |
170 |
generic object serialiser. |
171 |
|
172 |
This protocol is called "the Types::Serialiser object serialisation |
173 |
protocol". |
174 |
|
175 |
=head2 ENCODING |
176 |
|
177 |
When the encoder encounters an object that it cannot otherwise encode (for |
178 |
example, L<CBOR::XS> can encode a few special types itself, and will first |
179 |
attempt to use the special C<TO_CBOR> serialisation protocol), it will |
180 |
look up the C<FREEZE> method on the object. |
181 |
|
182 |
If it exists, it will call it with two arguments: the object to |
183 |
serialise, and a constant string that indicates the name of the |
184 |
serialisationformat. For example L<CBOR::XS> uses C<CBOR>, and L<JSON> and |
185 |
L<JSON::XS> (or any other JSON serialiser), would use C<JSON> as second |
186 |
argument. |
187 |
|
188 |
The C<FREEZE> method can then return zero or more values to identify the |
189 |
object instance. The serialiser is then supposed to encode the class name |
190 |
and all of these return values (which must be encodable in the format) |
191 |
using the relevant form for perl objects. In CBOR for example, there is a |
192 |
registered tag number for encoded perl objects. |
193 |
|
194 |
The values that C<FREEZE> returns must be serialisable with the serialiser |
195 |
that calls it. Therefore, it is recommended to use simple types such as |
196 |
strings and numbers, and maybe array references and hashes (basically, the |
197 |
JSON data model). You can always use a more complex format for a specific |
198 |
serialiser by checking the second argument. |
199 |
|
200 |
=head2 DECODING |
201 |
|
202 |
When the decoder then encounters such an encoded perl object, it should |
203 |
look up the C<THAW> method on the stored classname, and invoke it with the |
204 |
classname, the constant string to identify the format, and all the return |
205 |
values returned by C<FREEZE>. |
206 |
|
207 |
=head2 EXAMPLES |
208 |
|
209 |
See the C<OBJECT SERIALISATION> section in the L<CBOR::XS> manpage for |
210 |
more details, an example implementation, and code examples. |
211 |
|
212 |
Here is an example C<FREEZE>/C<THAW> method pair: |
213 |
|
214 |
sub My::Object::FREEZE { |
215 |
my ($self, $serialiser) = @_; |
216 |
|
217 |
($self->{type}, $self->{id}, $self->{variant}) |
218 |
} |
219 |
|
220 |
sub My::Object::THAW { |
221 |
my ($class, $serialiser, $type, $id, $variant) = @_; |
222 |
|
223 |
$class->new (type => $type, id => $id, variant => $variant) |
224 |
} |
225 |
|
226 |
=head1 BUGS |
227 |
|
228 |
The use of L<overload> makes this module much heavier than it should be |
229 |
(on my system, this module: 4kB RSS, overload: 260kB RSS). |
230 |
|
231 |
=head1 SEE ALSO |
232 |
|
233 |
Currently, L<JSON::XS> and L<CBOR::XS> use these types. |
234 |
|
235 |
=head1 AUTHOR |
236 |
|
237 |
Marc Lehmann <schmorp@schmorp.de> |
238 |
http://home.schmorp.de/ |
239 |
|
240 |
=cut |
241 |
|
242 |
1 |
243 |
|