view release on metacpan or  search on metacpan

XS.pm  view on Meta::CPAN

throwing an exception, encoding the reference as if it weren't
blessed, use the objects overloaded stringification method or provide
your own serializer method.

=item 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 C<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 L<Cpanel::JSON::XS::Type>.

Alternative way for deterministic types is to use C<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.

=back

=head2 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.

=head3 SERIALIZATION

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

=over 4

=item 1. C<allow_tags> is enabled and the object has a C<FREEZE> method.

In this case, C<Cpanel::JSON::XS> uses the L<Types::Serialiser> object
serialization protocol to create a tagged JSON value, using a nonstandard
extension to the JSON syntax.

This works by invoking the C<FREEZE> method on the object, with the first
argument being the object to serialize, and the second argument being the
constant string C<JSON> to distinguish it from other serializers.

The C<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 C<My::Object> C<FREEZE> method might use the
objects C<type> and C<id> members to encode the object:

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

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

=item 2. C<convert_blessed> is enabled and the object has a C<TO_JSON> method.

In this case, the C<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 C<TO_JSON> method will convert all L<URI>
objects to JSON strings when serialized. The fact that these values
originally were L<URI> objects is lost.