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

Diff Legend

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