ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/Types-Serialiser/Serialiser.pm
(Generate patch)

Comparing Types-Serialiser/Serialiser.pm (file contents):
Revision 1.1 by root, Sun Oct 27 19:49:33 2013 UTC vs.
Revision 1.9 by root, Sat Nov 30 18:33:51 2013 UTC

… …
15 15
16=cut 16=cut
17 17
18package Types::Serialiser; 18package Types::Serialiser;
19 19
20use common::sense; 20use common::sense; # required to suppress annoying warnings
21 21
22our $VERSION = 0.01; 22our $VERSION = '1.0';
23 23
24=head1 SIMPLE SCALAR CONSTANTS 24=head1 SIMPLE SCALAR CONSTANTS
25 25
26Simple scalar constants are values that are overloaded to act like simple 26Simple scalar constants are values that are overloaded to act like simple
27Perl values, but have (class) type to differentiate them from normal Perl 27Perl values, but have (class) type to differentiate them from normal Perl
… …
97 97
98=back 98=back
99 99
100=cut 100=cut
101 101
102BEGIN {
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
102our $true = do { bless \(my $dummy = 1), Types::Serialiser::Boolean:: }; 124our $true = do { bless \(my $dummy = 1), Types::Serialiser::Boolean:: };
103our $false = do { bless \(my $dummy = 0), Types::Serialiser::Boolean:: }; 125our $false = do { bless \(my $dummy = 0), Types::Serialiser::Boolean:: };
104our $error = do { bless \(my $dummy ), Types::Serialiser::Error:: }; 126our $error = do { bless \(my $dummy ), Types::Serialiser::Error:: };
105 127
106sub true () { $true } 128sub true () { $true }
… …
110sub is_bool ($) { UNIVERSAL::isa $_[0], Types::Serialiser::Boolean:: } 132sub is_bool ($) { UNIVERSAL::isa $_[0], Types::Serialiser::Boolean:: }
111sub is_true ($) { $_[0] && UNIVERSAL::isa $_[0], Types::Serialiser::Boolean:: } 133sub is_true ($) { $_[0] && UNIVERSAL::isa $_[0], Types::Serialiser::Boolean:: }
112sub is_false ($) { !$_[0] && UNIVERSAL::isa $_[0], Types::Serialiser::Boolean:: } 134sub is_false ($) { !$_[0] && UNIVERSAL::isa $_[0], Types::Serialiser::Boolean:: }
113sub is_error ($) { UNIVERSAL::isa $_[0], Types::Serialiser::Error:: } 135sub is_error ($) { UNIVERSAL::isa $_[0], Types::Serialiser::Error:: }
114 136
115package Types::Serialiser::Boolean;
116
117use overload
118 "0+" => sub { ${$_[0]} },
119 "++" => sub { $_[0] = ${$_[0]} + 1 },
120 "--" => sub { $_[0] = ${$_[0]} - 1 },
121 fallback => 1;
122
123package Types::Serialiser::Error; 137package Types::Serialiser::Error;
124 138
125sub error { 139sub error {
126 require Carp; 140 require Carp;
127 Carp::croak ("caught attempt to use Types::Serialiser::error value"); 141 Carp::croak ("caught attempt to use the Types::Serialiser::error value");
128}; 142};
129 143
130use overload 144use overload
131 "0+" => \&error, 145 "0+" => \&error,
132 "++" => \&error, 146 "++" => \&error,
133 "--" => \&error, 147 "--" => \&error,
134 fallback => 1; 148 fallback => 1;
135 149
150=head1 NOTES FOR XS USERS
151
152The recommended way to detect whether a scalar is one of these objects
153is to check whether the stash is the C<Types::Serialiser::Boolean> or
154C<Types::Serialiser::Error> stash, and then follow the scalar reference to
155see if it's C<1> (true), C<0> (false) or C<undef> (error).
156
157While it is possible to use an isa test, directly comparing stash pointers
158is faster and guaranteed to work.
159
160For historical reasons, the C<Types::Serialiser::Boolean> stash is
161just an alias for C<JSON::PP::Boolean>. When printed, the classname
162with usually be C<JSON::PP::Boolean>, but isa tests and stash pointer
163comparison will normally work correctly (i.e. Types::Serialiser::true ISA
164JSON::PP::Boolean, but also ISA Types::Serialiser::Boolean).
165
166=head1 A GENERIC OBJECT SERIALIATION PROTOCOL
167
168This section explains the object serialisation protocol used by
169L<CBOR::XS>. It is meant to be generic enough to support any kind of
170generic object serialiser.
171
172This protocol is called "the Types::Serialiser object serialisation
173protocol".
174
175=head2 ENCODING
176
177When the encoder encounters an object that it cannot otherwise encode (for
178example, L<CBOR::XS> can encode a few special types itself, and will first
179attempt to use the special C<TO_CBOR> serialisation protocol), it will
180look up the C<FREEZE> method on the object.
181
182Note that the C<FREEZE> method will normally be called I<during> encoding,
183and I<MUST NOT> change the data structure that is being encoded in any
184way, or it might cause memory corruption or worse.
185
186If it exists, it will call it with two arguments: the object to serialise,
187and a constant string that indicates the name of the data model. For
188example L<CBOR::XS> uses C<CBOR>, and the L<JSON> and L<JSON::XS> modules
189(or any other JSON serialiser), would use C<JSON> as second argument.
190
191The C<FREEZE> method can then return zero or more values to identify the
192object instance. The serialiser is then supposed to encode the class name
193and all of these return values (which must be encodable in the format)
194using the relevant form for Perl objects. In CBOR for example, there is a
195registered tag number for encoded perl objects.
196
197The values that C<FREEZE> returns must be serialisable with the serialiser
198that calls it. Therefore, it is recommended to use simple types such as
199strings and numbers, and maybe array references and hashes (basically, the
200JSON data model). You can always use a more complex format for a specific
201data model by checking the second argument, the data model.
202
203The "data model" is not the same as the "data format" - the data model
204indicates what types and kinds of return values can be returned from
205C<FREEZE>. For example, in C<CBOR> it is permissible to return tagged CBOR
206values, while JSON does not support these at all, so C<JSON> would be a
207valid (but too limited) data model name for C<CBOR::XS>. similarly, a
208serialising format that supports more or less the same data model as JSON
209could use C<JSON> as data model without losing anything.
210
211=head2 DECODING
212
213When the decoder then encounters such an encoded perl object, it should
214look up the C<THAW> method on the stored classname, and invoke it with the
215classname, the constant string to identify the data model/data format, and
216all the return values returned by C<FREEZE>.
217
218=head2 EXAMPLES
219
220See the C<OBJECT SERIALISATION> section in the L<CBOR::XS> manpage for
221more details, an example implementation, and code examples.
222
223Here is an example C<FREEZE>/C<THAW> method pair:
224
225 sub My::Object::FREEZE {
226 my ($self, $model) = @_;
227
228 ($self->{type}, $self->{id}, $self->{variant})
229 }
230
231 sub My::Object::THAW {
232 my ($class, $model, $type, $id, $variant) = @_;
233
234 $class->new (type => $type, id => $id, variant => $variant)
235 }
236
136=head1 BUGS 237=head1 BUGS
137 238
138The use of L<overload> makes this module much heavier than it should be 239The use of L<overload> makes this module much heavier than it should be
139(on my system, this module: 4kB RSS, overload: 260kB RSS). 240(on my system, this module: 4kB RSS, overload: 260kB RSS).
140 241

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines