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.9 by root, Mon Oct 28 21:28:14 2013 UTC vs.
Revision 1.17 by root, Wed Oct 30 10:11:04 2013 UTC

… …
42format 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
43can 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
44CBOR. 44CBOR.
45 45
46In short, CBOR is a faster and very 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. 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
51To give you a general idea about speed, with texts in the megabyte range,
52C<CBOR::XS> usually encodes roughly twice as fast as L<Storable> or
53L<JSON::XS> and decodes about 15%-30% faster than those. The shorter the
54data, the worse L<Storable> performs in comparison.
55
56As for compactness, C<CBOR::XS> encoded data structures are usually about
5720% smaller than the same data encoded as (compact) JSON or L<Storable>.
48 58
49The primary goal of this module is to be I<correct> and the secondary goal 59The primary goal of this module is to be I<correct> and the secondary goal
50is to be I<fast>. To reach the latter goal it was written in C. 60is to be I<fast>. To reach the latter goal it was written in C.
51 61
52See MAPPING, below, on how CBOR::XS maps perl values to CBOR values and 62See MAPPING, below, on how CBOR::XS maps perl values to CBOR values and
… …
56 66
57package CBOR::XS; 67package CBOR::XS;
58 68
59use common::sense; 69use common::sense;
60 70
61our $VERSION = 0.05; 71our $VERSION = 0.08;
62our @ISA = qw(Exporter); 72our @ISA = qw(Exporter);
63 73
64our @EXPORT = qw(encode_cbor decode_cbor); 74our @EXPORT = qw(encode_cbor decode_cbor);
65 75
66use Exporter; 76use Exporter;
… …
227error). See the L<Types::Serialiser> manpage for details. 237error). See the L<Types::Serialiser> manpage for details.
228 238
229=item CBOR tag 256 (perl object) 239=item CBOR tag 256 (perl object)
230 240
231The tag value C<256> (TODO: pending iana registration) will be used 241The tag value C<256> (TODO: pending iana registration) will be used
232to deserialise a Perl object serialised with C<FREEZE>. See "OBJECT 242to deserialise a Perl object serialised with C<FREEZE>. See L<OBJECT
233SERIALISATION", below, for details. 243SERIALISATION>, below, for details.
234 244
235=item CBOR tag 55799 (magic header) 245=item CBOR tag 55799 (magic header)
236 246
237The tag 55799 is ignored (this tag implements the magic header). 247The tag 55799 is ignored (this tag implements the magic header).
238 248
… …
281C<1>, which get turned into false and true in CBOR. 291C<1>, which get turned into false and true in CBOR.
282 292
283=item CBOR::XS::Tagged objects 293=item CBOR::XS::Tagged objects
284 294
285Objects of this type must be arrays consisting of a single C<[tag, value]> 295Objects of this type must be arrays consisting of a single C<[tag, value]>
286pair. The (numerical) tag will be encoded as a CBOR tag, the value will be 296pair. The (numerical) tag will be encoded as a CBOR tag, the value will
287encoded as appropriate for the value. 297be encoded as appropriate for the value. You cna use C<CBOR::XS::tag> to
298create such objects.
288 299
289=item Types::Serialiser::true, Types::Serialiser::false, Types::Serialiser::error 300=item Types::Serialiser::true, Types::Serialiser::false, Types::Serialiser::error
290 301
291These special values become CBOR true, CBOR false and CBOR undefined 302These special values become CBOR true, CBOR false and CBOR undefined
292values, respectively. You can also use C<\1>, C<\0> and C<\undef> directly 303values, respectively. You can also use C<\1>, C<\0> and C<\undef> directly
293if you want. 304if you want.
294 305
295=item other blessed objects 306=item other blessed objects
296 307
297Other blessed objects are serialised via C<TO_CBOR> or C<FREEZE>. See 308Other blessed objects are serialised via C<TO_CBOR> or C<FREEZE>. See
298"OBJECT SERIALISATION", below, for details. 309L<OBJECT SERIALISATION>, below, for details.
299 310
300=item simple scalars 311=item simple scalars
301 312
302TODO 313TODO
303Simple Perl scalars (any scalar that is not a reference) are the most 314Simple Perl scalars (any scalar that is not a reference) are the most
… …
451This string is available as C<$CBOR::XS::MAGIC>. This module does not 462This string is available as C<$CBOR::XS::MAGIC>. This module does not
452prepend this string tot he CBOR data it generates, but it will ignroe it 463prepend this string tot he CBOR data it generates, but it will ignroe it
453if present, so users can prepend this string as a "file type" indicator as 464if present, so users can prepend this string as a "file type" indicator as
454required. 465required.
455 466
467
468=head1 THE CBOR::XS::Tagged CLASS
469
470CBOR has the concept of tagged values - any CBOR value can be tagged with
471a numeric 64 bit number, which are centrally administered.
472
473C<CBOR::XS> handles a few tags internally when en- or decoding. You can
474also create tags yourself by encoding C<CBOR::XS::Tagged> objects, and the
475decoder will create C<CBOR::XS::Tagged> objects itself when it hits an
476unknown tag.
477
478These objects are simply blessed array references - the first member of
479the array being the numerical tag, the second being the value.
480
481You can interact with C<CBOR::XS::Tagged> objects in the following ways:
482
483=over 4
484
485=item $tagged = CBOR::XS::tag $tag, $value
486
487This function(!) creates a new C<CBOR::XS::Tagged> object using the given
488C<$tag> (0..2**64-1) to tag the given C<$value> (which can be any Perl
489value that can be encoded in CBOR, including serialisable Perl objects and
490C<CBOR::XS::Tagged> objects).
491
492=item $tagged->[0]
493
494=item $tagged->[0] = $new_tag
495
496=item $tag = $tagged->tag
497
498=item $new_tag = $tagged->tag ($new_tag)
499
500Access/mutate the tag.
501
502=item $tagged->[1]
503
504=item $tagged->[1] = $new_value
505
506=item $value = $tagged->value
507
508=item $new_value = $tagged->value ($new_value)
509
510Access/mutate the tagged value.
511
512=back
513
514=cut
515
516sub tag($$) {
517 bless [@_], CBOR::XS::Tagged::;
518}
519
520sub CBOR::XS::Tagged::tag {
521 $_[0][0] = $_[1] if $#_;
522 $_[0][0]
523}
524
525sub CBOR::XS::Tagged::value {
526 $_[0][1] = $_[1] if $#_;
527 $_[0][1]
528}
529
530=head2 EXAMPLES
531
532Here are some examples of C<CBOR::XS::Tagged> uses to tag objects.
533
534You can look up CBOR tag value and emanings in the IANA registry at
535L<http://www.iana.org/assignments/cbor-tags/cbor-tags.xhtml>.
536
537Prepend a magic header (C<$CBOR::XS::MAGIC>):
538
539 my $cbor = encode_cbor CBOR::XS::tag 55799, $value;
540 # same as:
541 my $cbor = $CBOR::XS::MAGIC . encode_cbor $value;
542
543Serialise some URIs and a regex in an array:
544
545 my $cbor = encode_cbor [
546 (CBOR::XS::tag 32, "http://www.nethype.de/"),
547 (CBOR::XS::tag 32, "http://software.schmorp.de/"),
548 (CBOR::XS::tag 35, "^[Pp][Ee][Rr][lL]\$"),
549 ];
550
551Wrap CBOR data in CBOR:
552
553 my $cbor_cbor = encode_cbor
554 CBOR::XS::tag 24,
555 encode_cbor [1, 2, 3];
456 556
457=head1 CBOR and JSON 557=head1 CBOR and JSON
458 558
459CBOR is supposed to implement a superset of the JSON data model, and is, 559CBOR is supposed to implement a superset of the JSON data model, and is,
460with some coercion, able to represent all JSON texts (something that other 560with some coercion, able to represent all JSON texts (something that other

Diff Legend

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