view release on metacpan or  search on metacpan

bin/perlbrewise-spec  view on Meta::CPAN

     encode_json [!1, !0]      # yields [false,true]
  
  =item blessed objects
  
  Blessed objects are not directly representable in JSON, but
  C<Cpanel::JSON::XS> allows various optional ways of handling
  objects. See L<OBJECT SERIALIZATION>, below, for details.
  
  See the C<allow_blessed> and C<convert_blessed> methods on various
  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.
  
  =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, 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.