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.30 by root, Sat Nov 30 16:19:59 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
32AND EAT YOUR CHILDREN! (Actually, apart from being untested and a bit
33feature-limited, it might already be useful).
34
35This module converts Perl data structures to the Concise Binary Object 31This module converts Perl data structures to the Concise Binary Object
36Representation (CBOR) and vice versa. CBOR is a fast binary serialisation 32Representation (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 33format that aims to use an (almost) superset of the JSON data model, i.e.
38can represent something in JSON, you should be able to represent it in 34when you can represent something useful in JSON, you should be able to
39CBOR. 35represent it in CBOR.
40 36
41This makes it a faster and more compact binary alternative to JSON, with 37In short, CBOR is a faster and quite compact binary alternative to JSON,
42the added ability of supporting serialising of perl objects. 38with the added ability of supporting serialisation of Perl objects. (JSON
39often compresses better than CBOR though, so if you plan to compress the
40data later and speed is less important you might want to compare both
41formats first).
42
43To give you a general idea about speed, with texts in the megabyte range,
44C<CBOR::XS> usually encodes roughly twice as fast as L<Storable> or
45L<JSON::XS> and decodes about 15%-30% faster than those. The shorter the
46data, the worse L<Storable> performs in comparison.
47
48Regarding compactness, C<CBOR::XS>-encoded data structures are usually
49about 20% smaller than the same data encoded as (compact) JSON or
50L<Storable>.
51
52In addition to the core CBOR data format, this module implements a
53number of extensions, to support cyclic and shared data structures (see
54C<allow_sharing>), string deduplication (see C<pack_strings>) and scalar
55references (always enabled).
43 56
44The primary goal of this module is to be I<correct> and the secondary goal 57The 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. 58is to be I<fast>. To reach the latter goal it was written in C.
46 59
47See MAPPING, below, on how CBOR::XS maps perl values to CBOR values and 60See MAPPING, below, on how CBOR::XS maps perl values to CBOR values and
51 64
52package CBOR::XS; 65package CBOR::XS;
53 66
54use common::sense; 67use common::sense;
55 68
56our $VERSION = 0.03; 69our $VERSION = '1.0';
57our @ISA = qw(Exporter); 70our @ISA = qw(Exporter);
58 71
59our @EXPORT = qw(encode_cbor decode_cbor); 72our @EXPORT = qw(encode_cbor decode_cbor);
60 73
61use Exporter; 74use Exporter;
98strings. All boolean flags described below are by default I<disabled>. 111strings. All boolean flags described below are by default I<disabled>.
99 112
100The mutators for flags all return the CBOR object again and thus calls can 113The mutators for flags all return the CBOR object again and thus calls can
101be chained: 114be chained:
102 115
103#TODO
104 my $cbor = CBOR::XS->new->encode ({a => [1,2]}); 116 my $cbor = CBOR::XS->new->encode ({a => [1,2]});
105 117
106=item $cbor = $cbor->max_depth ([$maximum_nesting_depth]) 118=item $cbor = $cbor->max_depth ([$maximum_nesting_depth])
107 119
108=item $max_depth = $cbor->get_max_depth 120=item $max_depth = $cbor->get_max_depth
142If no argument is given, the limit check will be deactivated (same as when 154If no argument is given, the limit check will be deactivated (same as when
143C<0> is specified). 155C<0> is specified).
144 156
145See SECURITY CONSIDERATIONS, below, for more info on why this is useful. 157See SECURITY CONSIDERATIONS, below, for more info on why this is useful.
146 158
159=item $cbor = $cbor->allow_unknown ([$enable])
160
161=item $enabled = $cbor->get_allow_unknown
162
163If C<$enable> is true (or missing), then C<encode> will I<not> throw an
164exception when it encounters values it cannot represent in CBOR (for
165example, filehandles) but instead will encode a CBOR C<error> value.
166
167If C<$enable> is false (the default), then C<encode> will throw an
168exception when it encounters anything it cannot encode as CBOR.
169
170This option does not affect C<decode> in any way, and it is recommended to
171leave it off unless you know your communications partner.
172
173=item $cbor = $cbor->allow_sharing ([$enable])
174
175=item $enabled = $cbor->get_allow_sharing
176
177If C<$enable> is true (or missing), then C<encode> will not double-encode
178values that have been referenced before (e.g. when the same object, such
179as an array, is referenced multiple times), but instead will emit a
180reference to the earlier value.
181
182This means that such values will only be encoded once, and will not result
183in a deep cloning of the value on decode, in decoders supporting the value
184sharing extension. This also makes it possible to encode cyclic data
185structures.
186
187It is recommended to leave it off unless you know your
188communication partner supports the value sharing extensions to CBOR
189(L<http://cbor.schmorp.de/value-sharing>), as without decoder support, the
190resulting data structure might be unusable.
191
192Detecting shared values incurs a runtime overhead when values are encoded
193that have a reference counter large than one, and might unnecessarily
194increase the encoded size, as potentially shared values are encode as
195sharable whether or not they are actually shared.
196
197At the moment, only targets of references can be shared (e.g. scalars,
198arrays or hashes pointed to by a reference). Weirder constructs, such as
199an array with multiple "copies" of the I<same> string, which are hard but
200not impossible to create in Perl, are not supported (this is the same as
201with L<Storable>).
202
203If C<$enable> is false (the default), then C<encode> will encode shared
204data structures repeatedly, unsharing them in the process. Cyclic data
205structures cannot be encoded in this mode.
206
207This option does not affect C<decode> in any way - shared values and
208references will always be decoded properly if present.
209
210=item $cbor = $cbor->pack_strings ([$enable])
211
212=item $enabled = $cbor->get_pack_strings
213
214If C<$enable> is true (or missing), then C<encode> will try not to encode
215the same string twice, but will instead encode a reference to the string
216instead. Depending on your data format, this can save a lot of space, but
217also results in a very large runtime overhead (expect encoding times to be
2182-4 times as high as without).
219
220It is recommended to leave it off unless you know your
221communications partner supports the stringref extension to CBOR
222(L<http://cbor.schmorp.de/stringref>), as without decoder support, the
223resulting data structure might not be usable.
224
225If C<$enable> is false (the default), then C<encode> will encode strings
226the standard CBOR way.
227
228This option does not affect C<decode> in any way - string references will
229always be decoded properly if present.
230
231=item $cbor = $cbor->filter ([$cb->($tag, $value)])
232
233=item $cb_or_undef = $cbor->get_filter
234
235Sets or replaces the tagged value decoding filter (when C<$cb> is
236specified) or clears the filter (if no argument or C<undef> is provided).
237
238The filter callback is called only during decoding, when a non-enforced
239tagged value has been decoded (see L<TAG HANDLING AND EXTENSIONS> for a
240list of enforced tags). For specific tags, it's often better to provide a
241default converter using the C<%CBOR::XS::FILTER> hash (see below).
242
243The first argument is the numerical tag, the second is the (decoded) value
244that has been tagged.
245
246The filter function should return either exactly one value, which will
247replace the tagged value in the decoded data structure, or no values,
248which will result in default handling, which currently means the decoder
249creates a C<CBOR::XS::Tagged> object to hold the tag and the value.
250
251When the filter is cleared (the default state), the default filter
252function, C<CBOR::XS::default_filter>, is used. This function simply looks
253up the tag in the C<%CBOR::XS::FILTER> hash. If an entry exists it must be
254a code reference that is called with tag and value, and is responsible for
255decoding the value. If no entry exists, it returns no values.
256
257Example: decode all tags not handled internally into C<CBOR::XS::Tagged>
258objects, with no other special handling (useful when working with
259potentially "unsafe" CBOR data).
260
261 CBOR::XS->new->filter (sub { })->decode ($cbor_data);
262
263Example: provide a global filter for tag 1347375694, converting the value
264into some string form.
265
266 $CBOR::XS::FILTER{1347375694} = sub {
267 my ($tag, $value);
268
269 "tag 1347375694 value $value"
270 };
271
147=item $cbor_data = $cbor->encode ($perl_scalar) 272=item $cbor_data = $cbor->encode ($perl_scalar)
148 273
149Converts the given Perl data structure (a scalar value) to its CBOR 274Converts the given Perl data structure (a scalar value) to its CBOR
150representation. 275representation.
151 276
191CBOR integers become (numeric) perl scalars. On perls without 64 bit 316CBOR integers become (numeric) perl scalars. On perls without 64 bit
192support, 64 bit integers will be truncated or otherwise corrupted. 317support, 64 bit integers will be truncated or otherwise corrupted.
193 318
194=item byte strings 319=item byte strings
195 320
196Byte strings will become octet strings in Perl (the byte values 0..255 321Byte strings will become octet strings in Perl (the Byte values 0..255
197will simply become characters of the same value in Perl). 322will simply become characters of the same value in Perl).
198 323
199=item UTF-8 strings 324=item UTF-8 strings
200 325
201UTF-8 strings in CBOR will be decoded, i.e. the UTF-8 octets will be 326UTF-8 strings in CBOR will be decoded, i.e. the UTF-8 octets will be
219C<Types:Serialiser::false> and C<Types::Serialiser::error>, 344C<Types:Serialiser::false> and C<Types::Serialiser::error>,
220respectively. They are overloaded to act almost exactly like the numbers 345respectively. They are overloaded to act almost exactly like the numbers
221C<1> and C<0> (for true and false) or to throw an exception on access (for 346C<1> and C<0> (for true and false) or to throw an exception on access (for
222error). See the L<Types::Serialiser> manpage for details. 347error). See the L<Types::Serialiser> manpage for details.
223 348
224=item CBOR tag 256 (perl object) 349=item tagged values
225 350
226The tag value C<256> (TODO: pending iana registration) will be used
227to deserialise a Perl object serialised with C<FREEZE>. See "OBJECT
228SERIALISATION", below, for details.
229
230=item CBOR tag 55799 (magic header)
231
232The tag 55799 is ignored (this tag implements the magic header).
233
234=item other CBOR tags
235
236Tagged items consists of a numeric tag and another CBOR value. Tags not 351Tagged items consists of a numeric tag and another CBOR value.
237handled internally are currently converted into a L<CBOR::XS::Tagged>
238object, which is simply a blessed array reference consisting of the
239numeric tag value followed by the (decoded) CBOR value.
240 352
241In the future, support for user-supplied conversions might get added. 353See L<TAG HANDLING AND EXTENSIONS> and the description of C<< ->filter >>
354for details on which tags are handled how.
242 355
243=item anything else 356=item anything else
244 357
245Anything else (e.g. unsupported simple values) will raise a decoding 358Anything else (e.g. unsupported simple values) will raise a decoding
246error. 359error.
249 362
250 363
251=head2 PERL -> CBOR 364=head2 PERL -> CBOR
252 365
253The mapping from Perl to CBOR is slightly more difficult, as Perl is a 366The mapping from Perl to CBOR is slightly more difficult, as Perl is a
254truly typeless language, so we can only guess which CBOR type is meant by 367typeless language. That means this module can only guess which CBOR type
255a Perl value. 368is meant by a perl value.
256 369
257=over 4 370=over 4
258 371
259=item hash references 372=item hash references
260 373
261Perl hash references become CBOR maps. As there is no inherent ordering in 374Perl hash references become CBOR maps. As there is no inherent ordering in
262hash keys (or CBOR maps), they will usually be encoded in a pseudo-random 375hash keys (or CBOR maps), they will usually be encoded in a pseudo-random
263order. 376order. This order can be different each time a hahs is encoded.
264 377
265Currently, tied hashes will use the indefinite-length format, while normal 378Currently, tied hashes will use the indefinite-length format, while normal
266hashes will use the fixed-length format. 379hashes will use the fixed-length format.
267 380
268=item array references 381=item array references
269 382
270Perl array references become fixed-length CBOR arrays. 383Perl array references become fixed-length CBOR arrays.
271 384
272=item other references 385=item other references
273 386
274Other unblessed references are generally not allowed and will cause an 387Other unblessed references will be represented using
275exception to be thrown, except for references to the integers C<0> and 388the indirection tag extension (tag value C<22098>,
276C<1>, which get turned into false and true in CBOR. 389L<http://cbor.schmorp.de/indirection>). CBOR decoders are guaranteed
390to be able to decode these values somehow, by either "doing the right
391thing", decoding into a generic tagged object, simply ignoring the tag, or
392something else.
277 393
278=item CBOR::XS::Tagged objects 394=item CBOR::XS::Tagged objects
279 395
280Objects of this type must be arrays consisting of a single C<[tag, value]> 396Objects of this type must be arrays consisting of a single C<[tag, value]>
281pair. The (numerical) tag will be encoded as a CBOR tag, the value will be 397pair. The (numerical) tag will be encoded as a CBOR tag, the value will
282encoded as appropriate for the value. 398be encoded as appropriate for the value. You must use C<CBOR::XS::tag> to
399create such objects.
283 400
284=item Types::Serialiser::true, Types::Serialiser::false, Types::Serialiser::error 401=item Types::Serialiser::true, Types::Serialiser::false, Types::Serialiser::error
285 402
286These special values become CBOR true, CBOR false and CBOR undefined 403These special values become CBOR true, CBOR false and CBOR undefined
287values, respectively. You can also use C<\1>, C<\0> and C<\undef> directly 404values, respectively. You can also use C<\1>, C<\0> and C<\undef> directly
288if you want. 405if you want.
289 406
290=item other blessed objects 407=item other blessed objects
291 408
292Other blessed objects are serialised via C<TO_CBOR> or C<FREEZE>. See 409Other blessed objects are serialised via C<TO_CBOR> or C<FREEZE>. See
293"OBJECT SERIALISATION", below, for details. 410L<TAG HANDLING AND EXTENSIONS> for specific classes handled by this
411module, and L<OBJECT SERIALISATION> for generic object serialisation.
294 412
295=item simple scalars 413=item simple scalars
296 414
297TODO
298Simple Perl scalars (any scalar that is not a reference) are the most 415Simple Perl scalars (any scalar that is not a reference) are the most
299difficult objects to encode: CBOR::XS will encode undefined scalars as 416difficult objects to encode: CBOR::XS will encode undefined scalars as
300CBOR null values, scalars that have last been used in a string context 417CBOR null values, scalars that have last been used in a string context
301before encoding as CBOR strings, and anything else as number value: 418before encoding as CBOR strings, and anything else as number value:
302 419
303 # dump as number 420 # dump as number
304 encode_cbor [2] # yields [2] 421 encode_cbor [2] # yields [2]
305 encode_cbor [-3.0e17] # yields [-3e+17] 422 encode_cbor [-3.0e17] # yields [-3e+17]
306 my $value = 5; encode_cbor [$value] # yields [5] 423 my $value = 5; encode_cbor [$value] # yields [5]
307 424
308 # used as string, so dump as string 425 # used as string, so dump as string (either byte or text)
309 print $value; 426 print $value;
310 encode_cbor [$value] # yields ["5"] 427 encode_cbor [$value] # yields ["5"]
311 428
312 # undef becomes null 429 # undef becomes null
313 encode_cbor [undef] # yields [null] 430 encode_cbor [undef] # yields [null]
316 433
317 my $x = 3.1; # some variable containing a number 434 my $x = 3.1; # some variable containing a number
318 "$x"; # stringified 435 "$x"; # stringified
319 $x .= ""; # another, more awkward way to stringify 436 $x .= ""; # another, more awkward way to stringify
320 print $x; # perl does it for you, too, quite often 437 print $x; # perl does it for you, too, quite often
438
439You can force whether a string ie encoded as byte or text string by using
440C<utf8::upgrade> and C<utf8::downgrade>):
441
442 utf8::upgrade $x; # encode $x as text string
443 utf8::downgrade $x; # encode $x as byte string
444
445Perl doesn't define what operations up- and downgrade strings, so if the
446difference between byte and text is important, you should up- or downgrade
447your string as late as possible before encoding.
321 448
322You can force the type to be a CBOR number by numifying it: 449You can force the type to be a CBOR number by numifying it:
323 450
324 my $x = "3"; # some variable containing a string 451 my $x = "3"; # some variable containing a string
325 $x += 0; # numify it, ensuring it will be dumped as a number 452 $x += 0; # numify it, ensuring it will be dumped as a number
338 465
339=back 466=back
340 467
341=head2 OBJECT SERIALISATION 468=head2 OBJECT SERIALISATION
342 469
470This module implements both a CBOR-specific and the generic
471L<Types::Serialier> object serialisation protocol. The following
472subsections explain both methods.
473
474=head3 ENCODING
475
343This module knows two way to serialise a Perl object: The CBOR-specific 476This module knows two way to serialise a Perl object: The CBOR-specific
344way, and the generic way. 477way, and the generic way.
345 478
346Whenever the encoder encounters a Perl object that it cnanot serialise 479Whenever the encoder encounters a Perl object that it cannot serialise
347directly (most of them), it will first look up the C<TO_CBOR> method on 480directly (most of them), it will first look up the C<TO_CBOR> method on
348it. 481it.
349 482
350If it has a C<TO_CBOR> method, it will call it with the object as only 483If 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 484argument, and expects exactly one return value, which it will then
357 490
358The C<FREEZE> method can return any number of values (i.e. zero or 491The 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 492more). These will be encoded as CBOR perl object, together with the
360classname. 493classname.
361 494
495These methods I<MUST NOT> change the data structure that is being
496serialised. Failure to comply to this can result in memory corruption -
497and worse.
498
362If an object supports neither C<TO_CBOR> nor C<FREEZE>, encoding will fail 499If an object supports neither C<TO_CBOR> nor C<FREEZE>, encoding will fail
363with an error. 500with an error.
364 501
502=head3 DECODING
503
365Objects encoded via C<TO_CBOR> cannot be automatically decoded, but 504Objects encoded via C<TO_CBOR> cannot (normally) be automatically decoded,
366objects encoded via C<FREEZE> can be decoded using the following protocol: 505but objects encoded via C<FREEZE> can be decoded using the following
506protocol:
367 507
368When an encoded CBOR perl object is encountered by the decoder, it will 508When 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 509look up the C<THAW> method, by using the stored classname, and will fail
370if the method cannot be found. 510if the method cannot be found.
371 511
372After the lookup it will call the C<THAW> method with the stored classname 512After 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 513as first argument, the constant string C<CBOR> as second argument, and all
374values returned by C<FREEZE> as remaining arguments. 514values returned by C<FREEZE> as remaining arguments.
375 515
376=head4 EXAMPLES 516=head3 EXAMPLES
377 517
378Here is an example C<TO_CBOR> method: 518Here is an example C<TO_CBOR> method:
379 519
380 sub My::Object::TO_CBOR { 520 sub My::Object::TO_CBOR {
381 my ($obj) = @_; 521 my ($obj) = @_;
392 532
393 sub URI::TO_CBOR { 533 sub URI::TO_CBOR {
394 my ($self) = @_; 534 my ($self) = @_;
395 my $uri = "$self"; # stringify uri 535 my $uri = "$self"; # stringify uri
396 utf8::upgrade $uri; # make sure it will be encoded as UTF-8 string 536 utf8::upgrade $uri; # make sure it will be encoded as UTF-8 string
397 CBOR::XS::tagged 32, "$_[0]" 537 CBOR::XS::tag 32, "$_[0]"
398 } 538 }
399 539
400This will encode URIs as a UTF-8 string with tag 32, which indicates an 540This will encode URIs as a UTF-8 string with tag 32, which indicates an
401URI. 541URI.
402 542
439=head1 MAGIC HEADER 579=head1 MAGIC HEADER
440 580
441There is no way to distinguish CBOR from other formats 581There is no way to distinguish CBOR from other formats
442programmatically. To make it easier to distinguish CBOR from other 582programmatically. To make it easier to distinguish CBOR from other
443formats, the CBOR specification has a special "magic string" that can be 583formats, the CBOR specification has a special "magic string" that can be
444prepended to any CBOR string without changing it's meaning. 584prepended to any CBOR string without changing its meaning.
445 585
446This string is available as C<$CBOR::XS::MAGIC>. This module does not 586This 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 587prepend this string to the CBOR data it generates, but it will ignore it
448if present, so users can prepend this string as a "file type" indicator as 588if present, so users can prepend this string as a "file type" indicator as
449required. 589required.
590
591
592=head1 THE CBOR::XS::Tagged CLASS
593
594CBOR has the concept of tagged values - any CBOR value can be tagged with
595a numeric 64 bit number, which are centrally administered.
596
597C<CBOR::XS> handles a few tags internally when en- or decoding. You can
598also create tags yourself by encoding C<CBOR::XS::Tagged> objects, and the
599decoder will create C<CBOR::XS::Tagged> objects itself when it hits an
600unknown tag.
601
602These objects are simply blessed array references - the first member of
603the array being the numerical tag, the second being the value.
604
605You can interact with C<CBOR::XS::Tagged> objects in the following ways:
606
607=over 4
608
609=item $tagged = CBOR::XS::tag $tag, $value
610
611This function(!) creates a new C<CBOR::XS::Tagged> object using the given
612C<$tag> (0..2**64-1) to tag the given C<$value> (which can be any Perl
613value that can be encoded in CBOR, including serialisable Perl objects and
614C<CBOR::XS::Tagged> objects).
615
616=item $tagged->[0]
617
618=item $tagged->[0] = $new_tag
619
620=item $tag = $tagged->tag
621
622=item $new_tag = $tagged->tag ($new_tag)
623
624Access/mutate the tag.
625
626=item $tagged->[1]
627
628=item $tagged->[1] = $new_value
629
630=item $value = $tagged->value
631
632=item $new_value = $tagged->value ($new_value)
633
634Access/mutate the tagged value.
635
636=back
637
638=cut
639
640sub tag($$) {
641 bless [@_], CBOR::XS::Tagged::;
642}
643
644sub CBOR::XS::Tagged::tag {
645 $_[0][0] = $_[1] if $#_;
646 $_[0][0]
647}
648
649sub CBOR::XS::Tagged::value {
650 $_[0][1] = $_[1] if $#_;
651 $_[0][1]
652}
653
654=head2 EXAMPLES
655
656Here are some examples of C<CBOR::XS::Tagged> uses to tag objects.
657
658You can look up CBOR tag value and emanings in the IANA registry at
659L<http://www.iana.org/assignments/cbor-tags/cbor-tags.xhtml>.
660
661Prepend a magic header (C<$CBOR::XS::MAGIC>):
662
663 my $cbor = encode_cbor CBOR::XS::tag 55799, $value;
664 # same as:
665 my $cbor = $CBOR::XS::MAGIC . encode_cbor $value;
666
667Serialise some URIs and a regex in an array:
668
669 my $cbor = encode_cbor [
670 (CBOR::XS::tag 32, "http://www.nethype.de/"),
671 (CBOR::XS::tag 32, "http://software.schmorp.de/"),
672 (CBOR::XS::tag 35, "^[Pp][Ee][Rr][lL]\$"),
673 ];
674
675Wrap CBOR data in CBOR:
676
677 my $cbor_cbor = encode_cbor
678 CBOR::XS::tag 24,
679 encode_cbor [1, 2, 3];
680
681=head1 TAG HANDLING AND EXTENSIONS
682
683This section describes how this module handles specific tagged values
684and extensions. If a tag is not mentioned here and no additional filters
685are provided for it, then the default handling applies (creating a
686CBOR::XS::Tagged object on decoding, and only encoding the tag when
687explicitly requested).
688
689Tags not handled specifically are currently converted into a
690L<CBOR::XS::Tagged> object, which is simply a blessed array reference
691consisting of the numeric tag value followed by the (decoded) CBOR value.
692
693Future versions of this module reserve the right to special case
694additional tags (such as base64url).
695
696=head2 ENFORCED TAGS
697
698These tags are always handled when decoding, and their handling cannot be
699overriden by the user.
700
701=over 4
702
703=item 26 (perl-object, L<http://cbor.schmorp.de/perl-object>)
704
705These tags are automatically created (and decoded) for serialisable
706objects using the C<FREEZE/THAW> methods (the L<Types::Serialier> object
707serialisation protocol). See L<OBJECT SERIALISATION> for details.
708
709=item 28, 29 (sharable, sharedref, L <http://cbor.schmorp.de/value-sharing>)
710
711These tags are automatically decoded when encountered, resulting in
712shared values in the decoded object. They are only encoded, however, when
713C<allow_sharable> is enabled.
714
715=item 256, 25 (stringref-namespace, stringref, L <http://cbor.schmorp.de/stringref>)
716
717These tags are automatically decoded when encountered. They are only
718encoded, however, when C<pack_strings> is enabled.
719
720=item 22098 (indirection, L<http://cbor.schmorp.de/indirection>)
721
722This tag is automatically generated when a reference are encountered (with
723the exception of hash and array refernces). It is converted to a reference
724when decoding.
725
726=item 55799 (self-describe CBOR, RFC 7049)
727
728This value is not generated on encoding (unless explicitly requested by
729the user), and is simply ignored when decoding.
730
731=back
732
733=head2 NON-ENFORCED TAGS
734
735These tags have default filters provided when decoding. Their handling can
736be overriden by changing the C<%CBOR::XS::FILTER> entry for the tag, or by
737providing a custom C<filter> callback when decoding.
738
739When they result in decoding into a specific Perl class, the module
740usually provides a corresponding C<TO_CBOR> method as well.
741
742When any of these need to load additional modules that are not part of the
743perl core distribution (e.g. L<URI>), it is (currently) up to the user to
744provide these modules. The decoding usually fails with an exception if the
745required module cannot be loaded.
746
747=over 4
748
749=item 2, 3 (positive/negative bignum)
750
751These tags are decoded into L<Math::BigInt> objects. The corresponding
752C<Math::BigInt::TO_CBOR> method encodes "small" bigints into normal CBOR
753integers, and others into positive/negative CBOR bignums.
754
755=item 4, 5 (decimal fraction/bigfloat)
756
757Both decimal fractions and bigfloats are decoded into L<Math::BigFloat>
758objects. The corresponding C<Math::BigFloat::TO_CBOR> method I<always>
759encodes into a decimal fraction.
760
761CBOR cannot represent bigfloats with I<very> large exponents - conversion
762of such big float objects is undefined.
763
764Also, NaN and infinities are not encoded properly.
765
766=item 21, 22, 23 (expected later JSON conversion)
767
768CBOR::XS is not a CBOR-to-JSON converter, and will simply ignore these
769tags.
770
771=item 32 (URI)
772
773These objects decode into L<URI> objects. The corresponding
774C<URI::TO_CBOR> method again results in a CBOR URI value.
775
776=back
777
778=cut
779
780our %FILTER = (
781 # 0 # rfc4287 datetime, utf-8
782 # 1 # unix timestamp, any
783
784 2 => sub { # pos bigint
785 require Math::BigInt;
786 Math::BigInt->new ("0x" . unpack "H*", pop)
787 },
788
789 3 => sub { # neg bigint
790 require Math::BigInt;
791 -Math::BigInt->new ("0x" . unpack "H*", pop)
792 },
793
794 4 => sub { # decimal fraction, array
795 require Math::BigFloat;
796 Math::BigFloat->new ($_[1][1] . "E" . $_[1][0])
797 },
798
799 5 => sub { # bigfloat, array
800 require Math::BigFloat;
801 scalar Math::BigFloat->new ($_[1][1])->blsft ($_[1][0], 2)
802 },
803
804 21 => sub { pop }, # expected conversion to base64url encoding
805 22 => sub { pop }, # expected conversion to base64 encoding
806 23 => sub { pop }, # expected conversion to base16 encoding
807
808 # 24 # embedded cbor, byte string
809
810 32 => sub {
811 require URI;
812 URI->new (pop)
813 },
814
815 # 33 # base64url rfc4648, utf-8
816 # 34 # base64 rfc46484, utf-8
817 # 35 # regex pcre/ecma262, utf-8
818 # 36 # mime message rfc2045, utf-8
819);
450 820
451 821
452=head1 CBOR and JSON 822=head1 CBOR and JSON
453 823
454CBOR is supposed to implement a superset of the JSON data model, and is, 824CBOR is supposed to implement a superset of the JSON data model, and is,
516properly. Half precision types are accepted, but not encoded. 886properly. Half precision types are accepted, but not encoded.
517 887
518Strict mode and canonical mode are not implemented. 888Strict mode and canonical mode are not implemented.
519 889
520 890
891=head1 LIMITATIONS ON PERLS WITHOUT 64-BIT INTEGER SUPPORT
892
893On perls that were built without 64 bit integer support (these are rare
894nowadays, even on 32 bit architectures), support for any kind of 64 bit
895integer in CBOR is very limited - most likely, these 64 bit values will
896be truncated, corrupted, or otherwise not decoded correctly. This also
897includes string, array and map sizes that are stored as 64 bit integers.
898
899
521=head1 THREADS 900=head1 THREADS
522 901
523This module is I<not> guaranteed to be thread safe and there are no 902This module is I<not> guaranteed to be thread safe and there are no
524plans to change this until Perl gets thread support (as opposed to the 903plans to change this until Perl gets thread support (as opposed to the
525horribly slow so-called "threads" which are simply slow and bloated 904horribly slow so-called "threads" which are simply slow and bloated
537Please refrain from using rt.cpan.org or any other bug reporting 916Please refrain from using rt.cpan.org or any other bug reporting
538service. I put the contact address into my modules for a reason. 917service. I put the contact address into my modules for a reason.
539 918
540=cut 919=cut
541 920
921our %FILTER = (
922 # 0 # rfc4287 datetime, utf-8
923 # 1 # unix timestamp, any
924
925 2 => sub { # pos bigint
926 require Math::BigInt;
927 Math::BigInt->new ("0x" . unpack "H*", pop)
928 },
929
930 3 => sub { # neg bigint
931 require Math::BigInt;
932 -Math::BigInt->new ("0x" . unpack "H*", pop)
933 },
934
935 4 => sub { # decimal fraction, array
936 require Math::BigFloat;
937 Math::BigFloat->new ($_[1][1] . "E" . $_[1][0])
938 },
939
940 5 => sub { # bigfloat, array
941 require Math::BigFloat;
942 scalar Math::BigFloat->new ($_[1][1])->blsft ($_[1][0], 2)
943 },
944
945 21 => sub { pop }, # expected conversion to base64url encoding
946 22 => sub { pop }, # expected conversion to base64 encoding
947 23 => sub { pop }, # expected conversion to base16 encoding
948
949 # 24 # embedded cbor, byte string
950
951 32 => sub {
952 require URI;
953 URI->new (pop)
954 },
955
956 # 33 # base64url rfc4648, utf-8
957 # 34 # base64 rfc46484, utf-8
958 # 35 # regex pcre/ecma262, utf-8
959 # 36 # mime message rfc2045, utf-8
960);
961
962sub CBOR::XS::default_filter {
963 &{ $FILTER{$_[0]} or return }
964}
965
966sub URI::TO_CBOR {
967 my $uri = $_[0]->as_string;
968 utf8::upgrade $uri;
969 CBOR::XS::tag 32, $uri
970}
971
972sub Math::BigInt::TO_CBOR {
973 if ($_[0] >= -2147483648 && $_[0] <= 2147483647) {
974 $_[0]->numify
975 } else {
976 my $hex = substr $_[0]->as_hex, 2;
977 $hex = "0$hex" if 1 & length $hex; # sigh
978 CBOR::XS::tag $_[0] >= 0 ? 2 : 3, pack "H*", $hex
979 }
980}
981
982sub Math::BigFloat::TO_CBOR {
983 my ($m, $e) = $_[0]->parts;
984 CBOR::XS::tag 4, [$e->numify, $m]
985}
986
542XSLoader::load "CBOR::XS", $VERSION; 987XSLoader::load "CBOR::XS", $VERSION;
543 988
544=head1 SEE ALSO 989=head1 SEE ALSO
545 990
546The L<JSON> and L<JSON::XS> modules that do similar, but human-readable, 991The L<JSON> and L<JSON::XS> modules that do similar, but human-readable,

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines