view release on metacpan or  search on metacpan

script/rsybak  view on Meta::CPAN

#    $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 VERSION
#
#    2.93
#
#=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 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 L<JSON::XS> by default, and when JSON::XS is not available,
#this module 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:
#
#=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
#that may contain objects, you usually need to look into the structure
#and replace objects with alternative non-blessed values, or enable