view release on metacpan or  search on metacpan

README  view on Meta::CPAN

        options on how to deal with this: basically, you can choose between
        throwing an exception, encoding the reference as if it weren't
        blessed, use the objects overloaded stringification method or
        provide your own serializer method.

    simple scalars
        Simple Perl scalars (any scalar that is not a reference) are the
        most difficult objects to encode: Cpanel::JSON::XS will encode
        undefined scalars or inf/nan as JSON "null" values and other scalars
        to either number or string in non-deterministic way which may be
        affected or changed by Perl version or any other loaded Perl module.

        If you want to have stable and deterministic types in JSON encoder
        then use Cpanel::JSON::XS::Type.

        Alternative way for deterministic types is to use "type_all_string"
        method when all perl scalars are encoded to JSON strings.

        Non-deterministic behavior is following: 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, but the two representations are for the same number
           print $value;
           encode_json [$value]                 # yields [5]

           # used as different string (non-matching dual-var)
           my $str = '0 but true';
           my $num = 1 + $str;
           encode_json [$num, $str]           # yields [1,"0 but true"]

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

           # inf or nan becomes null, unless you answered
           # "Do you want to handle inf/nan as strings" with yes
           encode_json [9**9**9]                # 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.

        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 thus null is returned instead. Optionally you can
        configure it to stringify inf and nan values.

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

   SERIALIZATION
    What happens when "Cpanel::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, "Cpanel::JSON::XS" uses the Types::Serialiser object
        serialization 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 serialize, and the second
        argument being the constant string "JSON" to distinguish it from
        other serializers.

        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, $serializer) = @_;

              ($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 serialized. The fact that these values
        originally were URI objects is lost.

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

    3. "convert_blessed" is enabled and the object has a stringification