view release on metacpan or  search on metacpan

README  view on Meta::CPAN

        partner.

    $json = $json->allow_blessed ([$enable])
    $enabled = $json->get_allow_blessed
        See "OBJECT SERIALISATION" for details.

        If $enable is true (or missing), then the "encode" method will not
        barf when it encounters a blessed reference that it cannot convert
        otherwise. Instead, a JSON "null" value is encoded instead of the
        object.

        If $enable is false (the default), then "encode" will throw an
        exception when it encounters a blessed object that it cannot convert
        otherwise.

        This setting has no effect on "decode".

    $json = $json->convert_blessed ([$enable])
    $enabled = $json->get_convert_blessed
        See "OBJECT SERIALISATION" for details.

        If $enable is true (or missing), then "encode", upon encountering a
        blessed object, will check for the availability of the "TO_JSON"
        method on the object's class. If found, it will be called in scalar
        context and the resulting scalar will be encoded instead of the
        object.

        The "TO_JSON" method may safely call die if it wants. If "TO_JSON"
        returns other blessed objects, those will be handled in the same
        way. "TO_JSON" must take care of not causing an endless recursion
        cycle (== crash) in this case. The name of "TO_JSON" was chosen
        because other methods called by the Perl core (== not by the user of
        the object) are usually in upper case letters and to avoid
        collisions with any "to_json" function or method.

        If $enable is false (the default), then "encode" will not consider
        this type of conversion.

        This setting has no effect on "decode".

    $json = $json->allow_tags ([$enable])
    $enabled = $json->get_allow_tags
        See "OBJECT SERIALISATION" for details.

        If $enable is true (or missing), then "encode", upon encountering a
        blessed object, will check for the availability of the "FREEZE"
        method on the object's class. If found, it will be used to serialise
        the object into a nonstandard tagged JSON value (that JSON decoders
        cannot decode).

        It also causes "decode" to parse such tagged JSON values and
        deserialise them via a call to the "THAW" method.

        If $enable is false (the default), then "encode" will not consider
        this type of conversion, and tagged JSON values will cause a parse
        error in "decode", as if tags were not part of the grammar.

        This option is not compatible with "use_simdjson", and using this
        option will silently disable simdjson mode.

    $json->boolean_values ([$false, $true])
    ($false, $true) = $json->get_boolean_values
        By default, JSON booleans will be decoded as overloaded
        $Types::Serialiser::false and $Types::Serialiser::true objects.

        With this method you can specify your own boolean values for
        decoding - on decode, JSON "false" will be decoded as a copy of
        $false, and JSON "true" will be decoded as $true ("copy" here is the
        same thing as assigning a value to another variable, i.e. "$copy =
        $false").

        Calling this method without any arguments will reset the booleans to
        their default values.

        "get_boolean_values" will return both $false and $true values, or
        the empty list when they are set to the default.

    $json->core_bools([$enable])
    $enabled = $json->get_core_bools
        If $enable is true (or missing), then subsequent "decode"s will
        produce standard perl boolean values. Equivalent to calling:

            $json->boolean_values(!!0, !!1)

        "get_core_bools" will return true if this has been set. On perl 5.36
        or newer, it will also return true if the boolean values have been
        set to perl's core booleans using the boolean_values method.

        If $enable is false, the booleans are reset to their default values.

        (See also "encode_core_bools" for the encode counterpart of this.)

    $json = $json->encode_core_bools ([$enable])
    $enabled = $json->get_encode_core_bools
        If $enable is true (or missing), then subsequent "encode" operations
        will recognize Perl's special boolean values !!0 and !!1 (or
        "builtin::false" and "builtin::true") and encode them as JSON
        "false" and "true", respectively.

        Be warned though, this only works on perl 5.36 or newer. With older
        perls this option does nothing.

    $json = $json->filter_json_object ([$coderef->($hashref)])
        When $coderef is specified, it will be called from "decode" each
        time it decodes a JSON object. The only argument is a reference to
        the newly-created hash. If the code reference returns a single
        scalar (which need not be a reference), this value (or rather a copy
        of it) is inserted into the deserialised data structure. If it
        returns an empty list (NOTE: *not* "undef", which is a valid
        scalar), the original deserialised hash will be inserted. This
        setting can slow down decoding considerably.

        When $coderef is omitted or undefined, any existing callback will be
        removed and "decode" will not change the deserialised hash in any
        way.

        Example, convert all JSON objects into the integer 5:

           my $js = JSON::SIMD->new->filter_json_object (sub { 5 });
           # returns [5]
           $js->decode ('[{}]')
           # throw an exception because allow_nonref is not enabled
           # so a lone 5 is not allowed.
           $js->decode ('{"a":1, "b":2}');

    $json = $json->filter_json_single_key_object ($key [=>
    $coderef->($value)])
        Works remotely similar to "filter_json_object", but is only called
        for JSON objects having a single key named $key.

        This $coderef is called before the one specified via
        "filter_json_object", if any. It gets passed the single value in the
        JSON object. If it returns a single value, it will be inserted into
        the data structure. If it returns nothing (not even "undef" but the
        empty list), the callback from "filter_json_object" will be called
        next, as if no single-key callback were specified.

        If $coderef is omitted or undefined, the corresponding callback will
        be disabled. There can only ever be one callback for a given key.

        As this callback gets called less often then the
        "filter_json_object" one, decoding speed will not usually suffer as
        much. Therefore, single-key objects make excellent targets to
        serialise Perl objects into, especially as single-key JSON objects
        are as close to the type-tagged value concept as JSON gets (it's
        basically an ID/VALUE tuple). Of course, JSON does not support this
        in any way, so you need to make sure your data never looks like a

README  view on Meta::CPAN

    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.

  JSON -> PERL
    object
        A JSON object becomes a reference to a hash in Perl. No ordering of
        object keys is preserved (JSON does not preserve object key ordering
        itself).

    array
        A JSON array becomes a reference to an array in Perl.

    string
        A JSON string becomes a string scalar in Perl - Unicode codepoints
        in JSON are represented by the same codepoints in the Perl string,
        so no manual decoding is necessary.

    number
        A JSON number becomes either an integer, numeric (floating point) or
        string scalar in perl, depending on its range and any fractional
        parts. On the Perl level, there is no difference between those as
        Perl handles all the conversion details, but an integer may take
        slightly less memory and might represent more values exactly than
        floating point numbers.

        If the number consists of digits only, JSON::SIMD will try to
        represent it as an integer value. If that fails, it will try to
        represent it as a numeric (floating point) value if that is possible
        without loss of precision. Otherwise it will preserve the number as
        a string value (in which case you lose roundtripping ability, as the
        JSON number will be re-encoded to a JSON string).

        Numbers containing a fractional or exponential part will always be
        represented as numeric (floating point) values, possibly at a loss
        of precision (in which case you might lose perfect roundtripping
        ability, but the JSON number will still be re-encoded as a JSON
        number).

        Note that precision is not accuracy - binary floating point values
        cannot represent most decimal fractions exactly, and when converting
        from and to floating point, JSON::SIMD only guarantees precision up
        to but not including the least significant bit.

        The simdjson decoder always decodes floating point numbers as
        IEEE-754 doubles, so if Perl was built to use long doubles or
        quadmath, we fall back to the slower but more precise legacy number
        parser in order to avoid the loss of precision.

    true, false
        By default, these JSON atoms become "Types::Serialiser::true" and
        "Types::Serialiser::false", respectively. They are overloaded to act
        almost exactly like the numbers 1 and 0. You can check whether a
        scalar is a JSON boolean by using the "Types::Serialiser::is_bool"
        function (after "use Types::Serialier", of course).

        You can also use the "boolean_values" method to supply your own true
        and false values for decoding, or the "core_bools" method to decode
        to Perl's standard booleans (the special values !!0 or !!1, also
        available as the aliases "false" and "true" from the (experimental)
        "builtin" module since perl 5.36).

    null
        A JSON null atom becomes "undef" in Perl.

    shell-style comments ("# *text*")
        As a nonstandard extension to the JSON syntax that is enabled by the
        "relaxed" setting, shell-style comments are allowed. They can start
        anywhere outside strings and go till the end of the line.

    tagged values ("(*tag*)*value*").
        Another nonstandard extension to the JSON syntax, enabled with the
        "allow_tags" setting, are tagged values. In this implementation, the
        *tag* must be a perl package/class name encoded as a JSON string,
        and the *value* must be a JSON array encoding optional constructor
        arguments.

        See "OBJECT SERIALISATION", below, for details.

  PERL -> JSON
    The mapping from Perl to JSON is slightly more difficult, as Perl is a
    truly typeless language, so we can only guess which JSON type is meant
    by a Perl value.

    hash references
        Perl hash references become JSON objects. As there is no inherent
        ordering in hash keys (or JSON objects), they will usually be
        encoded in a pseudo-random order. JSON::SIMD can optionally sort the
        hash keys (determined by the *canonical* flag), so the same
        datastructure will serialise to the same JSON text (given same
        settings and version of JSON::SIMD), but this incurs a runtime
        overhead and is only rarely useful, e.g. when you want to compare
        some JSON text against another for equality.

    array references
        Perl array references become JSON arrays.

    other references
        Other unblessed references are generally not allowed and will cause
        an exception to be thrown, except for references to the integers 0
        and 1, which get turned into "false" and "true" atoms in JSON.

        Since "JSON::SIMD" uses the boolean model from Types::Serialiser,
        you can also "use Types::Serialiser" and then use
        "Types::Serialiser::false" and "Types::Serialiser::true" to improve
        readability.

           use Types::Serialiser;
           encode_json [\0, Types::Serialiser::true]      # yields [false,true]

    Types::Serialiser::true, Types::Serialiser::false
        These special values from the Types::Serialiser module become JSON
        true and JSON false values, respectively. You can also use "\1" and
        "\0" directly if you want. Also see the "builtin booleans" section
        below.

    blessed objects