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.7 by root, Sun Oct 27 22:35:15 2013 UTC vs.
Revision 1.12 by root, Tue Oct 29 15:13:50 2013 UTC

… …
26 substr $many_cbor_strings, 0, $length, ""; # remove decoded cbor string 26 substr $many_cbor_strings, 0, $length, ""; # remove decoded cbor string
27 } 27 }
28 28
29=head1 DESCRIPTION 29=head1 DESCRIPTION
30 30
31WARNING! THIS IS A PRE-ALPHA RELEASE! IT WILL CRASH, CORRUPT YOUR DATA 31WARNING! This module is very new, and not very well tested (that's up to
32AND EAT YOUR CHILDREN! (Actually, apart from being untested and a bit 32you to do). Furthermore, details of the implementation might change freely
33feature-limited, it might already be useful). 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.
37
38You are still invited to try out CBOR, and this module.
34 39
35This module converts Perl data structures to the Concise Binary Object 40This module converts Perl data structures to the Concise Binary Object
36Representation (CBOR) and vice versa. CBOR is a fast binary serialisation 41Representation (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 42format 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 43can represent something in JSON, you should be able to represent it in
39CBOR. 44CBOR.
40 45
41This makes it a faster and more compact binary alternative to JSON, with 46In short, CBOR is a faster and very compact binary alternative to JSON,
42the added ability of supporting serialising 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).
43 50
44The 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
45is 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.
46 53
47See 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
… …
51 58
52package CBOR::XS; 59package CBOR::XS;
53 60
54use common::sense; 61use common::sense;
55 62
56our $VERSION = 0.03; 63our $VERSION = 0.05;
57our @ISA = qw(Exporter); 64our @ISA = qw(Exporter);
58 65
59our @EXPORT = qw(encode_cbor decode_cbor); 66our @EXPORT = qw(encode_cbor decode_cbor);
60 67
61use Exporter; 68use Exporter;
… …
222error). See the L<Types::Serialiser> manpage for details. 229error). See the L<Types::Serialiser> manpage for details.
223 230
224=item CBOR tag 256 (perl object) 231=item CBOR tag 256 (perl object)
225 232
226The tag value C<256> (TODO: pending iana registration) will be used 233The tag value C<256> (TODO: pending iana registration) will be used
227to deserialise a Perl object serialised with C<FREEZE>. See "OBJECT 234to deserialise a Perl object serialised with C<FREEZE>. See L<OBJECT
228SERIALISATION", below, for details. 235SERIALISATION>, below, for details.
229 236
230=item CBOR tag 55799 (magic header) 237=item CBOR tag 55799 (magic header)
231 238
232The tag 55799 is ignored (this tag implements the magic header). 239The tag 55799 is ignored (this tag implements the magic header).
233 240
… …
288if you want. 295if you want.
289 296
290=item other blessed objects 297=item other blessed objects
291 298
292Other blessed objects are serialised via C<TO_CBOR> or C<FREEZE>. See 299Other blessed objects are serialised via C<TO_CBOR> or C<FREEZE>. See
293"OBJECT SERIALISATION", below, for details. 300L<OBJECT SERIALISATION>, below, for details.
294 301
295=item simple scalars 302=item simple scalars
296 303
297TODO 304TODO
298Simple Perl scalars (any scalar that is not a reference) are the most 305Simple Perl scalars (any scalar that is not a reference) are the most
… …
446This string is available as C<$CBOR::XS::MAGIC>. This module does not 453This string is available as C<$CBOR::XS::MAGIC>. This module does not
447prepend this string tot he CBOR data it generates, but it will ignroe it 454prepend this string tot he CBOR data it generates, but it will ignroe it
448if present, so users can prepend this string as a "file type" indicator as 455if present, so users can prepend this string as a "file type" indicator as
449required. 456required.
450 457
458
459=head1 THE CBOR::XS::Tagged CLASS
460
461CBOR has the concept of tagged values - any CBOR value can be tagged with
462a numeric 64 bit number, which are centrally administered.
463
464C<CBOR::XS> handles a few tags internally when en- or decoding. You can
465also create tags yourself by encoding C<CBOR::XS::Tagged> objects, and the
466decoder will create C<CBOR::XS::Tagged> objects itself when it hits an
467unknown tag.
468
469These objects are simply blessed array references - the first member of
470the array being the numerical tag, the second being the value.
471
472You can interact with C<CBOR::XS::Tagged> objects in the following ways:
473
474=over 4
475
476=item $tagged = CBOR::XS::tag $tag, $value
477
478This function(!) creates a new C<CBOR::XS::Tagged> object using the given
479C<$tag> (0..2**64-1) to tag the given C<$value> (which can be any Perl
480value that can be encoded in CBOR, including serialisable Perl objects and
481C<CBOR::XS::Tagged> objects).
482
483=item $tagged->[0]
484
485=item $tagged->[0] = $new_tag
486
487=item $tag = $tagged->tag
488
489=item $new_tag = $tagged->tag ($new_tag)
490
491Access/mutate the tag.
492
493=item $tagged->[1]
494
495=item $tagged->[1] = $new_value
496
497=item $value = $tagged->value
498
499=item $new_value = $tagged->value ($new_value)
500
501Access/mutate the tagged value.
502
503=back
504
505=cut
506
507sub tag($$) {
508 bless [@_], CBOR::XS::Tagged::;
509}
510
511sub CBOR::XS::Tagged::tag {
512 $_[0][0] = $_[1] if $#_;
513 $_[0][0]
514}
515
516sub CBOR::XS::Tagged::value {
517 $_[0][1] = $_[1] if $#_;
518 $_[0][1]
519}
451 520
452=head1 CBOR and JSON 521=head1 CBOR and JSON
453 522
454CBOR is supposed to implement a superset of the JSON data model, and is, 523CBOR is supposed to implement a superset of the JSON data model, and is,
455with some coercion, able to represent all JSON texts (something that other 524with some coercion, able to represent all JSON texts (something that other

Diff Legend

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