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.30 by root, Sat Nov 30 16:19:59 2013 UTC vs.
Revision 1.34 by root, Sun Dec 1 14:48:00 2013 UTC

… …
48Regarding compactness, C<CBOR::XS>-encoded data structures are usually 48Regarding compactness, C<CBOR::XS>-encoded data structures are usually
49about 20% smaller than the same data encoded as (compact) JSON or 49about 20% smaller than the same data encoded as (compact) JSON or
50L<Storable>. 50L<Storable>.
51 51
52In addition to the core CBOR data format, this module implements a 52In addition to the core CBOR data format, this module implements a
53number of extensions, to support cyclic and shared data structures (see 53number of extensions, to support cyclic and shared data structures
54C<allow_sharing>), string deduplication (see C<pack_strings>) and scalar 54(see C<allow_sharing> and C<allow_cycles>), string deduplication (see
55references (always enabled). 55C<pack_strings>) and scalar references (always enabled).
56 56
57The 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
58is 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.
59 59
60See 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
… …
64 64
65package CBOR::XS; 65package CBOR::XS;
66 66
67use common::sense; 67use common::sense;
68 68
69our $VERSION = '1.0'; 69our $VERSION = 1.11;
70our @ISA = qw(Exporter); 70our @ISA = qw(Exporter);
71 71
72our @EXPORT = qw(encode_cbor decode_cbor); 72our @EXPORT = qw(encode_cbor decode_cbor);
73 73
74use Exporter; 74use Exporter;
… …
180reference to the earlier value. 180reference to the earlier value.
181 181
182This means that such values will only be encoded once, and will not result 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 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 184sharing extension. This also makes it possible to encode cyclic data
185structures. 185structures (which need C<allow_cycles> to ne enabled to be decoded by this
186module).
186 187
187It is recommended to leave it off unless you know your 188It is recommended to leave it off unless you know your
188communication partner supports the value sharing extensions to CBOR 189communication partner supports the value sharing extensions to CBOR
189(L<http://cbor.schmorp.de/value-sharing>), as without decoder support, the 190(L<http://cbor.schmorp.de/value-sharing>), as without decoder support, the
190resulting data structure might be unusable. 191resulting data structure might be unusable.
191 192
192Detecting shared values incurs a runtime overhead when values are encoded 193Detecting shared values incurs a runtime overhead when values are encoded
193that have a reference counter large than one, and might unnecessarily 194that have a reference counter large than one, and might unnecessarily
194increase the encoded size, as potentially shared values are encode as 195increase the encoded size, as potentially shared values are encode as
195sharable whether or not they are actually shared. 196shareable whether or not they are actually shared.
196 197
197At the moment, only targets of references can be shared (e.g. scalars, 198At the moment, only targets of references can be shared (e.g. scalars,
198arrays or hashes pointed to by a reference). Weirder constructs, such as 199arrays 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 200an 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 201not impossible to create in Perl, are not supported (this is the same as
… …
205structures cannot be encoded in this mode. 206structures cannot be encoded in this mode.
206 207
207This option does not affect C<decode> in any way - shared values and 208This option does not affect C<decode> in any way - shared values and
208references will always be decoded properly if present. 209references will always be decoded properly if present.
209 210
211=item $cbor = $cbor->allow_cycles ([$enable])
212
213=item $enabled = $cbor->get_allow_cycles
214
215If C<$enable> is true (or missing), then C<decode> will happily decode
216self-referential (cyclic) data structures. By default these will not be
217decoded, as they need manual cleanup to avoid memory leaks, so code that
218isn't prepared for this will not leak memory.
219
220If C<$enable> is false (the default), then C<decode> will throw an error
221when it encounters a self-referential/cyclic data structure.
222
223This option does not affect C<encode> in any way - shared values and
224references will always be decoded properly if present.
225
210=item $cbor = $cbor->pack_strings ([$enable]) 226=item $cbor = $cbor->pack_strings ([$enable])
211 227
212=item $enabled = $cbor->get_pack_strings 228=item $enabled = $cbor->get_pack_strings
213 229
214If C<$enable> is true (or missing), then C<encode> will try not to encode 230If C<$enable> is true (or missing), then C<encode> will try not to encode
… …
225If C<$enable> is false (the default), then C<encode> will encode strings 241If C<$enable> is false (the default), then C<encode> will encode strings
226the standard CBOR way. 242the standard CBOR way.
227 243
228This option does not affect C<decode> in any way - string references will 244This option does not affect C<decode> in any way - string references will
229always be decoded properly if present. 245always be decoded properly if present.
246
247=item $cbor = $cbor->validate_utf8 ([$enable])
248
249=item $enabled = $cbor->get_validate_utf8
250
251If C<$enable> is true (or missing), then C<decode> will validate that
252elements (text strings) containing UTF-8 data in fact contain valid UTF-8
253data (instead of blindly accepting it). This validation obviously takes
254extra time during decoding.
255
256The concept of "valid UTF-8" used is perl's concept, which is a superset
257of the official UTF-8.
258
259If C<$enable> is false (the default), then C<decode> will blindly accept
260UTF-8 data, marking them as valid UTF-8 in the resulting data structure
261regardless of whether thats true or not.
262
263Perl isn't too happy about corrupted UTF-8 in strings, but should
264generally not crash or do similarly evil things. Extensions might be not
265so forgiving, so it's recommended to turn on this setting if you receive
266untrusted CBOR.
267
268This option does not affect C<encode> in any way - strings that are
269supposedly valid UTF-8 will simply be dumped into the resulting CBOR
270string without checking whether that is, in fact, true or not.
230 271
231=item $cbor = $cbor->filter ([$cb->($tag, $value)]) 272=item $cbor = $cbor->filter ([$cb->($tag, $value)])
232 273
233=item $cb_or_undef = $cbor->get_filter 274=item $cb_or_undef = $cbor->get_filter
234 275
… …
704 745
705These tags are automatically created (and decoded) for serialisable 746These tags are automatically created (and decoded) for serialisable
706objects using the C<FREEZE/THAW> methods (the L<Types::Serialier> object 747objects using the C<FREEZE/THAW> methods (the L<Types::Serialier> object
707serialisation protocol). See L<OBJECT SERIALISATION> for details. 748serialisation protocol). See L<OBJECT SERIALISATION> for details.
708 749
709=item 28, 29 (sharable, sharedref, L <http://cbor.schmorp.de/value-sharing>) 750=item 28, 29 (shareable, sharedref, L <http://cbor.schmorp.de/value-sharing>)
710 751
711These tags are automatically decoded when encountered, resulting in 752These tags are automatically decoded when encountered (and they do not
753result in a cyclic data structure, see C<allow_cycles>), resulting in
712shared values in the decoded object. They are only encoded, however, when 754shared values in the decoded object. They are only encoded, however, when
713C<allow_sharable> is enabled. 755C<allow_sharing> is enabled.
756
757Not all shared values can be successfully decoded: values that reference
758themselves will I<currently> decode as C<undef> (this is not the same
759as a reference pointing to itself, which will be represented as a value
760that contains an indirect reference to itself - these will be decoded
761properly).
762
763Note that considerably more shared value data structures can be decoded
764than will be encoded - currently, only values pointed to by references
765will be shared, others will not. While non-reference shared values can be
766generated in Perl with some effort, they were considered too unimportant
767to be supported in the encoder. The decoder, however, will decode these
768values as shared values.
714 769
715=item 256, 25 (stringref-namespace, stringref, L <http://cbor.schmorp.de/stringref>) 770=item 256, 25 (stringref-namespace, stringref, L <http://cbor.schmorp.de/stringref>)
716 771
717These tags are automatically decoded when encountered. They are only 772These tags are automatically decoded when encountered. They are only
718encoded, however, when C<pack_strings> is enabled. 773encoded, however, when C<pack_strings> is enabled.

Diff Legend

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