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.4 by root, Sat Oct 26 22:25:47 2013 UTC vs.
Revision 1.11 by root, Tue Oct 29 00:20:26 2013 UTC

… …
12 $perl_value = decode_cbor $binary_cbor_data; 12 $perl_value = decode_cbor $binary_cbor_data;
13 13
14 # OO-interface 14 # OO-interface
15 15
16 $coder = CBOR::XS->new; 16 $coder = CBOR::XS->new;
17 #TODO 17 $binary_cbor_data = $coder->encode ($perl_value);
18 $perl_value = $coder->decode ($binary_cbor_data);
19
20 # prefix decoding
21
22 my $many_cbor_strings = ...;
23 while (length $many_cbor_strings) {
24 my ($data, $length) = $cbor->decode_prefix ($many_cbor_strings);
25 # data was decoded
26 substr $many_cbor_strings, 0, $length, ""; # remove decoded cbor string
27 }
18 28
19=head1 DESCRIPTION 29=head1 DESCRIPTION
20 30
21WARNING! THIS IS A PRE-ALPHA RELEASE! IT WILL CRASH, CORRUPT YOUR DATA AND 31WARNING! This module is very new, and not very well tested (that's up to
22EAT YOUR CHILDREN! 32you to do). Furthermore, details of the implementation might change freely
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.
23 37
24This module converts Perl data structures to CBOR and vice versa. Its 38You are still invited to try out CBOR, and this module.
39
40This module converts Perl data structures to the Concise Binary Object
41Representation (CBOR) and vice versa. CBOR is a fast binary serialisation
42format that aims to use a superset of the JSON data model, i.e. when you
43can represent something in JSON, you should be able to represent it in
44CBOR.
45
46In short, CBOR is a faster and very compact binary alternative to JSON,
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).
50
25primary goal is to be I<correct> and its secondary goal is to be 51The primary goal of this module is to be I<correct> and the secondary goal
26I<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.
27 53
28See 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
29vice versa. 55vice versa.
30 56
31=cut 57=cut
32 58
33package CBOR::XS; 59package CBOR::XS;
34 60
35use common::sense; 61use common::sense;
36 62
37our $VERSION = 0.02; 63our $VERSION = 0.05;
38our @ISA = qw(Exporter); 64our @ISA = qw(Exporter);
39 65
40our @EXPORT = qw(encode_cbor decode_cbor); 66our @EXPORT = qw(encode_cbor decode_cbor);
41 67
42use Exporter; 68use Exporter;
43use XSLoader; 69use XSLoader;
70
71use Types::Serialiser;
44 72
45our $MAGIC = "\xd9\xd9\xf7"; 73our $MAGIC = "\xd9\xd9\xf7";
46 74
47=head1 FUNCTIONAL INTERFACE 75=head1 FUNCTIONAL INTERFACE
48 76
… …
186 214
187CBOR arrays and CBOR maps will be converted into references to a Perl 215CBOR arrays and CBOR maps will be converted into references to a Perl
188array or hash, respectively. The keys of the map will be stringified 216array or hash, respectively. The keys of the map will be stringified
189during this process. 217during this process.
190 218
219=item null
220
221CBOR null becomes C<undef> in Perl.
222
191=item true, false 223=item true, false, undefined
192 224
193These CBOR values become C<CBOR::XS::true> and C<CBOR::XS::false>, 225These CBOR values become C<Types:Serialiser::true>,
226C<Types:Serialiser::false> and C<Types::Serialiser::error>,
194respectively. They are overloaded to act almost exactly like the numbers 227respectively. They are overloaded to act almost exactly like the numbers
195C<1> and C<0>. You can check whether a scalar is a CBOR boolean by using 228C<1> and C<0> (for true and false) or to throw an exception on access (for
196the C<CBOR::XS::is_bool> function. 229error). See the L<Types::Serialiser> manpage for details.
197 230
198=item null, undefined 231=item CBOR tag 256 (perl object)
199 232
200CBOR null and undefined values becomes C<undef> in Perl (in the future, 233The tag value C<256> (TODO: pending iana registration) will be used
201Undefined may raise an exception or something else). 234to deserialise a Perl object serialised with C<FREEZE>. See L<OBJECT
235SERIALISATION>, below, for details.
202 236
203=item tags 237=item CBOR tag 55799 (magic header)
204 238
239The tag 55799 is ignored (this tag implements the magic header).
240
241=item other CBOR tags
242
205Tagged items consists of a numeric tag and another CBOR value. The tag 243Tagged items consists of a numeric tag and another CBOR value. Tags not
20655799 is ignored (this tag implements the magic header). 244handled internally are currently converted into a L<CBOR::XS::Tagged>
207
208All other tags are currently converted into a L<CBOR::XS::Tagged> object,
209which is simply a blessed array reference consistsing of the numeric tag 245object, which is simply a blessed array reference consisting of the
210value followed by the (decoded) BOR value. 246numeric tag value followed by the (decoded) CBOR value.
247
248In the future, support for user-supplied conversions might get added.
211 249
212=item anything else 250=item anything else
213 251
214Anything else (e.g. unsupported simple values) will raise a decoding 252Anything else (e.g. unsupported simple values) will raise a decoding
215error. 253error.
… …
248 286
249Objects of this type must be arrays consisting of a single C<[tag, value]> 287Objects of this type must be arrays consisting of a single C<[tag, value]>
250pair. The (numerical) tag will be encoded as a CBOR tag, the value will be 288pair. The (numerical) tag will be encoded as a CBOR tag, the value will be
251encoded as appropriate for the value. 289encoded as appropriate for the value.
252 290
253=item CBOR::XS::true, CBOR::XS::false 291=item Types::Serialiser::true, Types::Serialiser::false, Types::Serialiser::error
254 292
255These special values become CBOR true and CBOR false values, 293These special values become CBOR true, CBOR false and CBOR undefined
256respectively. You can also use C<\1> and C<\0> directly if you want. 294values, respectively. You can also use C<\1>, C<\0> and C<\undef> directly
295if you want.
257 296
258=item blessed objects 297=item other blessed objects
259 298
260Other 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
261will be called on every object that is being serialised, and must return 300L<OBJECT SERIALISATION>, below, for details.
262something that can be encoded in CBOR.
263 301
264=item simple scalars 302=item simple scalars
265 303
266TODO 304TODO
267Simple 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
… …
305represent numerical values are supported, but might suffer loss of 343represent numerical values are supported, but might suffer loss of
306precision. 344precision.
307 345
308=back 346=back
309 347
348=head2 OBJECT SERIALISATION
310 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
311=head2 MAGIC HEADER 446=head1 MAGIC HEADER
312 447
313There is no way to distinguish CBOR from other formats 448There is no way to distinguish CBOR from other formats
314programmatically. To make it easier to distinguish CBOR from other 449programmatically. To make it easier to distinguish CBOR from other
315formats, the CBOR specification has a special "magic string" that can be 450formats, the CBOR specification has a special "magic string" that can be
316prepended to any CBOR string without changing it's meaning. 451prepended to any CBOR string without changing it's meaning.
… …
319prepend 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
320if 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
321required. 456required.
322 457
323 458
324=head2 CBOR and JSON 459=head1 CBOR and JSON
325 460
326CBOR 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,
327with some coercion, able to represent all JSON texts (something that other 462with some coercion, able to represent all JSON texts (something that other
328"binary JSON" formats such as BSON generally do not support). 463"binary JSON" formats such as BSON generally do not support).
329 464
… …
409Please refrain from using rt.cpan.org or any other bug reporting 544Please refrain from using rt.cpan.org or any other bug reporting
410service. I put the contact address into my modules for a reason. 545service. I put the contact address into my modules for a reason.
411 546
412=cut 547=cut
413 548
414our $true = do { bless \(my $dummy = 1), "CBOR::XS::Boolean" };
415our $false = do { bless \(my $dummy = 0), "CBOR::XS::Boolean" };
416
417sub true() { $true }
418sub false() { $false }
419
420sub is_bool($) {
421 UNIVERSAL::isa $_[0], "CBOR::XS::Boolean"
422# or UNIVERSAL::isa $_[0], "CBOR::Literal"
423}
424
425XSLoader::load "CBOR::XS", $VERSION; 549XSLoader::load "CBOR::XS", $VERSION;
426
427package CBOR::XS::Boolean;
428
429use overload
430 "0+" => sub { ${$_[0]} },
431 "++" => sub { $_[0] = ${$_[0]} + 1 },
432 "--" => sub { $_[0] = ${$_[0]} - 1 },
433 fallback => 1;
434
4351;
436 550
437=head1 SEE ALSO 551=head1 SEE ALSO
438 552
439The L<JSON> and L<JSON::XS> modules that do similar, but human-readable, 553The L<JSON> and L<JSON::XS> modules that do similar, but human-readable,
440serialisation. 554serialisation.
441 555
556The L<Types::Serialiser> module provides the data model for true, false
557and error values.
558
442=head1 AUTHOR 559=head1 AUTHOR
443 560
444 Marc Lehmann <schmorp@schmorp.de> 561 Marc Lehmann <schmorp@schmorp.de>
445 http://home.schmorp.de/ 562 http://home.schmorp.de/
446 563
447=cut 564=cut
448 565
5661
567

Diff Legend

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