view release on metacpan or  search on metacpan

README  view on Meta::CPAN

        Resets the incremental decoder. This throws away any saved state, so
        that subsequent calls to "incr_parse" or "incr_parse_multiple" start
        to parse a new CBOR value from the beginning of the $buffer again.

        This method can be called at any time, but it *must* be called if
        you want to change your $buffer or there was a decoding error and
        you want to reuse the $cbor object for future incremental parsings.

MAPPING
    This section describes how CBOR::XS maps Perl values to CBOR values and
    vice versa. These mappings are designed to "do the right thing" in most
    circumstances automatically, preserving round-tripping characteristics
    (what you put in comes out as something equivalent).

    For the more enlightened: note that in the following descriptions,
    lowercase *perl* refers to the Perl interpreter, while uppercase *Perl*
    refers to the abstract Perl language itself.

  CBOR -> PERL
    integers
        CBOR integers become (numeric) perl scalars. On perls without 64 bit
        support, 64 bit integers will be truncated or otherwise corrupted.

    byte strings
        Byte strings will become octet strings in Perl (the Byte values
        0..255 will simply become characters of the same value in Perl).

    UTF-8 strings
        UTF-8 strings in CBOR will be decoded, i.e. the UTF-8 octets will be
        decoded into proper Unicode code points. At the moment, the validity
        of the UTF-8 octets will not be validated - corrupt input will
        result in corrupted Perl strings.

    arrays, maps
        CBOR arrays and CBOR maps will be converted into references to a
        Perl array or hash, respectively. The keys of the map will be
        stringified during this process.

    null
        CBOR null becomes "undef" in Perl.

    true, false, undefined
        These CBOR values become "Types:Serialiser::true",
        "Types:Serialiser::false" and "Types::Serialiser::error",
        respectively. They are overloaded to act almost exactly like the
        numbers 1 and 0 (for true and false) or to throw an exception on
        access (for error). See the Types::Serialiser manpage for details.

    tagged values
        Tagged items consists of a numeric tag and another CBOR value.

        See "TAG HANDLING AND EXTENSIONS" and the description of "->filter"
        for details on which tags are handled how.

    anything else
        Anything else (e.g. unsupported simple values) will raise a decoding
        error.

  PERL -> CBOR
    The mapping from Perl to CBOR is slightly more difficult, as Perl is a
    typeless language. That means this module can only guess which CBOR type
    is meant by a perl value.

    hash references
        Perl hash references become CBOR maps. As there is no inherent
        ordering in hash keys (or CBOR maps), they will usually be encoded
        in a pseudo-random order. This order can be different each time a
        hash is encoded.

        Currently, tied hashes will use the indefinite-length format, while
        normal hashes will use the fixed-length format.

    array references
        Perl array references become fixed-length CBOR arrays.

    other references
        Other unblessed references will be represented using the indirection
        tag extension (tag value 22098,
        <http://cbor.schmorp.de/indirection>). CBOR decoders are guaranteed
        to be able to decode these values somehow, by either "doing the
        right thing", decoding into a generic tagged object, simply ignoring
        the tag, or something else.

    CBOR::XS::Tagged objects
        Objects of this type must be arrays consisting of a single "[tag,
        value]" pair. The (numerical) tag will be encoded as a CBOR tag, the
        value will be encoded as appropriate for the value. You must use
        "CBOR::XS::tag" to create such objects.

    Types::Serialiser::true, Types::Serialiser::false,
    Types::Serialiser::error
        These special values become CBOR true, CBOR false and CBOR undefined
        values, respectively.

    other blessed objects
        Other blessed objects are serialised via "TO_CBOR" or "FREEZE". See
        "TAG HANDLING AND EXTENSIONS" for specific classes handled by this
        module, and "OBJECT SERIALISATION" for generic object serialisation.

    simple scalars
        Simple Perl scalars (any scalar that is not a reference) are the
        most difficult objects to encode: CBOR::XS will encode undefined
        scalars as CBOR null values, scalars that have last been used in a
        string context before encoding as CBOR strings, and anything else as
        number value:

           # dump as number
           encode_cbor [2]                      # yields [2]
           encode_cbor [-3.0e17]                # yields [-3e+17]
           my $value = 5; encode_cbor [$value]  # yields [5]

           # used as string, so dump as string (either byte or text)
           print $value;
           encode_cbor [$value]                 # yields ["5"]

           # undef becomes null
           encode_cbor [undef]                  # yields [null]

        You can force the type to be a CBOR string by stringifying it:

           my $x = 3.1; # some variable containing a number