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.22 by root, Fri Nov 22 15:28:38 2013 UTC vs.
Revision 1.27 by root, Thu Nov 28 15:43:24 2013 UTC

… …
56As for compactness, C<CBOR::XS> encoded data structures are usually about 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>. 5720% smaller than the same data encoded as (compact) JSON or L<Storable>.
58 58
59In addition to the core CBOR data format, this module implements a number 59In addition to the core CBOR data format, this module implements a number
60of extensions, to support cyclic and self-referencing data structures 60of extensions, to support cyclic and self-referencing data structures
61(see C<allow_sharing>), string deduplication (see C<allow_stringref>) and 61(see C<allow_sharing>), string deduplication (see C<pack_strings>) and
62scalar references (always enabled). 62scalar references (always enabled).
63 63
64The primary goal of this module is to be I<correct> and the secondary goal 64The primary goal of this module is to be I<correct> and the secondary goal
65is to be I<fast>. To reach the latter goal it was written in C. 65is to be I<fast>. To reach the latter goal it was written in C.
66 66
… …
71 71
72package CBOR::XS; 72package CBOR::XS;
73 73
74use common::sense; 74use common::sense;
75 75
76our $VERSION = 0.08; 76our $VERSION = 0.09;
77our @ISA = qw(Exporter); 77our @ISA = qw(Exporter);
78 78
79our @EXPORT = qw(encode_cbor decode_cbor); 79our @EXPORT = qw(encode_cbor decode_cbor);
80 80
81use Exporter; 81use Exporter;
… …
118strings. All boolean flags described below are by default I<disabled>. 118strings. All boolean flags described below are by default I<disabled>.
119 119
120The mutators for flags all return the CBOR object again and thus calls can 120The mutators for flags all return the CBOR object again and thus calls can
121be chained: 121be chained:
122 122
123#TODO
124 my $cbor = CBOR::XS->new->encode ({a => [1,2]}); 123 my $cbor = CBOR::XS->new->encode ({a => [1,2]});
125 124
126=item $cbor = $cbor->max_depth ([$maximum_nesting_depth]) 125=item $cbor = $cbor->max_depth ([$maximum_nesting_depth])
127 126
128=item $max_depth = $cbor->get_max_depth 127=item $max_depth = $cbor->get_max_depth
… …
187as an array, is referenced multiple times), but instead will emit a 186as an array, is referenced multiple times), but instead will emit a
188reference to the earlier value. 187reference to the earlier value.
189 188
190This means that such values will only be encoded once, and will not result 189This means that such values will only be encoded once, and will not result
191in a deep cloning of the value on decode, in decoders supporting the value 190in a deep cloning of the value on decode, in decoders supporting the value
192sharing extension. 191sharing extension. This also makes it possible to encode cyclic data
192structures.
193 193
194It is recommended to leave it off unless you know your 194It is recommended to leave it off unless you know your
195communication partner supports the value sharing extensions to CBOR 195communication partner supports the value sharing extensions to CBOR
196(http://cbor.schmorp.de/value-sharing). 196(L<http://cbor.schmorp.de/value-sharing>), as without decoder support, the
197resulting data structure might be unusable.
197 198
198Detecting shared values incurs a runtime overhead when values are encoded 199Detecting shared values incurs a runtime overhead when values are encoded
199that have a reference counter large than one, and might unnecessarily 200that have a reference counter large than one, and might unnecessarily
200increase the encoded size, as potentially shared values are encode as 201increase the encoded size, as potentially shared values are encode as
201sharable whether or not they are actually shared. 202sharable whether or not they are actually shared.
202 203
203At the moment, only targets of references can be shared (e.g. scalars, 204At the moment, only targets of references can be shared (e.g. scalars,
204arrays or hashes pointed to by a reference). Weirder constructs, such as 205arrays or hashes pointed to by a reference). Weirder constructs, such as
205an array with multiple "copies" of the I<same> string, which are hard but 206an array with multiple "copies" of the I<same> string, which are hard but
206not impossible to create in Perl, are not supported (this is the same as 207not impossible to create in Perl, are not supported (this is the same as
207for L<Storable>). 208with L<Storable>).
208 209
209If C<$enable> is false (the default), then C<encode> will encode 210If C<$enable> is false (the default), then C<encode> will encode shared
210exception when it encounters anything it cannot encode as CBOR. 211data structures repeatedly, unsharing them in the process. Cyclic data
212structures cannot be encoded in this mode.
211 213
212This option does not affect C<decode> in any way - shared values and 214This option does not affect C<decode> in any way - shared values and
213references will always be decoded properly if present. 215references will always be decoded properly if present.
214 216
215=item $cbor = $cbor->allow_stringref ([$enable]) 217=item $cbor = $cbor->pack_strings ([$enable])
216 218
217=item $enabled = $cbor->get_allow_stringref 219=item $enabled = $cbor->get_pack_strings
218 220
219If C<$enable> is true (or missing), then C<encode> will try not to encode 221If C<$enable> is true (or missing), then C<encode> will try not to encode
220the same string twice, but will instead encode a reference to the string 222the same string twice, but will instead encode a reference to the string
221instead. Depending on your data format. this can save a lot of space, but 223instead. Depending on your data format, this can save a lot of space, but
222also results in a very large runtime overhead (expect encoding times to be 224also results in a very large runtime overhead (expect encoding times to be
2232-4 times as high as without). 2252-4 times as high as without).
224 226
225It is recommended to leave it off unless you know your 227It is recommended to leave it off unless you know your
226communications partner supports the stringref extension to CBOR 228communications partner supports the stringref extension to CBOR
227(http://cbor.schmorp.de/stringref). 229(L<http://cbor.schmorp.de/stringref>), as without decoder support, the
230resulting data structure might not be usable.
228 231
229If C<$enable> is false (the default), then C<encode> will encode 232If C<$enable> is false (the default), then C<encode> will encode strings
230exception when it encounters anything it cannot encode as CBOR. 233the standard CBOR way.
231 234
232This option does not affect C<decode> in any way - string references will 235This option does not affect C<decode> in any way - string references will
233always be decoded properly if present. 236always be decoded properly if present.
237
238=item $cbor = $cbor->filter ([$cb->($tag, $value)])
239
240=item $cb_or_undef = $cbor->get_filter
241
242Sets or replaces the tagged value decoding filter (when C<$cb> is
243specified) or clears the filter (if no argument or C<undef> is provided).
244
245The filter callback is called only during decoding, when a non-enforced
246tagged value has been decoded (see L<TAG HANDLING AND EXTENSIONS> for a
247list of enforced tags). For specific tags, it's often better to provide a
248default converter using the C<%CBOR::XS::FILTER> hash (see below).
249
250The first argument is the numerical tag, the second is the (decoded) value
251that has been tagged.
252
253The filter function should return either exactly one value, which will
254replace the tagged value in the decoded data structure, or no values,
255which will result in default handling, which currently means the decoder
256creates a C<CBOR::XS::Tagged> object to hold the tag and the value.
257
258When the filter is cleared (the default state), the default filter
259function, C<CBOR::XS::default_filter>, is used. This function simply looks
260up the tag in the C<%CBOR::XS::FILTER> hash. If an entry exists it must be
261a code reference that is called with tag and value, and is responsible for
262decoding the value. If no entry exists, it returns no values.
263
264Example: decode all tags not handled internally into CBOR::XS::Tagged
265objects, with no other special handling (useful when working with
266potentially "unsafe" CBOR data).
267
268 CBOR::XS->new->filter (sub { })->decode ($cbor_data);
269
270Example: provide a global filter for tag 1347375694, converting the value
271into some string form.
272
273 $CBOR::XS::FILTER{1347375694} = sub {
274 my ($tag, $value);
275
276 "tag 1347375694 value $value"
277 };
234 278
235=item $cbor_data = $cbor->encode ($perl_scalar) 279=item $cbor_data = $cbor->encode ($perl_scalar)
236 280
237Converts the given Perl data structure (a scalar value) to its CBOR 281Converts the given Perl data structure (a scalar value) to its CBOR
238representation. 282representation.
… …
279CBOR integers become (numeric) perl scalars. On perls without 64 bit 323CBOR integers become (numeric) perl scalars. On perls without 64 bit
280support, 64 bit integers will be truncated or otherwise corrupted. 324support, 64 bit integers will be truncated or otherwise corrupted.
281 325
282=item byte strings 326=item byte strings
283 327
284Byte strings will become octet strings in Perl (the byte values 0..255 328Byte strings will become octet strings in Perl (the Byte values 0..255
285will simply become characters of the same value in Perl). 329will simply become characters of the same value in Perl).
286 330
287=item UTF-8 strings 331=item UTF-8 strings
288 332
289UTF-8 strings in CBOR will be decoded, i.e. the UTF-8 octets will be 333UTF-8 strings in CBOR will be decoded, i.e. the UTF-8 octets will be
… …
307C<Types:Serialiser::false> and C<Types::Serialiser::error>, 351C<Types:Serialiser::false> and C<Types::Serialiser::error>,
308respectively. They are overloaded to act almost exactly like the numbers 352respectively. They are overloaded to act almost exactly like the numbers
309C<1> and C<0> (for true and false) or to throw an exception on access (for 353C<1> and C<0> (for true and false) or to throw an exception on access (for
310error). See the L<Types::Serialiser> manpage for details. 354error). See the L<Types::Serialiser> manpage for details.
311 355
312=item CBOR tag 256 (perl object) 356=item tagged values
313 357
314The tag value C<256> (TODO: pending iana registration) will be used
315to deserialise a Perl object serialised with C<FREEZE>. See L<OBJECT
316SERIALISATION>, below, for details.
317
318=item CBOR tag 55799 (magic header)
319
320The tag 55799 is ignored (this tag implements the magic header).
321
322=item other CBOR tags
323
324Tagged items consists of a numeric tag and another CBOR value. Tags not 358Tagged items consists of a numeric tag and another CBOR value.
325handled internally are currently converted into a L<CBOR::XS::Tagged>
326object, which is simply a blessed array reference consisting of the
327numeric tag value followed by the (decoded) CBOR value.
328 359
329In the future, support for user-supplied conversions might get added. 360See L<TAG HANDLING AND EXTENSIONS> and the description of C<< ->filter >>
361for details.
330 362
331=item anything else 363=item anything else
332 364
333Anything else (e.g. unsupported simple values) will raise a decoding 365Anything else (e.g. unsupported simple values) will raise a decoding
334error. 366error.
… …
377if you want. 409if you want.
378 410
379=item other blessed objects 411=item other blessed objects
380 412
381Other blessed objects are serialised via C<TO_CBOR> or C<FREEZE>. See 413Other blessed objects are serialised via C<TO_CBOR> or C<FREEZE>. See
382L<OBJECT SERIALISATION>, below, for details. 414L<TAG HANDLING AND EXTENSIONS> for specific classes handled by this
415module, and L<OBJECT SERIALISATION> for generic object serialisation.
383 416
384=item simple scalars 417=item simple scalars
385 418
386TODO
387Simple Perl scalars (any scalar that is not a reference) are the most 419Simple Perl scalars (any scalar that is not a reference) are the most
388difficult objects to encode: CBOR::XS will encode undefined scalars as 420difficult objects to encode: CBOR::XS will encode undefined scalars as
389CBOR null values, scalars that have last been used in a string context 421CBOR null values, scalars that have last been used in a string context
390before encoding as CBOR strings, and anything else as number value: 422before encoding as CBOR strings, and anything else as number value:
391 423
392 # dump as number 424 # dump as number
393 encode_cbor [2] # yields [2] 425 encode_cbor [2] # yields [2]
394 encode_cbor [-3.0e17] # yields [-3e+17] 426 encode_cbor [-3.0e17] # yields [-3e+17]
395 my $value = 5; encode_cbor [$value] # yields [5] 427 my $value = 5; encode_cbor [$value] # yields [5]
396 428
397 # used as string, so dump as string 429 # used as string, so dump as string (either byte or text)
398 print $value; 430 print $value;
399 encode_cbor [$value] # yields ["5"] 431 encode_cbor [$value] # yields ["5"]
400 432
401 # undef becomes null 433 # undef becomes null
402 encode_cbor [undef] # yields [null] 434 encode_cbor [undef] # yields [null]
… …
405 437
406 my $x = 3.1; # some variable containing a number 438 my $x = 3.1; # some variable containing a number
407 "$x"; # stringified 439 "$x"; # stringified
408 $x .= ""; # another, more awkward way to stringify 440 $x .= ""; # another, more awkward way to stringify
409 print $x; # perl does it for you, too, quite often 441 print $x; # perl does it for you, too, quite often
442
443You can force whether a string ie encoded as byte or text string by using
444C<utf8::upgrade> and C<utf8::downgrade>):
445
446 utf8::upgrade $x; # encode $x as text string
447 utf8::downgrade $x; # encode $x as byte string
448
449Perl doesn't define what operations up- and downgrade strings, so if the
450difference between byte and text is important, you should up- or downgrade
451your string as late as possible before encoding.
410 452
411You can force the type to be a CBOR number by numifying it: 453You can force the type to be a CBOR number by numifying it:
412 454
413 my $x = "3"; # some variable containing a string 455 my $x = "3"; # some variable containing a string
414 $x += 0; # numify it, ensuring it will be dumped as a number 456 $x += 0; # numify it, ensuring it will be dumped as a number
… …
633and extensions. If a tag is not mentioned here and no additional filters 675and extensions. If a tag is not mentioned here and no additional filters
634are provided for it, then the default handling applies (creating a 676are provided for it, then the default handling applies (creating a
635CBOR::XS::Tagged object on decoding, and only encoding the tag when 677CBOR::XS::Tagged object on decoding, and only encoding the tag when
636explicitly requested). 678explicitly requested).
637 679
680Tags not handled specifically are currently converted into a
681L<CBOR::XS::Tagged> object, which is simply a blessed array reference
682consisting of the numeric tag value followed by the (decoded) CBOR value.
683
638Future versions of this module reserve the right to special case 684Future versions of this module reserve the right to special case
639additional tags (such as base64url). 685additional tags (such as base64url).
640 686
641=head2 ENFORCED TAGS 687=head2 ENFORCED TAGS
642 688
643These tags are always handled when decoding, and their handling cannot be 689These tags are always handled when decoding, and their handling cannot be
644overriden by the user. 690overriden by the user.
645 691
646=over 4 692=over 4
647 693
648=item <unassigned> (perl-object, L<http://cbor.schmorp.de/perl-object>) 694=item 26 (perl-object, L<http://cbor.schmorp.de/perl-object>)
649 695
650These tags are automatically created for serialisable objects using the 696These tags are automatically created (and decoded) for serialisable
651C<FREEZE/THAW> methods (the L<Types::Serialier> object serialisation 697objects using the C<FREEZE/THAW> methods (the L<Types::Serialier> object
652protocol). 698serialisation protocol). See L<OBJECT SERIALISATION> for details.
653 699
654=item <unassigned>, <unassigned> (sharable, sharedref, L <http://cbor.schmorp.de/value-sharing>) 700=item 28, 29 (sharable, sharedref, L <http://cbor.schmorp.de/value-sharing>)
655 701
656These tags are automatically decoded when encountered, resulting in 702These tags are automatically decoded when encountered, resulting in
657shared values in the decoded object. They are only encoded, however, when 703shared values in the decoded object. They are only encoded, however, when
658C<allow_sharable> is enabled. 704C<allow_sharable> is enabled.
659 705
660=item <unassigned>, <unassigned> (stringref-namespace, stringref, L <http://cbor.schmorp.de/stringref>) 706=item 256, 25 (stringref-namespace, stringref, L <http://cbor.schmorp.de/stringref>)
661 707
662These tags are automatically decoded when encountered. They are only 708These tags are automatically decoded when encountered. They are only
663encoded, however, when C<allow_stringref> is enabled. 709encoded, however, when C<pack_strings> is enabled.
664 710
665=item 22098 (indirection, L<http://cbor.schmorp.de/indirection>) 711=item 22098 (indirection, L<http://cbor.schmorp.de/indirection>)
666 712
667This tag is automatically generated when a reference are encountered (with 713This tag is automatically generated when a reference are encountered (with
668the exception of hash and array refernces). It is converted to a reference 714the exception of hash and array refernces). It is converted to a reference
… …
673This value is not generated on encoding (unless explicitly requested by 719This value is not generated on encoding (unless explicitly requested by
674the user), and is simply ignored when decoding. 720the user), and is simply ignored when decoding.
675 721
676=back 722=back
677 723
678=head2 OPTIONAL TAGS 724=head2 NON-ENFORCED TAGS
679 725
680These tags have default filters provided when decoding. Their handling can 726These tags have default filters provided when decoding. Their handling can
681be overriden by changing the C<%CBOR::XS::FILTER> entry for the tag, or by 727be overriden by changing the C<%CBOR::XS::FILTER> entry for the tag, or by
682providing a custom C<filter> function when decoding. 728providing a custom C<filter> callback when decoding.
683 729
684When they result in decoding into a specific Perl class, the module 730When they result in decoding into a specific Perl class, the module
685usually provides a corresponding C<TO_CBOR> method as well. 731usually provides a corresponding C<TO_CBOR> method as well.
686 732
687When any of these need to load additional modules that are not part of the 733When any of these need to load additional modules that are not part of the

Diff Legend

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