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.7 by root, Sun Oct 27 22:35:15 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 IS A PRE-ALPHA RELEASE! IT WILL CRASH, CORRUPT YOUR DATA
22EAT YOUR CHILDREN! 32AND EAT YOUR CHILDREN! (Actually, apart from being untested and a bit
33feature-limited, it might already be useful).
23 34
24This module converts Perl data structures to CBOR and vice versa. Its 35This module converts Perl data structures to the Concise Binary Object
36Representation (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
38can represent something in JSON, you should be able to represent it in
39CBOR.
40
41This makes it a faster and more compact binary alternative to JSON, with
42the added ability of supporting serialising of perl objects.
43
25primary goal is to be I<correct> and its secondary goal is to be 44The 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. 45is to be I<fast>. To reach the latter goal it was written in C.
27 46
28See MAPPING, below, on how CBOR::XS maps perl values to CBOR values and 47See MAPPING, below, on how CBOR::XS maps perl values to CBOR values and
29vice versa. 48vice versa.
30 49
31=cut 50=cut
32 51
33package CBOR::XS; 52package CBOR::XS;
34 53
35use common::sense; 54use common::sense;
36 55
37our $VERSION = 0.02; 56our $VERSION = 0.03;
38our @ISA = qw(Exporter); 57our @ISA = qw(Exporter);
39 58
40our @EXPORT = qw(encode_cbor decode_cbor); 59our @EXPORT = qw(encode_cbor decode_cbor);
41 60
42use Exporter; 61use Exporter;
43use XSLoader; 62use XSLoader;
63
64use Types::Serialiser;
44 65
45our $MAGIC = "\xd9\xd9\xf7"; 66our $MAGIC = "\xd9\xd9\xf7";
46 67
47=head1 FUNCTIONAL INTERFACE 68=head1 FUNCTIONAL INTERFACE
48 69
… …
186 207
187CBOR arrays and CBOR maps will be converted into references to a Perl 208CBOR arrays and CBOR maps will be converted into references to a Perl
188array or hash, respectively. The keys of the map will be stringified 209array or hash, respectively. The keys of the map will be stringified
189during this process. 210during this process.
190 211
212=item null
213
214CBOR null becomes C<undef> in Perl.
215
191=item true, false 216=item true, false, undefined
192 217
193These CBOR values become C<CBOR::XS::true> and C<CBOR::XS::false>, 218These CBOR values become C<Types:Serialiser::true>,
219C<Types:Serialiser::false> and C<Types::Serialiser::error>,
194respectively. They are overloaded to act almost exactly like the numbers 220respectively. 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 221C<1> and C<0> (for true and false) or to throw an exception on access (for
196the C<CBOR::XS::is_bool> function. 222error). See the L<Types::Serialiser> manpage for details.
197 223
198=item null, undefined 224=item CBOR tag 256 (perl object)
199 225
200CBOR null and undefined values becomes C<undef> in Perl (in the future, 226The tag value C<256> (TODO: pending iana registration) will be used
201Undefined may raise an exception or something else). 227to deserialise a Perl object serialised with C<FREEZE>. See "OBJECT
228SERIALISATION", below, for details.
202 229
203=item tags 230=item CBOR tag 55799 (magic header)
204 231
232The tag 55799 is ignored (this tag implements the magic header).
233
234=item other CBOR tags
235
205Tagged items consists of a numeric tag and another CBOR value. The tag 236Tagged items consists of a numeric tag and another CBOR value. Tags not
20655799 is ignored (this tag implements the magic header). 237handled 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 238object, which is simply a blessed array reference consisting of the
210value followed by the (decoded) BOR value. 239numeric tag value followed by the (decoded) CBOR value.
240
241In the future, support for user-supplied conversions might get added.
211 242
212=item anything else 243=item anything else
213 244
214Anything else (e.g. unsupported simple values) will raise a decoding 245Anything else (e.g. unsupported simple values) will raise a decoding
215error. 246error.
… …
248 279
249Objects of this type must be arrays consisting of a single C<[tag, value]> 280Objects 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 281pair. The (numerical) tag will be encoded as a CBOR tag, the value will be
251encoded as appropriate for the value. 282encoded as appropriate for the value.
252 283
253=item CBOR::XS::true, CBOR::XS::false 284=item Types::Serialiser::true, Types::Serialiser::false, Types::Serialiser::error
254 285
255These special values become CBOR true and CBOR false values, 286These special values become CBOR true, CBOR false and CBOR undefined
256respectively. You can also use C<\1> and C<\0> directly if you want. 287values, respectively. You can also use C<\1>, C<\0> and C<\undef> directly
288if you want.
257 289
258=item blessed objects 290=item other blessed objects
259 291
260Other 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
261will be called on every object that is being serialised, and must return 293"OBJECT SERIALISATION", below, for details.
262something that can be encoded in CBOR.
263 294
264=item simple scalars 295=item simple scalars
265 296
266TODO 297TODO
267Simple 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
… …
305represent numerical values are supported, but might suffer loss of 336represent numerical values are supported, but might suffer loss of
306precision. 337precision.
307 338
308=back 339=back
309 340
341=head2 OBJECT SERIALISATION
310 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
311=head2 MAGIC HEADER 439=head1 MAGIC HEADER
312 440
313There is no way to distinguish CBOR from other formats 441There is no way to distinguish CBOR from other formats
314programmatically. To make it easier to distinguish CBOR from other 442programmatically. To make it easier to distinguish CBOR from other
315formats, the CBOR specification has a special "magic string" that can be 443formats, the CBOR specification has a special "magic string" that can be
316prepended to any CBOR string without changing it's meaning. 444prepended to any CBOR string without changing it's meaning.
… …
319prepend 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
320if 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
321required. 449required.
322 450
323 451
324=head2 CBOR and JSON 452=head1 CBOR and JSON
325 453
326CBOR 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,
327with some coercion, able to represent all JSON texts (something that other 455with some coercion, able to represent all JSON texts (something that other
328"binary JSON" formats such as BSON generally do not support). 456"binary JSON" formats such as BSON generally do not support).
329 457
… …
409Please refrain from using rt.cpan.org or any other bug reporting 537Please refrain from using rt.cpan.org or any other bug reporting
410service. I put the contact address into my modules for a reason. 538service. I put the contact address into my modules for a reason.
411 539
412=cut 540=cut
413 541
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; 542XSLoader::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 543
437=head1 SEE ALSO 544=head1 SEE ALSO
438 545
439The L<JSON> and L<JSON::XS> modules that do similar, but human-readable, 546The L<JSON> and L<JSON::XS> modules that do similar, but human-readable,
440serialisation. 547serialisation.
441 548
549The L<Types::Serialiser> module provides the data model for true, false
550and error values.
551
442=head1 AUTHOR 552=head1 AUTHOR
443 553
444 Marc Lehmann <schmorp@schmorp.de> 554 Marc Lehmann <schmorp@schmorp.de>
445 http://home.schmorp.de/ 555 http://home.schmorp.de/
446 556
447=cut 557=cut
448 558
5591
560

Diff Legend

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