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

Diff Legend

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