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.26 by root, Thu Nov 28 12:11:06 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.
… …
640These tags are always handled when decoding, and their handling cannot be 679These tags are always handled when decoding, and their handling cannot be
641overriden by the user. 680overriden by the user.
642 681
643=over 4 682=over 4
644 683
645=item <unassigned> (perl-object, L<http://cbor.schmorp.de/perl-object>) 684=item 26 (perl-object, L<http://cbor.schmorp.de/perl-object>)
646 685
647These tags are automatically created (and decoded) for serialisable 686These tags are automatically created (and decoded) for serialisable
648objects using the C<FREEZE/THAW> methods (the L<Types::Serialier> object 687objects using the C<FREEZE/THAW> methods (the L<Types::Serialier> object
649serialisation protocol). See L<OBJECT SERIALISATION> for details. 688serialisation protocol). See L<OBJECT SERIALISATION> for details.
650 689
651=item <unassigned>, <unassigned> (sharable, sharedref, L <http://cbor.schmorp.de/value-sharing>) 690=item 28, 29 (sharable, sharedref, L <http://cbor.schmorp.de/value-sharing>)
652 691
653These tags are automatically decoded when encountered, resulting in 692These tags are automatically decoded when encountered, resulting in
654shared values in the decoded object. They are only encoded, however, when 693shared values in the decoded object. They are only encoded, however, when
655C<allow_sharable> is enabled. 694C<allow_sharable> is enabled.
656 695
657=item <unassigned>, <unassigned> (stringref-namespace, stringref, L <http://cbor.schmorp.de/stringref>) 696=item 256, 25 (stringref-namespace, stringref, L <http://cbor.schmorp.de/stringref>)
658 697
659These tags are automatically decoded when encountered. They are only 698These tags are automatically decoded when encountered. They are only
660encoded, however, when C<allow_stringref> is enabled. 699encoded, however, when C<pack_strings> is enabled.
661 700
662=item 22098 (indirection, L<http://cbor.schmorp.de/indirection>) 701=item 22098 (indirection, L<http://cbor.schmorp.de/indirection>)
663 702
664This tag is automatically generated when a reference are encountered (with 703This tag is automatically generated when a reference are encountered (with
665the exception of hash and array refernces). It is converted to a reference 704the exception of hash and array refernces). It is converted to a reference
… …
670This value is not generated on encoding (unless explicitly requested by 709This value is not generated on encoding (unless explicitly requested by
671the user), and is simply ignored when decoding. 710the user), and is simply ignored when decoding.
672 711
673=back 712=back
674 713
675=head2 OPTIONAL TAGS 714=head2 NON-ENFORCED TAGS
676 715
677These tags have default filters provided when decoding. Their handling can 716These 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 717be overriden by changing the C<%CBOR::XS::FILTER> entry for the tag, or by
679providing a custom C<filter> function when decoding. 718providing a custom C<filter> callback when decoding.
680 719
681When they result in decoding into a specific Perl class, the module 720When they result in decoding into a specific Perl class, the module
682usually provides a corresponding C<TO_CBOR> method as well. 721usually provides a corresponding C<TO_CBOR> method as well.
683 722
684When any of these need to load additional modules that are not part of the 723When any of these need to load additional modules that are not part of the

Diff Legend

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