view release on metacpan or  search on metacpan

lib/JSON.pm  view on Meta::CPAN

            }
            $pp_method->(@_);
        };
    }

    $JSON::DEBUG and Carp::carp("set -support_by_pp mode.");
}

1;
__END__

=head1 NAME

JSON - JSON (JavaScript Object Notation) encoder/decoder

=head1 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

=head1 DESCRIPTION

This module is a thin wrapper for L<JSON::XS>-compatible modules with a few
additional features. All the backend modules convert a Perl data structure
to a JSON text and vice versa. This module uses L<JSON::XS> by default,
and when JSON::XS is not available, falls back on L<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 L<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.

=head1 CHOOSING BACKEND

This module respects an environmental variable called C<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 (C<export> may be C<setenv>, C<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 C<BEGIN>, and set before actually C<use>-ing JSON module, as it decides
its backend as soon as it's loaded):

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

=head1 USING OPTIONAL FEATURES

There are a few options you can set when you C<use> this module.
These historical options are only kept for backward compatibility,
and should not be used in a new application.

=over

=item -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
C<decode>/C<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.

=item -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