view release on metacpan or  search on metacpan

README  view on Meta::CPAN

NAME
  JSON - JSON (JavaScript Object Notation) encoder/decoder

SYNOPSIS
   use JSON; # imports encode_json, decode_json, to_json and from_json.
 
   # simple and fast interfaces (expect/generate UTF-8)
 
   $utf8_encoded_json_text = encode_json $perl_hash_or_arrayref;
   $perl_hash_or_arrayref  = decode_json $utf8_encoded_json_text;
 
   # OO-interface
 
   $json = JSON->new->allow_nonref;
 
   $json_text   = $json->encode( $perl_scalar );
   $perl_scalar = $json->decode( $json_text );
 
   $pretty_printed = $json->pretty->encode( $perl_scalar ); # pretty-printing

VERSION
      2.93

DESCRIPTION
  This module is a thin wrapper for JSON::XS-compatible modules with
  a few additional features. All the backend modules convert a Perl
  data structure to a JSON text as of RFC4627 (which we know is
  obsolete but we still stick to; see below for an option to support
  part of RFC7159) and vice versa. This module uses JSON::XS by
  default, and when JSON::XS is not available, this module falls
  back on JSON::PP, which is in the Perl core since 5.14. If
  JSON::PP is not available either, this module then falls back on
  JSON::backportPP (which is actually JSON::PP in a different .pm
  file) bundled in the same distribution as this module. You can
  also explicitly specify to use Cpanel::JSON::XS, a fork of
  JSON::XS by Reini Urban.

  All these backend modules have slight incompatibilities between
  them, including extra features that other modules don't support,
  but as long as you use only common features (most important ones
  are described below), migration from backend to backend should be
  reasonably easy. For details, see each backend module you use.

CHOOSING BACKEND
  This module respects an environmental variable called
  "PERL_JSON_BACKEND" when it decides a backend module to use. If
  this environmental variable is not set, it tries to load JSON::XS,
  and if JSON::XS is not available, it falls back on JSON::PP, and
  then JSON::backportPP if JSON::PP is not available either.

  If you always don't want it to fall back on pure perl modules, set
  the variable like this ("export" may be "setenv", "set" and the
  likes, depending on your environment):

    > export PERL_JSON_BACKEND=JSON::XS

  If you prefer Cpanel::JSON::XS to JSON::XS, then:

    > export PERL_JSON_BACKEND=Cpanel::JSON::XS,JSON::XS,JSON::PP

  You may also want to set this variable at the top of your test
  files, in order not to be bothered with incompatibilities between
  backends (you need to wrap this in "BEGIN", and set before
  actually "use"-ing JSON module, as it decides its backend as soon
  as it's loaded):

    BEGIN { $ENV{PERL_JSON_BACKEND}='JSON::backportPP'; }
    use JSON;

USING OPTIONAL FEATURES
  There are a few options you can set when you "use" this module:

  -support_by_pp
         BEGIN { $ENV{PERL_JSON_BACKEND} = 'JSON::XS' }
   
         use JSON -support_by_pp;
   
         my $json = JSON->new;
         # escape_slash is for JSON::PP only.
         $json->allow_nonref->escape_slash->encode("/");

      With this option, this module loads its pure perl backend
      along with its XS backend (if available), and lets the XS
      backend to watch if you set a flag only JSON::PP supports.
      When you do, the internal JSON::XS object is replaced with a
      newly created JSON::PP object with the setting copied from the
      XS object, so that you can use JSON::PP flags (and its slower
      "decode"/"encode" methods) from then on. In other words, this
      is not something that allows you to hook JSON::XS to change
      its behavior while keeping its speed. JSON::XS and JSON::PP
      objects are quite different (JSON::XS object is a blessed
      scalar reference, while JSON::PP object is a blessed hash
      reference), and can't share their internals.

      To avoid needless overhead (by copying settings), you are
      advised not to use this option and just to use JSON::PP
      explicitly when you need JSON::PP features.

  -convert_blessed_universally
         use JSON -convert_blessed_universally;

         my $json = JSON->new->allow_nonref->convert_blessed;
         my $object = bless {foo => 'bar'}, 'Foo';
         $json->encode($object); # => {"foo":"bar"}

      JSON::XS-compatible backend modules don't encode blessed
      objects by default (except for their boolean values, which are
      typically blessed JSON::PP::Boolean objects). If you need to
      encode a data structure that may contain objects, you usually
      need to look into the structure and replace objects with
      alternative non-blessed values, or enable "convert_blessed"
      and provide a "TO_JSON" method for each object's (base) class