ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/CBOR-XS/README
(Generate patch)

Comparing CBOR-XS/README (file contents):
Revision 1.11 by root, Sat Nov 30 18:42:27 2013 UTC vs.
Revision 1.16 by root, Mon Feb 8 04:37:12 2016 UTC

… …
178 code that isn't prepared for this will not leak memory. 178 code that isn't prepared for this will not leak memory.
179 179
180 If $enable is false (the default), then "decode" will throw an error 180 If $enable is false (the default), then "decode" will throw an error
181 when it encounters a self-referential/cyclic data structure. 181 when it encounters a self-referential/cyclic data structure.
182 182
183 FUTURE DIRECTION: the motivation behind this option is to avoid
184 *real* cycles - future versions of this module might chose to decode
185 cyclic data structures using weak references when this option is
186 off, instead of throwing an error.
187
183 This option does not affect "encode" in any way - shared values and 188 This option does not affect "encode" in any way - shared values and
184 references will always be decoded properly if present. 189 references will always be encoded properly if present.
185 190
186 $cbor = $cbor->pack_strings ([$enable]) 191 $cbor = $cbor->pack_strings ([$enable])
187 $enabled = $cbor->get_pack_strings 192 $enabled = $cbor->get_pack_strings
188 If $enable is true (or missing), then "encode" will try not to 193 If $enable is true (or missing), then "encode" will try not to
189 encode the same string twice, but will instead encode a reference to 194 encode the same string twice, but will instead encode a reference to
… …
200 the standard CBOR way. 205 the standard CBOR way.
201 206
202 This option does not affect "decode" in any way - string references 207 This option does not affect "decode" in any way - string references
203 will always be decoded properly if present. 208 will always be decoded properly if present.
204 209
210 $cbor = $cbor->validate_utf8 ([$enable])
211 $enabled = $cbor->get_validate_utf8
212 If $enable is true (or missing), then "decode" will validate that
213 elements (text strings) containing UTF-8 data in fact contain valid
214 UTF-8 data (instead of blindly accepting it). This validation
215 obviously takes extra time during decoding.
216
217 The concept of "valid UTF-8" used is perl's concept, which is a
218 superset of the official UTF-8.
219
220 If $enable is false (the default), then "decode" will blindly accept
221 UTF-8 data, marking them as valid UTF-8 in the resulting data
222 structure regardless of whether thats true or not.
223
224 Perl isn't too happy about corrupted UTF-8 in strings, but should
225 generally not crash or do similarly evil things. Extensions might be
226 not so forgiving, so it's recommended to turn on this setting if you
227 receive untrusted CBOR.
228
229 This option does not affect "encode" in any way - strings that are
230 supposedly valid UTF-8 will simply be dumped into the resulting CBOR
231 string without checking whether that is, in fact, true or not.
232
205 $cbor = $cbor->filter ([$cb->($tag, $value)]) 233 $cbor = $cbor->filter ([$cb->($tag, $value)])
206 $cb_or_undef = $cbor->get_filter 234 $cb_or_undef = $cbor->get_filter
207 Sets or replaces the tagged value decoding filter (when $cb is 235 Sets or replaces the tagged value decoding filter (when $cb is
208 specified) or clears the filter (if no argument or "undef" is 236 specified) or clears the filter (if no argument or "undef" is
209 provided). 237 provided).
… …
263 protocol and you need to know where the first CBOR string ends amd 291 protocol and you need to know where the first CBOR string ends amd
264 the next one starts. 292 the next one starts.
265 293
266 CBOR::XS->new->decode_prefix ("......") 294 CBOR::XS->new->decode_prefix ("......")
267 => ("...", 3) 295 => ("...", 3)
296
297 INCREMENTAL PARSING
298 In some cases, there is the need for incremental parsing of JSON texts.
299 While this module always has to keep both CBOR text and resulting Perl
300 data structure in memory at one time, it does allow you to parse a CBOR
301 stream incrementally, using a similar to using "decode_prefix" to see if
302 a full CBOR object is available, but is much more efficient.
303
304 It basically works by parsing as much of a CBOR string as possible - if
305 the CBOR data is not complete yet, the pasrer will remember where it
306 was, to be able to restart when more data has been accumulated. Once
307 enough data is available to either decode a complete CBOR value or raise
308 an error, a real decode will be attempted.
309
310 A typical use case would be a network protocol that consists of sending
311 and receiving CBOR-encoded messages. The solution that works with CBOR
312 and about anything else is by prepending a length to every CBOR value,
313 so the receiver knows how many octets to read. More compact (and
314 slightly slower) would be to just send CBOR values back-to-back, as
315 "CBOR::XS" knows where a CBOR value ends, and doesn't need an explicit
316 length.
317
318 The following methods help with this:
319
320 @decoded = $cbor->incr_parse ($buffer)
321 This method attempts to decode exactly one CBOR value from the
322 beginning of the given $buffer. The value is removed from the
323 $buffer on success. When $buffer doesn't contain a complete value
324 yet, it returns nothing. Finally, when the $buffer doesn't start
325 with something that could ever be a valid CBOR value, it raises an
326 exception, just as "decode" would. In the latter case the decoder
327 state is undefined and must be reset before being able to parse
328 further.
329
330 This method modifies the $buffer in place. When no CBOR value can be
331 decoded, the decoder stores the current string offset. On the next
332 call, continues decoding at the place where it stopped before. For
333 this to make sense, the $buffer must begin with the same octets as
334 on previous unsuccessful calls.
335
336 You can call this method in scalar context, in which case it either
337 returns a decoded value or "undef". This makes it impossible to
338 distinguish between CBOR null values (which decode to "undef") and
339 an unsuccessful decode, which is often acceptable.
340
341 @decoded = $cbor->incr_parse_multiple ($buffer)
342 Same as "incr_parse", but attempts to decode as many CBOR values as
343 possible in one go, instead of at most one. Calls to "incr_parse"
344 and "incr_parse_multiple" can be interleaved.
345
346 $cbor->incr_reset
347 Resets the incremental decoder. This throws away any saved state, so
348 that subsequent calls to "incr_parse" or "incr_parse_multiple" start
349 to parse a new CBOR value from the beginning of the $buffer again.
350
351 This method can be caled at any time, but it *must* be called if you
352 want to change your $buffer or there was a decoding error and you
353 want to reuse the $cbor object for future incremental parsings.
268 354
269MAPPING 355MAPPING
270 This section describes how CBOR::XS maps Perl values to CBOR values and 356 This section describes how CBOR::XS maps Perl values to CBOR values and
271 vice versa. These mappings are designed to "do the right thing" in most 357 vice versa. These mappings are designed to "do the right thing" in most
272 circumstances automatically, preserving round-tripping characteristics 358 circumstances automatically, preserving round-tripping characteristics
… …
608 26 (perl-object, <http://cbor.schmorp.de/perl-object>) 694 26 (perl-object, <http://cbor.schmorp.de/perl-object>)
609 These tags are automatically created (and decoded) for serialisable 695 These tags are automatically created (and decoded) for serialisable
610 objects using the "FREEZE/THAW" methods (the Types::Serialier object 696 objects using the "FREEZE/THAW" methods (the Types::Serialier object
611 serialisation protocol). See "OBJECT SERIALISATION" for details. 697 serialisation protocol). See "OBJECT SERIALISATION" for details.
612 698
613 28, 29 (shareable, sharedref, L <http://cbor.schmorp.de/value-sharing>) 699 28, 29 (shareable, sharedref, <http://cbor.schmorp.de/value-sharing>)
614 These tags are automatically decoded when encountered (and they do 700 These tags are automatically decoded when encountered (and they do
615 not result in a cyclic data structure, see "allow_cycles"), 701 not result in a cyclic data structure, see "allow_cycles"),
616 resulting in shared values in the decoded object. They are only 702 resulting in shared values in the decoded object. They are only
617 encoded, however, when "allow_sharing" is enabled. 703 encoded, however, when "allow_sharing" is enabled.
618 704
… …
627 references will be shared, others will not. While non-reference 713 references will be shared, others will not. While non-reference
628 shared values can be generated in Perl with some effort, they were 714 shared values can be generated in Perl with some effort, they were
629 considered too unimportant to be supported in the encoder. The 715 considered too unimportant to be supported in the encoder. The
630 decoder, however, will decode these values as shared values. 716 decoder, however, will decode these values as shared values.
631 717
632 256, 25 (stringref-namespace, stringref, L 718 256, 25 (stringref-namespace, stringref,
633 <http://cbor.schmorp.de/stringref>) 719 <http://cbor.schmorp.de/stringref>)
634 These tags are automatically decoded when encountered. They are only 720 These tags are automatically decoded when encountered. They are only
635 encoded, however, when "pack_strings" is enabled. 721 encoded, however, when "pack_strings" is enabled.
636 722
637 22098 (indirection, <http://cbor.schmorp.de/indirection>) 723 22098 (indirection, <http://cbor.schmorp.de/indirection>)
… …
653 739
654 When any of these need to load additional modules that are not part of 740 When any of these need to load additional modules that are not part of
655 the perl core distribution (e.g. URI), it is (currently) up to the user 741 the perl core distribution (e.g. URI), it is (currently) up to the user
656 to provide these modules. The decoding usually fails with an exception 742 to provide these modules. The decoding usually fails with an exception
657 if the required module cannot be loaded. 743 if the required module cannot be loaded.
744
745 0, 1 (date/time string, seconds since the epoch)
746 These tags are decoded into Time::Piece objects. The corresponding
747 "Time::Piece::TO_CBOR" method always encodes into tag 1 values
748 currently.
749
750 The Time::Piece API is generally surprisingly bad, and fractional
751 seconds are only accidentally kept intact, so watch out. On the plus
752 side, the module comes with perl since 5.10, which has to count for
753 something.
658 754
659 2, 3 (positive/negative bignum) 755 2, 3 (positive/negative bignum)
660 These tags are decoded into Math::BigInt objects. The corresponding 756 These tags are decoded into Math::BigInt objects. The corresponding
661 "Math::BigInt::TO_CBOR" method encodes "small" bigints into normal 757 "Math::BigInt::TO_CBOR" method encodes "small" bigints into normal
662 CBOR integers, and others into positive/negative CBOR bignums. 758 CBOR integers, and others into positive/negative CBOR bignums.
… …
743 839
744 Strict mode and canonical mode are not implemented. 840 Strict mode and canonical mode are not implemented.
745 841
746LIMITATIONS ON PERLS WITHOUT 64-BIT INTEGER SUPPORT 842LIMITATIONS ON PERLS WITHOUT 64-BIT INTEGER SUPPORT
747 On perls that were built without 64 bit integer support (these are rare 843 On perls that were built without 64 bit integer support (these are rare
748 nowadays, even on 32 bit architectures), support for any kind of 64 bit 844 nowadays, even on 32 bit architectures, as all major Perl distributions
845 are built with 64 bit integer support), support for any kind of 64 bit
749 integer in CBOR is very limited - most likely, these 64 bit values will 846 integer in CBOR is very limited - most likely, these 64 bit values will
750 be truncated, corrupted, or otherwise not decoded correctly. This also 847 be truncated, corrupted, or otherwise not decoded correctly. This also
751 includes string, array and map sizes that are stored as 64 bit integers. 848 includes string, array and map sizes that are stored as 64 bit integers.
752 849
753THREADS 850THREADS

Diff Legend

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