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

Comparing CBOR-XS/XS.pm (file contents):
Revision 1.6 by root, Sun Oct 27 20:40:25 2013 UTC vs.
Revision 1.7 by root, Sun Oct 27 22:35:15 2013 UTC

… …
221C<1> and C<0> (for true and false) or to throw an exception on access (for 221C<1> and C<0> (for true and false) or to throw an exception on access (for
222error). See the L<Types::Serialiser> manpage for details. 222error). See the L<Types::Serialiser> manpage for details.
223 223
224=item CBOR tag 256 (perl object) 224=item CBOR tag 256 (perl object)
225 225
226The tag value C<256> (TODO: pending iana registration) will be used to 226The tag value C<256> (TODO: pending iana registration) will be used
227deserialise a Perl object. 227to deserialise a Perl object serialised with C<FREEZE>. See "OBJECT
228 228SERIALISATION", below, for details.
229TODO For this to work, the class must be loaded and must have a
230C<FROM_CBOR> method. The decoder will then call the C<FROM_CBOR> method
231with the constructor arguments provided by the C<TO_CBOR> method (see
232below).
233
234The C<FROM_CBOR> method must return a single value that will then be used
235as the deserialised value.
236 229
237=item CBOR tag 55799 (magic header) 230=item CBOR tag 55799 (magic header)
238 231
239The tag 55799 is ignored (this tag implements the magic header). 232The tag 55799 is ignored (this tag implements the magic header).
240 233
… …
292 285
293These special values become CBOR true, CBOR false and CBOR undefined 286These special values become CBOR true, CBOR false and CBOR undefined
294values, respectively. You can also use C<\1>, C<\0> and C<\undef> directly 287values, respectively. You can also use C<\1>, C<\0> and C<\undef> directly
295if you want. 288if you want.
296 289
297=item blessed objects 290=item other blessed objects
298 291
299Other blessed objects currently need to have a C<TO_CBOR> method. It 292Other blessed objects are serialised via C<TO_CBOR> or C<FREEZE>. See
300will be called on every object that is being serialised, and must return 293"OBJECT SERIALISATION", below, for details.
301something that can be encoded in CBOR.
302 294
303=item simple scalars 295=item simple scalars
304 296
305TODO 297TODO
306Simple Perl scalars (any scalar that is not a reference) are the most 298Simple Perl scalars (any scalar that is not a reference) are the most
… …
344represent numerical values are supported, but might suffer loss of 336represent numerical values are supported, but might suffer loss of
345precision. 337precision.
346 338
347=back 339=back
348 340
341=head2 OBJECT SERIALISATION
349 342
343This module knows two way to serialise a Perl object: The CBOR-specific
344way, and the generic way.
345
346Whenever the encoder encounters a Perl object that it cnanot serialise
347directly (most of them), it will first look up the C<TO_CBOR> method on
348it.
349
350If it has a C<TO_CBOR> method, it will call it with the object as only
351argument, and expects exactly one return value, which it will then
352substitute and encode it in the place of the object.
353
354Otherwise, it will look up the C<FREEZE> method. If it exists, it will
355call it with the object as first argument, and the constant string C<CBOR>
356as the second argument, to distinguish it from other serialisers.
357
358The C<FREEZE> method can return any number of values (i.e. zero or
359more). These will be encoded as CBOR perl object, together with the
360classname.
361
362If an object supports neither C<TO_CBOR> nor C<FREEZE>, encoding will fail
363with an error.
364
365Objects encoded via C<TO_CBOR> cannot be automatically decoded, but
366objects encoded via C<FREEZE> can be decoded using the following protocol:
367
368When an encoded CBOR perl object is encountered by the decoder, it will
369look up the C<THAW> method, by using the stored classname, and will fail
370if the method cannot be found.
371
372After the lookup it will call the C<THAW> method with the stored classname
373as first argument, the constant string C<CBOR> as second argument, and all
374values returned by C<FREEZE> as remaining arguments.
375
376=head4 EXAMPLES
377
378Here is an example C<TO_CBOR> method:
379
380 sub My::Object::TO_CBOR {
381 my ($obj) = @_;
382
383 ["this is a serialised My::Object object", $obj->{id}]
384 }
385
386When a C<My::Object> is encoded to CBOR, it will instead encode a simple
387array with two members: a string, and the "object id". Decoding this CBOR
388string will yield a normal perl array reference in place of the object.
389
390A more useful and practical example would be a serialisation method for
391the URI module. CBOR has a custom tag value for URIs, namely 32:
392
393 sub URI::TO_CBOR {
394 my ($self) = @_;
395 my $uri = "$self"; # stringify uri
396 utf8::upgrade $uri; # make sure it will be encoded as UTF-8 string
397 CBOR::XS::tagged 32, "$_[0]"
398 }
399
400This will encode URIs as a UTF-8 string with tag 32, which indicates an
401URI.
402
403Decoding such an URI will not (currently) give you an URI object, but
404instead a CBOR::XS::Tagged object with tag number 32 and the string -
405exactly what was returned by C<TO_CBOR>.
406
407To serialise an object so it can automatically be deserialised, you need
408to use C<FREEZE> and C<THAW>. To take the URI module as example, this
409would be a possible implementation:
410
411 sub URI::FREEZE {
412 my ($self, $serialiser) = @_;
413 "$self" # encode url string
414 }
415
416 sub URI::THAW {
417 my ($class, $serialiser, $uri) = @_;
418
419 $class->new ($uri)
420 }
421
422Unlike C<TO_CBOR>, multiple values can be returned by C<FREEZE>. For
423example, a C<FREEZE> method that returns "type", "id" and "variant" values
424would cause an invocation of C<THAW> with 5 arguments:
425
426 sub My::Object::FREEZE {
427 my ($self, $serialiser) = @_;
428
429 ($self->{type}, $self->{id}, $self->{variant})
430 }
431
432 sub My::Object::THAW {
433 my ($class, $serialiser, $type, $id, $variant) = @_;
434
435 $class-<new (type => $type, id => $id, variant => $variant)
436 }
437
438
350=head2 MAGIC HEADER 439=head1 MAGIC HEADER
351 440
352There is no way to distinguish CBOR from other formats 441There is no way to distinguish CBOR from other formats
353programmatically. To make it easier to distinguish CBOR from other 442programmatically. To make it easier to distinguish CBOR from other
354formats, the CBOR specification has a special "magic string" that can be 443formats, the CBOR specification has a special "magic string" that can be
355prepended to any CBOR string without changing it's meaning. 444prepended to any CBOR string without changing it's meaning.
… …
358prepend this string tot he CBOR data it generates, but it will ignroe it 447prepend this string tot he CBOR data it generates, but it will ignroe it
359if present, so users can prepend this string as a "file type" indicator as 448if present, so users can prepend this string as a "file type" indicator as
360required. 449required.
361 450
362 451
363=head2 CBOR and JSON 452=head1 CBOR and JSON
364 453
365CBOR is supposed to implement a superset of the JSON data model, and is, 454CBOR is supposed to implement a superset of the JSON data model, and is,
366with some coercion, able to represent all JSON texts (something that other 455with some coercion, able to represent all JSON texts (something that other
367"binary JSON" formats such as BSON generally do not support). 456"binary JSON" formats such as BSON generally do not support).
368 457

Diff Legend

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