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.11 by root, Tue Oct 29 00:20:26 2013 UTC

… …
26 substr $many_cbor_strings, 0, $length, ""; # remove decoded cbor string 26 substr $many_cbor_strings, 0, $length, ""; # remove decoded cbor string
27 } 27 }
28 28
29=head1 DESCRIPTION 29=head1 DESCRIPTION
30 30
31WARNING! THIS IS A PRE-ALPHA RELEASE! IT WILL CRASH, CORRUPT YOUR DATA 31WARNING! This module is very new, and not very well tested (that's up to
32AND EAT YOUR CHILDREN! (Actually, apart from being untested and a bit 32you to do). Furthermore, details of the implementation might change freely
33feature-limited, it might already be useful). 33before version 1.0. And lastly, the object serialisation protocol depends
34on a pending IANA assignment, and until that assignment is official, this
35implementation is not interoperable with other implementations (even
36future versions of this module) until the assignment is done.
37
38You are still invited to try out CBOR, and this module.
34 39
35This module converts Perl data structures to the Concise Binary Object 40This module converts Perl data structures to the Concise Binary Object
36Representation (CBOR) and vice versa. CBOR is a fast binary serialisation 41Representation (CBOR) and vice versa. CBOR is a fast binary serialisation
37format that aims to use a superset of the JSON data model, i.e. when you 42format that aims to use a superset of the JSON data model, i.e. when you
38can represent something in JSON, you should be able to represent it in 43can represent something in JSON, you should be able to represent it in
39CBOR. 44CBOR.
40 45
41This makes it a faster and more compact binary alternative to JSON, with 46In short, CBOR is a faster and very compact binary alternative to JSON,
42the added ability of supporting serialising of perl objects. 47with the added ability of supporting serialisation of Perl objects. (JSON
48often compresses better than CBOR though, so if you plan to compress the
49data later you might want to compare both formats first).
43 50
44The primary goal of this module is to be I<correct> and the secondary goal 51The primary goal of this module is to be I<correct> and the secondary goal
45is to be I<fast>. To reach the latter goal it was written in C. 52is to be I<fast>. To reach the latter goal it was written in C.
46 53
47See MAPPING, below, on how CBOR::XS maps perl values to CBOR values and 54See MAPPING, below, on how CBOR::XS maps perl values to CBOR values and
… …
51 58
52package CBOR::XS; 59package CBOR::XS;
53 60
54use common::sense; 61use common::sense;
55 62
56our $VERSION = 0.03; 63our $VERSION = 0.05;
57our @ISA = qw(Exporter); 64our @ISA = qw(Exporter);
58 65
59our @EXPORT = qw(encode_cbor decode_cbor); 66our @EXPORT = qw(encode_cbor decode_cbor);
60 67
61use Exporter; 68use Exporter;
… …
221C<1> and C<0> (for true and false) or to throw an exception on access (for 228C<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. 229error). See the L<Types::Serialiser> manpage for details.
223 230
224=item CBOR tag 256 (perl object) 231=item CBOR tag 256 (perl object)
225 232
226The tag value C<256> (TODO: pending iana registration) will be used to 233The tag value C<256> (TODO: pending iana registration) will be used
227deserialise a Perl object. 234to deserialise a Perl object serialised with C<FREEZE>. See L<OBJECT
228 235SERIALISATION>, 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 236
237=item CBOR tag 55799 (magic header) 237=item CBOR tag 55799 (magic header)
238 238
239The tag 55799 is ignored (this tag implements the magic header). 239The tag 55799 is ignored (this tag implements the magic header).
240 240
… …
292 292
293These special values become CBOR true, CBOR false and CBOR undefined 293These special values become CBOR true, CBOR false and CBOR undefined
294values, respectively. You can also use C<\1>, C<\0> and C<\undef> directly 294values, respectively. You can also use C<\1>, C<\0> and C<\undef> directly
295if you want. 295if you want.
296 296
297=item blessed objects 297=item other blessed objects
298 298
299Other blessed objects currently need to have a C<TO_CBOR> method. It 299Other 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 300L<OBJECT SERIALISATION>, below, for details.
301something that can be encoded in CBOR.
302 301
303=item simple scalars 302=item simple scalars
304 303
305TODO 304TODO
306Simple Perl scalars (any scalar that is not a reference) are the most 305Simple Perl scalars (any scalar that is not a reference) are the most
… …
344represent numerical values are supported, but might suffer loss of 343represent numerical values are supported, but might suffer loss of
345precision. 344precision.
346 345
347=back 346=back
348 347
348=head2 OBJECT SERIALISATION
349 349
350This module knows two way to serialise a Perl object: The CBOR-specific
351way, and the generic way.
352
353Whenever the encoder encounters a Perl object that it cnanot serialise
354directly (most of them), it will first look up the C<TO_CBOR> method on
355it.
356
357If it has a C<TO_CBOR> method, it will call it with the object as only
358argument, and expects exactly one return value, which it will then
359substitute and encode it in the place of the object.
360
361Otherwise, it will look up the C<FREEZE> method. If it exists, it will
362call it with the object as first argument, and the constant string C<CBOR>
363as the second argument, to distinguish it from other serialisers.
364
365The C<FREEZE> method can return any number of values (i.e. zero or
366more). These will be encoded as CBOR perl object, together with the
367classname.
368
369If an object supports neither C<TO_CBOR> nor C<FREEZE>, encoding will fail
370with an error.
371
372Objects encoded via C<TO_CBOR> cannot be automatically decoded, but
373objects encoded via C<FREEZE> can be decoded using the following protocol:
374
375When an encoded CBOR perl object is encountered by the decoder, it will
376look up the C<THAW> method, by using the stored classname, and will fail
377if the method cannot be found.
378
379After the lookup it will call the C<THAW> method with the stored classname
380as first argument, the constant string C<CBOR> as second argument, and all
381values returned by C<FREEZE> as remaining arguments.
382
383=head4 EXAMPLES
384
385Here is an example C<TO_CBOR> method:
386
387 sub My::Object::TO_CBOR {
388 my ($obj) = @_;
389
390 ["this is a serialised My::Object object", $obj->{id}]
391 }
392
393When a C<My::Object> is encoded to CBOR, it will instead encode a simple
394array with two members: a string, and the "object id". Decoding this CBOR
395string will yield a normal perl array reference in place of the object.
396
397A more useful and practical example would be a serialisation method for
398the URI module. CBOR has a custom tag value for URIs, namely 32:
399
400 sub URI::TO_CBOR {
401 my ($self) = @_;
402 my $uri = "$self"; # stringify uri
403 utf8::upgrade $uri; # make sure it will be encoded as UTF-8 string
404 CBOR::XS::tagged 32, "$_[0]"
405 }
406
407This will encode URIs as a UTF-8 string with tag 32, which indicates an
408URI.
409
410Decoding such an URI will not (currently) give you an URI object, but
411instead a CBOR::XS::Tagged object with tag number 32 and the string -
412exactly what was returned by C<TO_CBOR>.
413
414To serialise an object so it can automatically be deserialised, you need
415to use C<FREEZE> and C<THAW>. To take the URI module as example, this
416would be a possible implementation:
417
418 sub URI::FREEZE {
419 my ($self, $serialiser) = @_;
420 "$self" # encode url string
421 }
422
423 sub URI::THAW {
424 my ($class, $serialiser, $uri) = @_;
425
426 $class->new ($uri)
427 }
428
429Unlike C<TO_CBOR>, multiple values can be returned by C<FREEZE>. For
430example, a C<FREEZE> method that returns "type", "id" and "variant" values
431would cause an invocation of C<THAW> with 5 arguments:
432
433 sub My::Object::FREEZE {
434 my ($self, $serialiser) = @_;
435
436 ($self->{type}, $self->{id}, $self->{variant})
437 }
438
439 sub My::Object::THAW {
440 my ($class, $serialiser, $type, $id, $variant) = @_;
441
442 $class-<new (type => $type, id => $id, variant => $variant)
443 }
444
445
350=head2 MAGIC HEADER 446=head1 MAGIC HEADER
351 447
352There is no way to distinguish CBOR from other formats 448There is no way to distinguish CBOR from other formats
353programmatically. To make it easier to distinguish CBOR from other 449programmatically. To make it easier to distinguish CBOR from other
354formats, the CBOR specification has a special "magic string" that can be 450formats, the CBOR specification has a special "magic string" that can be
355prepended to any CBOR string without changing it's meaning. 451prepended to any CBOR string without changing it's meaning.
… …
358prepend this string tot he CBOR data it generates, but it will ignroe it 454prepend 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 455if present, so users can prepend this string as a "file type" indicator as
360required. 456required.
361 457
362 458
363=head2 CBOR and JSON 459=head1 CBOR and JSON
364 460
365CBOR is supposed to implement a superset of the JSON data model, and is, 461CBOR 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 462with some coercion, able to represent all JSON texts (something that other
367"binary JSON" formats such as BSON generally do not support). 463"binary JSON" formats such as BSON generally do not support).
368 464

Diff Legend

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