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.5 by root, Sat Oct 26 23:02:55 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 31WARNING! This module is very new, and not very well tested (that's up to
22AND EAT YOUR CHILDREN! (Actually, apart from being untested and a bit 32you to do). Furthermore, details of the implementation might change freely
23feature-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.
24 39
25This module converts Perl data structures to the Concise Binary Object 40This module converts Perl data structures to the Concise Binary Object
26Representation (CBOR) and vice versa. CBOR is a fast binary serialisation 41Representation (CBOR) and vice versa. CBOR is a fast binary serialisation
27format 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
28can 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
29CBOR. 44CBOR.
30 45
31This makes it a faster and more compact binary alternative to JSON. 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).
32 50
33The 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
34is 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.
35 53
36See 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
… …
40 58
41package CBOR::XS; 59package CBOR::XS;
42 60
43use common::sense; 61use common::sense;
44 62
45our $VERSION = 0.03; 63our $VERSION = 0.05;
46our @ISA = qw(Exporter); 64our @ISA = qw(Exporter);
47 65
48our @EXPORT = qw(encode_cbor decode_cbor); 66our @EXPORT = qw(encode_cbor decode_cbor);
49 67
50use Exporter; 68use Exporter;
51use XSLoader; 69use XSLoader;
70
71use Types::Serialiser;
52 72
53our $MAGIC = "\xd9\xd9\xf7"; 73our $MAGIC = "\xd9\xd9\xf7";
54 74
55=head1 FUNCTIONAL INTERFACE 75=head1 FUNCTIONAL INTERFACE
56 76
… …
194 214
195CBOR 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
196array or hash, respectively. The keys of the map will be stringified 216array or hash, respectively. The keys of the map will be stringified
197during this process. 217during this process.
198 218
219=item null
220
221CBOR null becomes C<undef> in Perl.
222
199=item true, false 223=item true, false, undefined
200 224
201These 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>,
202respectively. They are overloaded to act almost exactly like the numbers 227respectively. They are overloaded to act almost exactly like the numbers
203C<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
204the C<CBOR::XS::is_bool> function. 229error). See the L<Types::Serialiser> manpage for details.
205 230
206=item null, undefined 231=item CBOR tag 256 (perl object)
207 232
208CBOR null and undefined values becomes C<undef> in Perl (in the future, 233The tag value C<256> (TODO: pending iana registration) will be used
209Undefined may raise an exception or something else). 234to deserialise a Perl object serialised with C<FREEZE>. See L<OBJECT
235SERIALISATION>, below, for details.
210 236
211=item tags 237=item CBOR tag 55799 (magic header)
212 238
239The tag 55799 is ignored (this tag implements the magic header).
240
241=item other CBOR tags
242
213Tagged 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
21455799 is ignored (this tag implements the magic header). 244handled internally are currently converted into a L<CBOR::XS::Tagged>
215
216All other tags are currently converted into a L<CBOR::XS::Tagged> object,
217which is simply a blessed array reference consistsing of the numeric tag 245object, which is simply a blessed array reference consisting of the
218value 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.
219 249
220=item anything else 250=item anything else
221 251
222Anything else (e.g. unsupported simple values) will raise a decoding 252Anything else (e.g. unsupported simple values) will raise a decoding
223error. 253error.
… …
256 286
257Objects 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]>
258pair. 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
259encoded as appropriate for the value. 289encoded as appropriate for the value.
260 290
261=item CBOR::XS::true, CBOR::XS::false 291=item Types::Serialiser::true, Types::Serialiser::false, Types::Serialiser::error
262 292
263These special values become CBOR true and CBOR false values, 293These special values become CBOR true, CBOR false and CBOR undefined
264respectively. 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.
265 296
266=item blessed objects 297=item other blessed objects
267 298
268Other 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
269will be called on every object that is being serialised, and must return 300L<OBJECT SERIALISATION>, below, for details.
270something that can be encoded in CBOR.
271 301
272=item simple scalars 302=item simple scalars
273 303
274TODO 304TODO
275Simple 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
… …
313represent numerical values are supported, but might suffer loss of 343represent numerical values are supported, but might suffer loss of
314precision. 344precision.
315 345
316=back 346=back
317 347
348=head2 OBJECT SERIALISATION
318 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
319=head2 MAGIC HEADER 446=head1 MAGIC HEADER
320 447
321There is no way to distinguish CBOR from other formats 448There is no way to distinguish CBOR from other formats
322programmatically. To make it easier to distinguish CBOR from other 449programmatically. To make it easier to distinguish CBOR from other
323formats, the CBOR specification has a special "magic string" that can be 450formats, the CBOR specification has a special "magic string" that can be
324prepended to any CBOR string without changing it's meaning. 451prepended to any CBOR string without changing it's meaning.
… …
327prepend 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
328if 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
329required. 456required.
330 457
331 458
332=head2 CBOR and JSON 459=head1 CBOR and JSON
333 460
334CBOR 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,
335with some coercion, able to represent all JSON texts (something that other 462with some coercion, able to represent all JSON texts (something that other
336"binary JSON" formats such as BSON generally do not support). 463"binary JSON" formats such as BSON generally do not support).
337 464
… …
417Please refrain from using rt.cpan.org or any other bug reporting 544Please refrain from using rt.cpan.org or any other bug reporting
418service. I put the contact address into my modules for a reason. 545service. I put the contact address into my modules for a reason.
419 546
420=cut 547=cut
421 548
422our $true = do { bless \(my $dummy = 1), "CBOR::XS::Boolean" };
423our $false = do { bless \(my $dummy = 0), "CBOR::XS::Boolean" };
424
425sub true() { $true }
426sub false() { $false }
427
428sub is_bool($) {
429 UNIVERSAL::isa $_[0], "CBOR::XS::Boolean"
430# or UNIVERSAL::isa $_[0], "CBOR::Literal"
431}
432
433XSLoader::load "CBOR::XS", $VERSION; 549XSLoader::load "CBOR::XS", $VERSION;
434
435package CBOR::XS::Boolean;
436
437use overload
438 "0+" => sub { ${$_[0]} },
439 "++" => sub { $_[0] = ${$_[0]} + 1 },
440 "--" => sub { $_[0] = ${$_[0]} - 1 },
441 fallback => 1;
442
4431;
444 550
445=head1 SEE ALSO 551=head1 SEE ALSO
446 552
447The 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,
448serialisation. 554serialisation.
449 555
556The L<Types::Serialiser> module provides the data model for true, false
557and error values.
558
450=head1 AUTHOR 559=head1 AUTHOR
451 560
452 Marc Lehmann <schmorp@schmorp.de> 561 Marc Lehmann <schmorp@schmorp.de>
453 http://home.schmorp.de/ 562 http://home.schmorp.de/
454 563
455=cut 564=cut
456 565
5661
567

Diff Legend

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