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.6 by root, Tue Oct 29 13:08:35 2013 UTC vs.
Revision 1.9 by root, Sat Nov 30 18:33:51 2013 UTC

… …
17 17
18package Types::Serialiser; 18package Types::Serialiser;
19 19
20use common::sense; # required to suppress annoying warnings 20use common::sense; # required to suppress annoying warnings
21 21
22our $VERSION = 0.03; 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
… …
157While it is possible to use an isa test, directly comparing stash pointers 157While it is possible to use an isa test, directly comparing stash pointers
158is faster and guaranteed to work. 158is faster and guaranteed to work.
159 159
160For historical reasons, the C<Types::Serialiser::Boolean> stash is 160For historical reasons, the C<Types::Serialiser::Boolean> stash is
161just an alias for C<JSON::PP::Boolean>. When printed, the classname 161just an alias for C<JSON::PP::Boolean>. When printed, the classname
162withh usually be C<JSON::PP::Boolean>, but isa tests and stash pointer 162with usually be C<JSON::PP::Boolean>, but isa tests and stash pointer
163comparison will normally work correctly (i.e. Types::Serialiser::true ISA 163comparison will normally work correctly (i.e. Types::Serialiser::true ISA
164JSON::PP::Boolean, but also ISA Types::Serialiser::Boolean). 164JSON::PP::Boolean, but also ISA Types::Serialiser::Boolean).
165 165
166=head1 A GENERIC OBJECT SERIALIATION PROTOCOL 166=head1 A GENERIC OBJECT SERIALIATION PROTOCOL
167 167
… …
177When the encoder encounters an object that it cannot otherwise encode (for 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 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 179attempt to use the special C<TO_CBOR> serialisation protocol), it will
180look up the C<FREEZE> method on the object. 180look up the C<FREEZE> method on the object.
181 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
182If it exists, it will call it with two arguments: the object to 186If it exists, it will call it with two arguments: the object to serialise,
183serialise, and a constant string that indicates the name of the 187and a constant string that indicates the name of the data model. For
184serialisationformat. For example L<CBOR::XS> uses C<CBOR>, and L<JSON> and 188example L<CBOR::XS> uses C<CBOR>, and the L<JSON> and L<JSON::XS> modules
185L<JSON::XS> (or any other JSON serialiser), would use C<JSON> as second 189(or any other JSON serialiser), would use C<JSON> as second argument.
186argument.
187 190
188The C<FREEZE> method can then return zero or more values to identify the 191The C<FREEZE> method can then return zero or more values to identify the
189object instance. The serialiser is then supposed to encode the class name 192object instance. The serialiser is then supposed to encode the class name
190and all of these return values (which must be encodable in the format) 193and all of these return values (which must be encodable in the format)
191using the relevant form for perl objects. In CBOR for example, there is a 194using the relevant form for Perl objects. In CBOR for example, there is a
192registered tag number for encoded perl objects. 195registered tag number for encoded perl objects.
193 196
194The values that C<FREEZE> returns must be serialisable with the serialiser 197The values that C<FREEZE> returns must be serialisable with the serialiser
195that calls it. Therefore, it is recommended to use simple types such as 198that calls it. Therefore, it is recommended to use simple types such as
196strings and numbers, and maybe array references and hashes (basically, the 199strings and numbers, and maybe array references and hashes (basically, the
197JSON data model). You can always use a more complex format for a specific 200JSON data model). You can always use a more complex format for a specific
198serialiser by checking the second argument. 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.
199 210
200=head2 DECODING 211=head2 DECODING
201 212
202When the decoder then encounters such an encoded perl object, it should 213When the decoder then encounters such an encoded perl object, it should
203look up the C<THAW> method on the stored classname, and invoke it with the 214look up the C<THAW> method on the stored classname, and invoke it with the
204classname, the constant string to identify the format, and all the return 215classname, the constant string to identify the data model/data format, and
205values returned by C<FREEZE>. 216all the return values returned by C<FREEZE>.
206 217
207=head2 EXAMPLES 218=head2 EXAMPLES
208 219
209See the C<OBJECT SERIALISATION> section in the L<CBOR::XS> manpage for 220See the C<OBJECT SERIALISATION> section in the L<CBOR::XS> manpage for
210more details, an example implementation, and code examples. 221more details, an example implementation, and code examples.
211 222
212Here is an example C<FREEZE>/C<THAW> method pair: 223Here is an example C<FREEZE>/C<THAW> method pair:
213 224
214 sub My::Object::FREEZE { 225 sub My::Object::FREEZE {
215 my ($self, $serialiser) = @_; 226 my ($self, $model) = @_;
216 227
217 ($self->{type}, $self->{id}, $self->{variant}) 228 ($self->{type}, $self->{id}, $self->{variant})
218 } 229 }
219 230
220 sub My::Object::THAW { 231 sub My::Object::THAW {
221 my ($class, $serialiser, $type, $id, $variant) = @_; 232 my ($class, $model, $type, $id, $variant) = @_;
222 233
223 $class-<new (type => $type, id => $id, variant => $variant) 234 $class->new (type => $type, id => $id, variant => $variant)
224 } 235 }
225 236
226=head1 BUGS 237=head1 BUGS
227 238
228The 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

Diff Legend

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