view release on metacpan or  search on metacpan

XS.pm  view on Meta::CPAN

If C<$enable> is true (or missing), then C<encode> will not double-encode
values that have been referenced before (e.g. when the same object, such
as an array, is referenced multiple times), but instead will emit a
reference to the earlier value.

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 (which need C<allow_cycles> to be 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
(L<http://cbor.schmorp.de/value-sharing>), as without decoder support, the
resulting data structure might be unusable.

Detecting shared values incurs a runtime overhead when values are encoded
that have a reference counter larger than one, and might unnecessarily
increase the encoded size, as potentially shared values are encoded as
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
an array with multiple "copies" of the I<same> string, which are hard but
not impossible to create in Perl, are not supported (this is the same as
with L<Storable>).

If C<$enable> is false (the default), then C<encode> will encode shared
data structures repeatedly, unsharing them in the process. Cyclic data
structures cannot be encoded in this mode.

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 encoded properly if present.

=item $cbor = $cbor->allow_weak_cycles ([$enable])

=item $enabled = $cbor->get_allow_weak_cycles

This works like C<allow_cycles> in that it allows the resulting data
structures to contain cycles, but unlike C<allow_cycles>, those cyclic
rreferences will be weak. That means that code that recurrsively walks
the data structure must be prepared with cycles, but at least not special
precautions must be implemented to free these data structures.

Only those references leading to actual cycles will be weakened - other
references, e.g. when the same hash or arrray is referenced multiple times
in an arrray, will be normal references.

This option does not affect C<encode> in any way - shared values and
references will always be encoded properly if present.

=item $cbor = $cbor->forbid_objects ([$enable])

=item $enabled = $cbor->get_forbid_objects

Disables the use of the object serialiser protocol.

If C<$enable> is true (or missing), then C<encode> will will throw an
exception when it encounters perl objects that would be encoded using the
perl-object tag (26). When C<decode> encounters such tags, it will fall
back to the general filter/tagged logic as if this were an unknown tag (by
default resulting in a C<CBOR::XC::Tagged> object).

If C<$enable> is false (the default), then C<encode> will use the
L<Types::Serialiser> object serialisation protocol to serialise objects
into perl-object tags, and C<decode> will do the same to decode such tags.

See L<SECURITY CONSIDERATIONS>, below, for more info on why forbidding this
protocol can be useful.

=item $cbor = $cbor->pack_strings ([$enable])

=item $enabled = $cbor->get_pack_strings

If C<$enable> is true (or missing), then C<encode> will try not to encode
the same string twice, but will instead encode a reference to the string
instead. Depending on your data format, this can save a lot of space, but
also results in a very large runtime overhead (expect encoding times to be
2-4 times as high as without).

It is recommended to leave it off unless you know your
communications partner supports the stringref extension to CBOR
(L<http://cbor.schmorp.de/stringref>), as without decoder support, the
resulting data structure might not be usable.

If C<$enable> is false (the default), then C<encode> will encode strings
the standard CBOR way.

This option does not affect C<decode> in any way - string references will
always be decoded properly if present.

=item $cbor = $cbor->text_keys ([$enable])

=item $enabled = $cbor->get_text_keys

If C<$enabled> is true (or missing), then C<encode> will encode all
perl hash keys as CBOR text strings/UTF-8 string, upgrading them as needed.

If C<$enable> is false (the default), then C<encode> will encode hash keys
normally - upgraded perl strings (strings internally encoded as UTF-8) as
CBOR text strings, and downgraded perl strings as CBOR byte strings.

This option does not affect C<decode> in any way.

This option is useful for interoperability with CBOR decoders that don't