view release on metacpan or  search on metacpan

README  view on Meta::CPAN

  other references
      Other unblessed references are generally not allowed and will
      cause an exception to be thrown, except for references to the
      integers 0 and 1, which get turned into "false" and "true"
      atoms in JSON. You can also use "JSON::false" and "JSON::true"
      to improve readability.

         encode_json [\0,JSON::true]      # yields [false,true]

  JSON::true, JSON::false, JSON::null
      These special values 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: this module 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 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 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 for Perl objects, this module only supports a pure JSON
  representation (without the ability to deserialise the object
  automatically again).

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

  1. "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
         }

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

  3. none of the above
      If none of the settings are enabled or the respective methods
      are missing, this module throws an exception.

ENCODING/CODESET FLAG NOTES
  This section is taken from JSON::XS.

  The interested reader might have seen a number of flags that
  signify encodings or codesets - "utf8", "latin1" and "ascii".
  There seems to be some confusion on what these do, so here is a
  short comparison:

  "utf8" controls whether the JSON text created by "encode" (and
  expected by "decode") is UTF-8 encoded or not, while "latin1" and
  "ascii" only control whether "encode" escapes character values
  outside their respective codeset range. Neither of these flags
  conflict with each other, although some combinations make less
  sense than others.

  Care has been taken to make all flags symmetrical with respect to
  "encode" and "decode", that is, texts encoded with any combination
  of these flag values will be correctly decoded when the same flags
  are used - in general, if you use different flag settings while
  encoding vs. when decoding you likely have a bug somewhere.

  Below comes a verbose discussion of these flags. Note that a
  "codeset" is simply an abstract set of character-codepoint pairs,
  while an encoding takes those codepoint numbers and *encodes*