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.9 by root, Mon Oct 28 21:28:14 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.
48
25primary goal is to be I<correct> and its secondary goal is to be 49The 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. 50is to be I<fast>. To reach the latter goal it was written in C.
27 51
28See MAPPING, below, on how CBOR::XS maps perl values to CBOR values and 52See MAPPING, below, on how CBOR::XS maps perl values to CBOR values and
29vice versa. 53vice versa.
30 54
31=cut 55=cut
32 56
33package CBOR::XS; 57package CBOR::XS;
34 58
35use common::sense; 59use common::sense;
36 60
37our $VERSION = 0.02; 61our $VERSION = 0.05;
38our @ISA = qw(Exporter); 62our @ISA = qw(Exporter);
39 63
40our @EXPORT = qw(encode_cbor decode_cbor); 64our @EXPORT = qw(encode_cbor decode_cbor);
41 65
42use Exporter; 66use Exporter;
43use XSLoader; 67use XSLoader;
68
69use Types::Serialiser;
44 70
45our $MAGIC = "\xd9\xd9\xf7"; 71our $MAGIC = "\xd9\xd9\xf7";
46 72
47=head1 FUNCTIONAL INTERFACE 73=head1 FUNCTIONAL INTERFACE
48 74
… …
186 212
187CBOR arrays and CBOR maps will be converted into references to a Perl 213CBOR arrays and CBOR maps will be converted into references to a Perl
188array or hash, respectively. The keys of the map will be stringified 214array or hash, respectively. The keys of the map will be stringified
189during this process. 215during this process.
190 216
217=item null
218
219CBOR null becomes C<undef> in Perl.
220
191=item true, false 221=item true, false, undefined
192 222
193These CBOR values become C<CBOR::XS::true> and C<CBOR::XS::false>, 223These CBOR values become C<Types:Serialiser::true>,
224C<Types:Serialiser::false> and C<Types::Serialiser::error>,
194respectively. They are overloaded to act almost exactly like the numbers 225respectively. 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 226C<1> and C<0> (for true and false) or to throw an exception on access (for
196the C<CBOR::XS::is_bool> function. 227error). See the L<Types::Serialiser> manpage for details.
197 228
198=item null, undefined 229=item CBOR tag 256 (perl object)
199 230
200CBOR null and undefined values becomes C<undef> in Perl (in the future, 231The tag value C<256> (TODO: pending iana registration) will be used
201Undefined may raise an exception or something else). 232to deserialise a Perl object serialised with C<FREEZE>. See "OBJECT
233SERIALISATION", below, for details.
202 234
203=item tags 235=item CBOR tag 55799 (magic header)
204 236
237The tag 55799 is ignored (this tag implements the magic header).
238
239=item other CBOR tags
240
205Tagged items consists of a numeric tag and another CBOR value. The tag 241Tagged items consists of a numeric tag and another CBOR value. Tags not
20655799 is ignored (this tag implements the magic header). 242handled 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 243object, which is simply a blessed array reference consisting of the
210value followed by the (decoded) BOR value. 244numeric tag value followed by the (decoded) CBOR value.
245
246In the future, support for user-supplied conversions might get added.
211 247
212=item anything else 248=item anything else
213 249
214Anything else (e.g. unsupported simple values) will raise a decoding 250Anything else (e.g. unsupported simple values) will raise a decoding
215error. 251error.
… …
248 284
249Objects of this type must be arrays consisting of a single C<[tag, value]> 285Objects 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 286pair. The (numerical) tag will be encoded as a CBOR tag, the value will be
251encoded as appropriate for the value. 287encoded as appropriate for the value.
252 288
253=item CBOR::XS::true, CBOR::XS::false 289=item Types::Serialiser::true, Types::Serialiser::false, Types::Serialiser::error
254 290
255These special values become CBOR true and CBOR false values, 291These special values become CBOR true, CBOR false and CBOR undefined
256respectively. You can also use C<\1> and C<\0> directly if you want. 292values, respectively. You can also use C<\1>, C<\0> and C<\undef> directly
293if you want.
257 294
258=item blessed objects 295=item other blessed objects
259 296
260Other blessed objects currently need to have a C<TO_CBOR> method. It 297Other 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 298"OBJECT SERIALISATION", below, for details.
262something that can be encoded in CBOR.
263 299
264=item simple scalars 300=item simple scalars
265 301
266TODO 302TODO
267Simple Perl scalars (any scalar that is not a reference) are the most 303Simple Perl scalars (any scalar that is not a reference) are the most
… …
305represent numerical values are supported, but might suffer loss of 341represent numerical values are supported, but might suffer loss of
306precision. 342precision.
307 343
308=back 344=back
309 345
346=head2 OBJECT SERIALISATION
310 347
348This module knows two way to serialise a Perl object: The CBOR-specific
349way, and the generic way.
350
351Whenever the encoder encounters a Perl object that it cnanot serialise
352directly (most of them), it will first look up the C<TO_CBOR> method on
353it.
354
355If it has a C<TO_CBOR> method, it will call it with the object as only
356argument, and expects exactly one return value, which it will then
357substitute and encode it in the place of the object.
358
359Otherwise, it will look up the C<FREEZE> method. If it exists, it will
360call it with the object as first argument, and the constant string C<CBOR>
361as the second argument, to distinguish it from other serialisers.
362
363The C<FREEZE> method can return any number of values (i.e. zero or
364more). These will be encoded as CBOR perl object, together with the
365classname.
366
367If an object supports neither C<TO_CBOR> nor C<FREEZE>, encoding will fail
368with an error.
369
370Objects encoded via C<TO_CBOR> cannot be automatically decoded, but
371objects encoded via C<FREEZE> can be decoded using the following protocol:
372
373When an encoded CBOR perl object is encountered by the decoder, it will
374look up the C<THAW> method, by using the stored classname, and will fail
375if the method cannot be found.
376
377After the lookup it will call the C<THAW> method with the stored classname
378as first argument, the constant string C<CBOR> as second argument, and all
379values returned by C<FREEZE> as remaining arguments.
380
381=head4 EXAMPLES
382
383Here is an example C<TO_CBOR> method:
384
385 sub My::Object::TO_CBOR {
386 my ($obj) = @_;
387
388 ["this is a serialised My::Object object", $obj->{id}]
389 }
390
391When a C<My::Object> is encoded to CBOR, it will instead encode a simple
392array with two members: a string, and the "object id". Decoding this CBOR
393string will yield a normal perl array reference in place of the object.
394
395A more useful and practical example would be a serialisation method for
396the URI module. CBOR has a custom tag value for URIs, namely 32:
397
398 sub URI::TO_CBOR {
399 my ($self) = @_;
400 my $uri = "$self"; # stringify uri
401 utf8::upgrade $uri; # make sure it will be encoded as UTF-8 string
402 CBOR::XS::tagged 32, "$_[0]"
403 }
404
405This will encode URIs as a UTF-8 string with tag 32, which indicates an
406URI.
407
408Decoding such an URI will not (currently) give you an URI object, but
409instead a CBOR::XS::Tagged object with tag number 32 and the string -
410exactly what was returned by C<TO_CBOR>.
411
412To serialise an object so it can automatically be deserialised, you need
413to use C<FREEZE> and C<THAW>. To take the URI module as example, this
414would be a possible implementation:
415
416 sub URI::FREEZE {
417 my ($self, $serialiser) = @_;
418 "$self" # encode url string
419 }
420
421 sub URI::THAW {
422 my ($class, $serialiser, $uri) = @_;
423
424 $class->new ($uri)
425 }
426
427Unlike C<TO_CBOR>, multiple values can be returned by C<FREEZE>. For
428example, a C<FREEZE> method that returns "type", "id" and "variant" values
429would cause an invocation of C<THAW> with 5 arguments:
430
431 sub My::Object::FREEZE {
432 my ($self, $serialiser) = @_;
433
434 ($self->{type}, $self->{id}, $self->{variant})
435 }
436
437 sub My::Object::THAW {
438 my ($class, $serialiser, $type, $id, $variant) = @_;
439
440 $class-<new (type => $type, id => $id, variant => $variant)
441 }
442
443
311=head2 MAGIC HEADER 444=head1 MAGIC HEADER
312 445
313There is no way to distinguish CBOR from other formats 446There is no way to distinguish CBOR from other formats
314programmatically. To make it easier to distinguish CBOR from other 447programmatically. To make it easier to distinguish CBOR from other
315formats, the CBOR specification has a special "magic string" that can be 448formats, the CBOR specification has a special "magic string" that can be
316prepended to any CBOR string without changing it's meaning. 449prepended to any CBOR string without changing it's meaning.
… …
319prepend this string tot he CBOR data it generates, but it will ignroe it 452prepend 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 453if present, so users can prepend this string as a "file type" indicator as
321required. 454required.
322 455
323 456
324=head2 CBOR and JSON 457=head1 CBOR and JSON
325 458
326CBOR is supposed to implement a superset of the JSON data model, and is, 459CBOR 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 460with some coercion, able to represent all JSON texts (something that other
328"binary JSON" formats such as BSON generally do not support). 461"binary JSON" formats such as BSON generally do not support).
329 462
… …
409Please refrain from using rt.cpan.org or any other bug reporting 542Please refrain from using rt.cpan.org or any other bug reporting
410service. I put the contact address into my modules for a reason. 543service. I put the contact address into my modules for a reason.
411 544
412=cut 545=cut
413 546
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; 547XSLoader::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 548
437=head1 SEE ALSO 549=head1 SEE ALSO
438 550
439The L<JSON> and L<JSON::XS> modules that do similar, but human-readable, 551The L<JSON> and L<JSON::XS> modules that do similar, but human-readable,
440serialisation. 552serialisation.
441 553
554The L<Types::Serialiser> module provides the data model for true, false
555and error values.
556
442=head1 AUTHOR 557=head1 AUTHOR
443 558
444 Marc Lehmann <schmorp@schmorp.de> 559 Marc Lehmann <schmorp@schmorp.de>
445 http://home.schmorp.de/ 560 http://home.schmorp.de/
446 561
447=cut 562=cut
448 563
5641
565

Diff Legend

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