view release on metacpan or  search on metacpan

README  view on Meta::CPAN

    Otherwise, the "THAW" method is invoked with the classname as first
    argument, the constant string "JSON" as second argument, and all the
    values from the JSON array (the values originally returned by the
    "FREEZE" method) as remaining arguments.

    The method must then return the object. While technically you can return
    any Perl scalar, you might have to enable the "enable_nonref" setting to
    make that work in all cases, so better return an actual blessed
    reference.

    As an example, let's implement a "THAW" function that regenerates the
    "My::Object" from the "FREEZE" example earlier:

       sub My::Object::THAW {
          my ($class, $serializer, $type, $id) = @_;

          $class->new (type => $type, id => $id)
       }

    See the "SECURITY CONSIDERATIONS" section below. Allowing external json
    objects being deserialized to perl objects is usually a very bad idea.

ENCODING/CODESET FLAG NOTES
    The interested reader might have seen a number of flags that signify
    encodings or codesets - "utf8", "latin1", "binary" and "ascii". There
    seems to be some confusion on what these do, so here is a short
    comparison:

    "utf8" controls whether the JSON text created by "encode" (and expected
    by "decode") is UTF-8 encoded or not, while "latin1" and "ascii" only
    control whether "encode" escapes character values outside their
    respective codeset range. Neither of these flags conflict with each
    other, although some combinations make less sense than others.

    Care has been taken to make all flags symmetrical with respect to
    "encode" and "decode", that is, texts encoded with any combination of
    these flag values will be correctly decoded when the same flags are used
    - in general, if you use different flag settings while encoding vs. when
    decoding you likely have a bug somewhere.

    Below comes a verbose discussion of these flags. Note that a "codeset"
    is simply an abstract set of character-codepoint pairs, while an
    encoding takes those codepoint numbers and *encodes* them, in our case
    into octets. Unicode is (among other things) a codeset, UTF-8 is an
    encoding, and ISO-8859-1 (= latin 1) and ASCII are both codesets *and*
    encodings at the same time, which can be confusing.

    "utf8" flag disabled
        When "utf8" is disabled (the default), then "encode"/"decode"
        generate and expect Unicode strings, that is, characters with high
        ordinal Unicode values (> 255) will be encoded as such characters,
        and likewise such characters are decoded as-is, no changes to them
        will be done, except "(re-)interpreting" them as Unicode codepoints
        or Unicode characters, respectively (to Perl, these are the same
        thing in strings unless you do funny/weird/dumb stuff).

        This is useful when you want to do the encoding yourself (e.g. when
        you want to have UTF-16 encoded JSON texts) or when some other layer
        does the encoding for you (for example, when printing to a terminal
        using a filehandle that transparently encodes to UTF-8 you certainly
        do NOT want to UTF-8 encode your data first and have Perl encode it
        another time).

    "utf8" flag enabled
        If the "utf8"-flag is enabled, "encode"/"decode" will encode all
        characters using the corresponding UTF-8 multi-byte sequence, and
        will expect your input strings to be encoded as UTF-8, that is, no
        "character" of the input string must have any value > 255, as UTF-8
        does not allow that.

        The "utf8" flag therefore switches between two modes: disabled means
        you will get a Unicode string in Perl, enabled means you get an
        UTF-8 encoded octet/binary string in Perl.

    "latin1", "binary" or "ascii" flags enabled
        With "latin1" (or "ascii") enabled, "encode" will escape characters
        with ordinal values > 255 (> 127 with "ascii") and encode the
        remaining characters as specified by the "utf8" flag. With "binary"
        enabled, ordinal values > 255 are illegal.

        If "utf8" is disabled, then the result is also correctly encoded in
        those character sets (as both are proper subsets of Unicode, meaning
        that a Unicode string with all character values < 256 is the same
        thing as a ISO-8859-1 string, and a Unicode string with all
        character values < 128 is the same thing as an ASCII string in
        Perl).

        If "utf8" is enabled, you still get a correct UTF-8-encoded string,
        regardless of these flags, just some more characters will be escaped
        using "\uXXXX" then before.

        Note that ISO-8859-1-*encoded* strings are not compatible with UTF-8
        encoding, while ASCII-encoded strings are. That is because the
        ISO-8859-1 encoding is NOT a subset of UTF-8 (despite the ISO-8859-1
        *codeset* being a subset of Unicode), while ASCII is.

        Surprisingly, "decode" will ignore these flags and so treat all
        input values as governed by the "utf8" flag. If it is disabled, this
        allows you to decode ISO-8859-1- and ASCII-encoded strings, as both
        strict subsets of Unicode. If it is enabled, you can correctly
        decode UTF-8 encoded strings.

        So neither "latin1", "binary" nor "ascii" are incompatible with the
        "utf8" flag - they only govern when the JSON output engine escapes a
        character or not.

        The main use for "latin1" or "binary" is to relatively efficiently
        store binary data as JSON, at the expense of breaking compatibility
        with most JSON decoders.

        The main use for "ascii" is to force the output to not contain
        characters with values > 127, which means you can interpret the
        resulting string as UTF-8, ISO-8859-1, ASCII, KOI8-R or most about
        any character set and 8-bit-encoding, and still get the same data
        structure back. This is useful when your channel for JSON transfer
        is not 8-bit clean or the encoding might be mangled in between (e.g.
        in mail), and works because ASCII is a proper subset of most 8-bit
        and multibyte encodings in use in the world.

  JSON and ECMAscript