view release on metacpan or  search on metacpan

README  view on Meta::CPAN

        and 1, which get turned into "false" and "true" atoms in JSON.

        Since "JSON::XS" 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.

    blessed objects
        Blessed objects are not directly representable in JSON, but
        "JSON::XS" allows various ways of handling objects. See "OBJECT
        SERIALISATION", below, for details.

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

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

           # used as string, so dump as string
           print $value;
           encode_json [$value]                 # yields ["5"]

           # undef becomes null
           encode_json [undef]                  # yields [null]

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

           my $x = 3.1; # some variable containing a number
           "$x";        # stringified
           $x .= "";    # another, more awkward way to stringify
           print $x;    # perl does it for you, too, quite often

        You can force the type to be a JSON number by numifying it:

           my $x = "3"; # some variable containing a string
           $x += 0;     # numify it, ensuring it will be dumped as a number
           $x *= 1;     # same thing, the choice is yours.

        You can not currently force the type in other, less obscure, ways.
        Tell me if you need this capability (but don't forget to explain why
        it's needed :).

        Note that numerical precision has the same meaning as under Perl (so
        binary to decimal conversion follows the same rules as in Perl,
        which can differ to other languages). Also, your perl interpreter
        might expose extensions to the floating point numbers of your
        platform, such as infinities or NaN's - these cannot be represented
        in JSON, and it is an error to pass those in.

  OBJECT SERIALISATION
    As JSON cannot directly represent Perl objects, you have to choose
    between a pure JSON representation (without the ability to deserialise
    the object automatically again), and a nonstandard extension to the JSON
    syntax, tagged values.

   SERIALISATION
    What happens when "JSON::XS" encounters a Perl object depends on the
    "allow_blessed", "convert_blessed" and "allow_tags" settings, which are
    used in this order:

    1. "allow_tags" is enabled and the object has a "FREEZE" method.
        In this case, "JSON::XS" uses the Types::Serialiser object
        serialisation protocol to create a tagged JSON value, using a
        nonstandard extension to the JSON syntax.

        This works by invoking the "FREEZE" method on the object, with the
        first argument being the object to serialise, and the second
        argument being the constant string "JSON" to distinguish it from
        other serialisers.

        The "FREEZE" method can return any number of values (i.e. zero or
        more). These values and the paclkage/classname of the object will
        then be encoded as a tagged JSON value in the following format:

           ("classname")[FREEZE return values...]

        e.g.:

           ("URI")["http://www.google.com/"]
           ("MyDate")[2013,10,29]
           ("ImageData::JPEG")["Z3...VlCg=="]

        For example, the hypothetical "My::Object" "FREEZE" method might use
        the objects "type" and "id" members to encode the object:

           sub My::Object::FREEZE {
              my ($self, $serialiser) = @_;

              ($self->{type}, $self->{id})
           }

    2. "convert_blessed" is enabled and the object has a "TO_JSON" method.
        In this case, the "TO_JSON" method of the object is invoked in
        scalar context. It must return a single scalar that can be directly
        encoded into JSON. This scalar replaces the object in the JSON text.

        For example, the following "TO_JSON" method will convert all URI
        objects to JSON strings when serialised. The fact that these values
        originally were URI objects is lost.

           sub URI::TO_JSON {
              my ($uri) = @_;
              $uri->as_string
           }

    3. "allow_blessed" is enabled.
        The object will be serialised as a JSON null value.