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.23 by root, Fri Nov 22 16:00:30 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;
… …
186as an array, is referenced multiple times), but instead will emit a 186as an array, is referenced multiple times), but instead will emit a
187reference to the earlier value. 187reference to the earlier value.
188 188
189This 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
190in 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
191sharing extension. 191sharing extension. This also makes it possible to encode cyclic data
192structures.
192 193
193It is recommended to leave it off unless you know your 194It is recommended to leave it off unless you know your
194communication partner supports the value sharing extensions to CBOR 195communication partner supports the value sharing extensions to CBOR
195(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.
196 198
197Detecting shared values incurs a runtime overhead when values are encoded 199Detecting shared values incurs a runtime overhead when values are encoded
198that have a reference counter large than one, and might unnecessarily 200that have a reference counter large than one, and might unnecessarily
199increase the encoded size, as potentially shared values are encode as 201increase the encoded size, as potentially shared values are encode as
200sharable whether or not they are actually shared. 202sharable whether or not they are actually shared.
201 203
202At 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,
203arrays or hashes pointed to by a reference). Weirder constructs, such as 205arrays or hashes pointed to by a reference). Weirder constructs, such as
204an 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
205not 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
206for L<Storable>). 208with L<Storable>).
207 209
208If C<$enable> is false (the default), then C<encode> will encode 210If C<$enable> is false (the default), then C<encode> will encode shared
209exception 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.
210 213
211This 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
212references will always be decoded properly if present. 215references will always be decoded properly if present.
213 216
214=item $cbor = $cbor->allow_stringref ([$enable]) 217=item $cbor = $cbor->pack_strings ([$enable])
215 218
216=item $enabled = $cbor->get_allow_stringref 219=item $enabled = $cbor->get_pack_strings
217 220
218If 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
219the 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
220instead. 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
221also 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
2222-4 times as high as without). 2252-4 times as high as without).
223 226
224It is recommended to leave it off unless you know your 227It is recommended to leave it off unless you know your
225communications partner supports the stringref extension to CBOR 228communications partner supports the stringref extension to CBOR
226(http://cbor.schmorp.de/stringref). 229(L<http://cbor.schmorp.de/stringref>), as without decoder support, the
230resulting data structure might not be usable.
227 231
228If C<$enable> is false (the default), then C<encode> will encode 232If C<$enable> is false (the default), then C<encode> will encode strings
229exception when it encounters anything it cannot encode as CBOR. 233the standard CBOR way.
230 234
231This 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
232always be decoded properly if present. 236always be decoded properly if present.
233 237
234=item $cbor = $cbor->filter ([$cb->($tag, $value)]) 238=item $cbor = $cbor->filter ([$cb->($tag, $value)])
235 239
236=item $cb_or_undef = $cbor->get_filter 240=item $cb_or_undef = $cbor->get_filter
237 241
238TODO 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 };
239 278
240=item $cbor_data = $cbor->encode ($perl_scalar) 279=item $cbor_data = $cbor->encode ($perl_scalar)
241 280
242Converts the given Perl data structure (a scalar value) to its CBOR 281Converts the given Perl data structure (a scalar value) to its CBOR
243representation. 282representation.
… …
284CBOR integers become (numeric) perl scalars. On perls without 64 bit 323CBOR integers become (numeric) perl scalars. On perls without 64 bit
285support, 64 bit integers will be truncated or otherwise corrupted. 324support, 64 bit integers will be truncated or otherwise corrupted.
286 325
287=item byte strings 326=item byte strings
288 327
289Byte 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
290will simply become characters of the same value in Perl). 329will simply become characters of the same value in Perl).
291 330
292=item UTF-8 strings 331=item UTF-8 strings
293 332
294UTF-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
… …
385 # dump as number 424 # dump as number
386 encode_cbor [2] # yields [2] 425 encode_cbor [2] # yields [2]
387 encode_cbor [-3.0e17] # yields [-3e+17] 426 encode_cbor [-3.0e17] # yields [-3e+17]
388 my $value = 5; encode_cbor [$value] # yields [5] 427 my $value = 5; encode_cbor [$value] # yields [5]
389 428
390 # used as string, so dump as string 429 # used as string, so dump as string (either byte or text)
391 print $value; 430 print $value;
392 encode_cbor [$value] # yields ["5"] 431 encode_cbor [$value] # yields ["5"]
393 432
394 # undef becomes null 433 # undef becomes null
395 encode_cbor [undef] # yields [null] 434 encode_cbor [undef] # yields [null]
… …
398 437
399 my $x = 3.1; # some variable containing a number 438 my $x = 3.1; # some variable containing a number
400 "$x"; # stringified 439 "$x"; # stringified
401 $x .= ""; # another, more awkward way to stringify 440 $x .= ""; # another, more awkward way to stringify
402 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.
403 452
404You 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:
405 454
406 my $x = "3"; # some variable containing a string 455 my $x = "3"; # some variable containing a string
407 $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
… …
640These tags are always handled when decoding, and their handling cannot be 689These tags are always handled when decoding, and their handling cannot be
641overriden by the user. 690overriden by the user.
642 691
643=over 4 692=over 4
644 693
645=item <unassigned> (perl-object, L<http://cbor.schmorp.de/perl-object>) 694=item 26 (perl-object, L<http://cbor.schmorp.de/perl-object>)
646 695
647These tags are automatically created (and decoded) for serialisable 696These tags are automatically created (and decoded) for serialisable
648objects using the C<FREEZE/THAW> methods (the L<Types::Serialier> object 697objects using the C<FREEZE/THAW> methods (the L<Types::Serialier> object
649serialisation protocol). See L<OBJECT SERIALISATION> for details. 698serialisation protocol). See L<OBJECT SERIALISATION> for details.
650 699
651=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>)
652 701
653These tags are automatically decoded when encountered, resulting in 702These tags are automatically decoded when encountered, resulting in
654shared values in the decoded object. They are only encoded, however, when 703shared values in the decoded object. They are only encoded, however, when
655C<allow_sharable> is enabled. 704C<allow_sharable> is enabled.
656 705
657=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>)
658 707
659These tags are automatically decoded when encountered. They are only 708These tags are automatically decoded when encountered. They are only
660encoded, however, when C<allow_stringref> is enabled. 709encoded, however, when C<pack_strings> is enabled.
661 710
662=item 22098 (indirection, L<http://cbor.schmorp.de/indirection>) 711=item 22098 (indirection, L<http://cbor.schmorp.de/indirection>)
663 712
664This tag is automatically generated when a reference are encountered (with 713This tag is automatically generated when a reference are encountered (with
665the 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
… …
670This value is not generated on encoding (unless explicitly requested by 719This value is not generated on encoding (unless explicitly requested by
671the user), and is simply ignored when decoding. 720the user), and is simply ignored when decoding.
672 721
673=back 722=back
674 723
675=head2 OPTIONAL TAGS 724=head2 NON-ENFORCED TAGS
676 725
677These tags have default filters provided when decoding. Their handling can 726These tags have default filters provided when decoding. Their handling can
678be 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
679providing a custom C<filter> function when decoding. 728providing a custom C<filter> callback when decoding.
680 729
681When they result in decoding into a specific Perl class, the module 730When they result in decoding into a specific Perl class, the module
682usually provides a corresponding C<TO_CBOR> method as well. 731usually provides a corresponding C<TO_CBOR> method as well.
683 732
684When 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