view release on metacpan or  search on metacpan

README  view on Meta::CPAN

    $cbor = $cbor->allow_sharing ([$enable])
    $enabled = $cbor->get_allow_sharing
        If $enable is true (or missing), then "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 "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
        (<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 *same*
        string, which are hard but not impossible to create in Perl, are not
        supported (this is the same as with Storable).

        If $enable is false (the default), then "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 "decode" in any way - shared values and
        references will always be decoded properly if present.

    $cbor = $cbor->allow_cycles ([$enable])
    $enabled = $cbor->get_allow_cycles
        If $enable is true (or missing), then "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 $enable is false (the default), then "decode" will throw an error
        when it encounters a self-referential/cyclic data structure.

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

    $cbor = $cbor->allow_weak_cycles ([$enable])
    $enabled = $cbor->get_allow_weak_cycles
        This works like "allow_cycles" in that it allows the resulting data
        structures to contain cycles, but unlike "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 "encode" in any way - shared values and
        references will always be encoded properly if present.

    $cbor = $cbor->forbid_objects ([$enable])
    $enabled = $cbor->get_forbid_objects
        Disables the use of the object serialiser protocol.

        If $enable is true (or missing), then "encode" will will throw an
        exception when it encounters perl objects that would be encoded
        using the perl-object tag (26). When "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 "CBOR::XC::Tagged"
        object).

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

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

    $cbor = $cbor->pack_strings ([$enable])
    $enabled = $cbor->get_pack_strings
        If $enable is true (or missing), then "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
        (<http://cbor.schmorp.de/stringref>), as without decoder support,
        the resulting data structure might not be usable.

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

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

    $cbor = $cbor->text_keys ([$enable])
    $enabled = $cbor->get_text_keys
        If $enabled is true (or missing), then "encode" will encode all perl
        hash keys as CBOR text strings/UTF-8 string, upgrading them as
        needed.

        If $enable is false (the default), then "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 "decode" in any way.

        This option is useful for interoperability with CBOR decoders that
        don't treat byte strings as a form of text. It is especially useful
        as Perl gives very little control over hash keys.