view release on metacpan or  search on metacpan

README  view on Meta::CPAN

        This option does not affect "decode" in any way, and it is
        recommended to leave it off unless you know your communications
        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.

    $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 = $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::XS->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
        serialised Perl hash.

        Typical names for the single object key are "__class_whatever__", or
        "$__dollars_are_rarely_used__$" or "}ugly_brace_placement", or even
        things like "__class_md5sum(classname)__", to reduce the risk of
        clashing with real hashes.

        Example, decode JSON objects of the form "{ "__widget__" => <id> }"
        into the corresponding $WIDGET{<id>} object:

           # return whatever is in $WIDGET{5}:
           JSON::XS
              ->new