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.8 by root, Mon Nov 4 15:12:16 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
… …
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 serialise, 186If it exists, it will call it with two arguments: the object to serialise,
183and a constant string that indicates the name of the data model or data 187and a constant string that indicates the name of the data model. For
184format. For example L<CBOR::XS> uses C<CBOR>, and L<JSON> and L<JSON::XS> 188example L<CBOR::XS> uses C<CBOR>, and the L<JSON> and L<JSON::XS> modules
185(or any other JSON serialiser), would use C<JSON> as second argument. 189(or any other JSON serialiser), would use C<JSON> as second argument.
186 190
187The 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
188object instance. The serialiser is then supposed to encode the class name 192object instance. The serialiser is then supposed to encode the class name
189and 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)
190using 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
191registered tag number for encoded perl objects. 195registered tag number for encoded perl objects.
192 196
193The values that C<FREEZE> returns must be serialisable with the serialiser 197The values that C<FREEZE> returns must be serialisable with the serialiser
194that 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
195strings and numbers, and maybe array references and hashes (basically, the 199strings and numbers, and maybe array references and hashes (basically, the
196JSON 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
197data model 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.
198 210
199=head2 DECODING 211=head2 DECODING
200 212
201When the decoder then encounters such an encoded perl object, it should 213When the decoder then encounters such an encoded perl object, it should
202look 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

Diff Legend

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