--- CBOR-XS/XS.pm	2013/11/30 15:23:59	1.29
+++ CBOR-XS/XS.pm	2013/12/01 14:48:00	1.34
@@ -50,9 +50,9 @@
 L<Storable>.
 
 In addition to the core CBOR data format, this module implements a
-number of extensions, to support cyclic and shared data structures (see
-C<allow_sharing>), string deduplication (see C<pack_strings>) and scalar
-references (always enabled).
+number of extensions, to support cyclic and shared data structures
+(see C<allow_sharing> and C<allow_cycles>), string deduplication (see
+C<pack_strings>) and scalar references (always enabled).
 
 The primary goal of this module is to be I<correct> and the secondary goal
 is to be I<fast>. To reach the latter goal it was written in C.
@@ -66,7 +66,7 @@
 
 use common::sense;
 
-our $VERSION = '1.0';
+our $VERSION = 1.11;
 our @ISA = qw(Exporter);
 
 our @EXPORT = qw(encode_cbor decode_cbor);
@@ -182,7 +182,8 @@
 This means that such values will only be encoded once, and will not result
 in a deep cloning of the value on decode, in decoders supporting the value
 sharing extension. This also makes it possible to encode cyclic data
-structures.
+structures (which need C<allow_cycles> to ne enabled to be decoded by this
+module).
 
 It is recommended to leave it off unless you know your
 communication partner supports the value sharing extensions to CBOR
@@ -192,7 +193,7 @@
 Detecting shared values incurs a runtime overhead when values are encoded
 that have a reference counter large than one, and might unnecessarily
 increase the encoded size, as potentially shared values are encode as
-sharable whether or not they are actually shared.
+shareable whether or not they are actually shared.
 
 At the moment, only targets of references can be shared (e.g. scalars,
 arrays or hashes pointed to by a reference). Weirder constructs, such as
@@ -207,6 +208,21 @@
 This option does not affect C<decode> in any way - shared values and
 references will always be decoded properly if present.
 
+=item $cbor = $cbor->allow_cycles ([$enable])
+
+=item $enabled = $cbor->get_allow_cycles
+
+If C<$enable> is true (or missing), then C<decode> will happily decode
+self-referential (cyclic) data structures. By default these will not be
+decoded, as they need manual cleanup to avoid memory leaks, so code that
+isn't prepared for this will not leak memory.
+
+If C<$enable> is false (the default), then C<decode> will throw an error
+when it encounters a self-referential/cyclic data structure.
+
+This option does not affect C<encode> in any way - shared values and
+references will always be decoded properly if present.
+
 =item $cbor = $cbor->pack_strings ([$enable])
 
 =item $enabled = $cbor->get_pack_strings
@@ -228,6 +244,31 @@
 This option does not affect C<decode> in any way - string references will
 always be decoded properly if present.
 
+=item $cbor = $cbor->validate_utf8 ([$enable])
+
+=item $enabled = $cbor->get_validate_utf8
+
+If C<$enable> is true (or missing), then C<decode> will validate that
+elements (text strings) containing UTF-8 data in fact contain valid UTF-8
+data (instead of blindly accepting it). This validation obviously takes
+extra time during decoding.
+
+The concept of "valid UTF-8" used is perl's concept, which is a superset
+of the official UTF-8.
+
+If C<$enable> is false (the default), then C<decode> will blindly accept
+UTF-8 data, marking them as valid UTF-8 in the resulting data structure
+regardless of whether thats true or not.
+
+Perl isn't too happy about corrupted UTF-8 in strings, but should
+generally not crash or do similarly evil things. Extensions might be not
+so forgiving, so it's recommended to turn on this setting if you receive
+untrusted CBOR.
+
+This option does not affect C<encode> in any way - strings that are
+supposedly valid UTF-8 will simply be dumped into the resulting CBOR
+string without checking whether that is, in fact, true or not.
+
 =item $cbor = $cbor->filter ([$cb->($tag, $value)])
 
 =item $cb_or_undef = $cbor->get_filter
@@ -706,11 +747,25 @@
 objects using the C<FREEZE/THAW> methods (the L<Types::Serialier> object
 serialisation protocol). See L<OBJECT SERIALISATION> for details.
 
-=item 28, 29 (sharable, sharedref, L <http://cbor.schmorp.de/value-sharing>)
+=item 28, 29 (shareable, sharedref, L <http://cbor.schmorp.de/value-sharing>)
 
-These tags are automatically decoded when encountered, resulting in
+These tags are automatically decoded when encountered (and they do not
+result in a cyclic data structure, see C<allow_cycles>), resulting in
 shared values in the decoded object. They are only encoded, however, when
-C<allow_sharable> is enabled.
+C<allow_sharing> is enabled.
+
+Not all shared values can be successfully decoded: values that reference
+themselves will I<currently> decode as C<undef> (this is not the same
+as a reference pointing to itself, which will be represented as a value
+that contains an indirect reference to itself - these will be decoded
+properly).
+
+Note that considerably more shared value data structures can be decoded
+than will be encoded - currently, only values pointed to by references
+will be shared, others will not. While non-reference shared values can be
+generated in Perl with some effort, they were considered too unimportant
+to be supported in the encoder. The decoder, however, will decode these
+values as shared values.
 
 =item 256, 25 (stringref-namespace, stringref, L <http://cbor.schmorp.de/stringref>)
 
@@ -888,6 +943,15 @@
 Strict mode and canonical mode are not implemented.
 
 
+=head1 LIMITATIONS ON PERLS WITHOUT 64-BIT INTEGER SUPPORT
+
+On perls that were built without 64 bit integer support (these are rare
+nowadays, even on 32 bit architectures), support for any kind of 64 bit
+integer in CBOR is very limited - most likely, these 64 bit values will
+be truncated, corrupted, or otherwise not decoded correctly. This also
+includes string, array and map sizes that are stored as 64 bit integers.
+
+
 =head1 THREADS
 
 This module is I<not> guaranteed to be thread safe and there are no