summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/site/lib/JSON.pm
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl/site/lib/JSON.pm')
-rw-r--r--Master/tlpkg/tlperl/site/lib/JSON.pm1659
1 files changed, 0 insertions, 1659 deletions
diff --git a/Master/tlpkg/tlperl/site/lib/JSON.pm b/Master/tlpkg/tlperl/site/lib/JSON.pm
deleted file mode 100644
index 9170fa6925c..00000000000
--- a/Master/tlpkg/tlperl/site/lib/JSON.pm
+++ /dev/null
@@ -1,1659 +0,0 @@
-package JSON;
-
-
-use strict;
-use Carp ();
-use Exporter;
-BEGIN { @JSON::ISA = 'Exporter' }
-
-@JSON::EXPORT = qw(from_json to_json jsonToObj objToJson encode_json decode_json);
-
-BEGIN {
- $JSON::VERSION = '2.94';
- $JSON::DEBUG = 0 unless (defined $JSON::DEBUG);
- $JSON::DEBUG = $ENV{ PERL_JSON_DEBUG } if exists $ENV{ PERL_JSON_DEBUG };
-}
-
-my %RequiredVersion = (
- 'JSON::PP' => '2.27203',
- 'JSON::XS' => '2.34',
-);
-
-# XS and PP common methods
-
-my @PublicMethods = qw/
- ascii latin1 utf8 pretty indent space_before space_after relaxed canonical allow_nonref
- allow_blessed convert_blessed filter_json_object filter_json_single_key_object
- shrink max_depth max_size encode decode decode_prefix allow_unknown
-/;
-
-my @Properties = qw/
- ascii latin1 utf8 indent space_before space_after relaxed canonical allow_nonref
- allow_blessed convert_blessed shrink max_depth max_size allow_unknown
-/;
-
-my @XSOnlyMethods = qw/allow_tags/; # Currently nothing
-
-my @PPOnlyMethods = qw/
- indent_length sort_by
- allow_singlequote allow_bignum loose allow_barekey escape_slash as_nonblessed
-/; # JSON::PP specific
-
-
-# used in _load_xs and _load_pp ($INSTALL_ONLY is not used currently)
-my $_INSTALL_DONT_DIE = 1; # When _load_xs fails to load XS, don't die.
-my $_ALLOW_UNSUPPORTED = 0;
-my $_UNIV_CONV_BLESSED = 0;
-
-
-# Check the environment variable to decide worker module.
-
-unless ($JSON::Backend) {
- $JSON::DEBUG and Carp::carp("Check used worker module...");
-
- my $backend = exists $ENV{PERL_JSON_BACKEND} ? $ENV{PERL_JSON_BACKEND} : 1;
-
- if ($backend eq '1') {
- $backend = 'JSON::XS,JSON::PP';
- }
- elsif ($backend eq '0') {
- $backend = 'JSON::PP';
- }
- elsif ($backend eq '2') {
- $backend = 'JSON::XS';
- }
- $backend =~ s/\s+//g;
-
- my @backend_modules = split /,/, $backend;
- while(my $module = shift @backend_modules) {
- if ($module =~ /JSON::XS/) {
- _load_xs($module, @backend_modules ? $_INSTALL_DONT_DIE : 0);
- }
- elsif ($module =~ /JSON::PP/) {
- _load_pp($module);
- }
- elsif ($module =~ /JSON::backportPP/) {
- _load_pp($module);
- }
- else {
- Carp::croak "The value of environmental variable 'PERL_JSON_BACKEND' is invalid.";
- }
- last if $JSON::Backend;
- }
-}
-
-
-sub import {
- my $pkg = shift;
- my @what_to_export;
- my $no_export;
-
- for my $tag (@_) {
- if ($tag eq '-support_by_pp') {
- if (!$_ALLOW_UNSUPPORTED++) {
- JSON::Backend::XS
- ->support_by_pp(@PPOnlyMethods) if ($JSON::Backend->is_xs);
- }
- next;
- }
- elsif ($tag eq '-no_export') {
- $no_export++, next;
- }
- elsif ( $tag eq '-convert_blessed_universally' ) {
- my $org_encode = $JSON::Backend->can('encode');
- eval q|
- require B;
- local $^W;
- no strict 'refs';
- *{"${JSON::Backend}\::encode"} = sub {
- # only works with Perl 5.18+
- local *UNIVERSAL::TO_JSON = sub {
- my $b_obj = B::svref_2object( $_[0] );
- return $b_obj->isa('B::HV') ? { %{ $_[0] } }
- : $b_obj->isa('B::AV') ? [ @{ $_[0] } ]
- : undef
- ;
- };
- $org_encode->(@_);
- };
- | if ( !$_UNIV_CONV_BLESSED++ );
- next;
- }
- push @what_to_export, $tag;
- }
-
- return if ($no_export);
-
- __PACKAGE__->export_to_level(1, $pkg, @what_to_export);
-}
-
-
-# OBSOLETED
-
-sub jsonToObj {
- my $alternative = 'from_json';
- if (defined $_[0] and UNIVERSAL::isa($_[0], 'JSON')) {
- shift @_; $alternative = 'decode';
- }
- Carp::carp "'jsonToObj' will be obsoleted. Please use '$alternative' instead.";
- return JSON::from_json(@_);
-};
-
-sub objToJson {
- my $alternative = 'to_json';
- if (defined $_[0] and UNIVERSAL::isa($_[0], 'JSON')) {
- shift @_; $alternative = 'encode';
- }
- Carp::carp "'objToJson' will be obsoleted. Please use '$alternative' instead.";
- JSON::to_json(@_);
-};
-
-
-# INTERFACES
-
-sub to_json ($@) {
- if (
- ref($_[0]) eq 'JSON'
- or (@_ > 2 and $_[0] eq 'JSON')
- ) {
- Carp::croak "to_json should not be called as a method.";
- }
- my $json = JSON->new;
-
- if (@_ == 2 and ref $_[1] eq 'HASH') {
- my $opt = $_[1];
- for my $method (keys %$opt) {
- $json->$method( $opt->{$method} );
- }
- }
-
- $json->encode($_[0]);
-}
-
-
-sub from_json ($@) {
- if ( ref($_[0]) eq 'JSON' or $_[0] eq 'JSON' ) {
- Carp::croak "from_json should not be called as a method.";
- }
- my $json = JSON->new;
-
- if (@_ == 2 and ref $_[1] eq 'HASH') {
- my $opt = $_[1];
- for my $method (keys %$opt) {
- $json->$method( $opt->{$method} );
- }
- }
-
- return $json->decode( $_[0] );
-}
-
-
-
-sub true { $JSON::true }
-
-sub false { $JSON::false }
-
-sub null { undef; }
-
-
-sub require_xs_version { $RequiredVersion{'JSON::XS'}; }
-
-sub backend {
- my $proto = shift;
- $JSON::Backend;
-}
-
-#*module = *backend;
-
-
-sub is_xs {
- return $_[0]->backend->is_xs;
-}
-
-
-sub is_pp {
- return $_[0]->backend->is_pp;
-}
-
-
-sub pureperl_only_methods { @PPOnlyMethods; }
-
-
-sub property {
- my ($self, $name, $value) = @_;
-
- if (@_ == 1) {
- my %props;
- for $name (@Properties) {
- my $method = 'get_' . $name;
- if ($name eq 'max_size') {
- my $value = $self->$method();
- $props{$name} = $value == 1 ? 0 : $value;
- next;
- }
- $props{$name} = $self->$method();
- }
- return \%props;
- }
- elsif (@_ > 3) {
- Carp::croak('property() can take only the option within 2 arguments.');
- }
- elsif (@_ == 2) {
- if ( my $method = $self->can('get_' . $name) ) {
- if ($name eq 'max_size') {
- my $value = $self->$method();
- return $value == 1 ? 0 : $value;
- }
- $self->$method();
- }
- }
- else {
- $self->$name($value);
- }
-
-}
-
-
-
-# INTERNAL
-
-sub __load_xs {
- my ($module, $opt) = @_;
-
- $JSON::DEBUG and Carp::carp "Load $module.";
- my $required_version = $RequiredVersion{$module} || '';
-
- eval qq|
- use $module $required_version ();
- |;
-
- if ($@) {
- if (defined $opt and $opt & $_INSTALL_DONT_DIE) {
- $JSON::DEBUG and Carp::carp "Can't load $module...($@)";
- return 0;
- }
- Carp::croak $@;
- }
- $JSON::BackendModuleXS = $module;
- return 1;
-}
-
-sub _load_xs {
- my ($module, $opt) = @_;
- __load_xs($module, $opt) or return;
-
- my $data = join("", <DATA>); # this code is from Jcode 2.xx.
- close(DATA);
- eval $data;
- JSON::Backend::XS->init($module);
-
- return 1;
-};
-
-
-sub __load_pp {
- my ($module, $opt) = @_;
-
- $JSON::DEBUG and Carp::carp "Load $module.";
- my $required_version = $RequiredVersion{$module} || '';
-
- eval qq| use $module $required_version () |;
-
- if ($@) {
- if ( $module eq 'JSON::PP' ) {
- $JSON::DEBUG and Carp::carp "Can't load $module ($@), so try to load JSON::backportPP";
- $module = 'JSON::backportPP';
- local $^W; # if PP installed but invalid version, backportPP redefines methods.
- eval qq| require $module |;
- }
- Carp::croak $@ if $@;
- }
- $JSON::BackendModulePP = $module;
- return 1;
-}
-
-sub _load_pp {
- my ($module, $opt) = @_;
- __load_pp($module, $opt);
-
- JSON::Backend::PP->init($module);
-};
-
-#
-# Helper classes for Backend Module (PP)
-#
-
-package JSON::Backend::PP;
-
-sub init {
- my ($class, $module) = @_;
-
- # name may vary, but the module should (always) be a JSON::PP
-
- local $^W;
- no strict qw(refs); # this routine may be called after JSON::Backend::XS init was called.
- *{"JSON::decode_json"} = \&{"JSON::PP::decode_json"};
- *{"JSON::encode_json"} = \&{"JSON::PP::encode_json"};
- *{"JSON::is_bool"} = \&{"JSON::PP::is_bool"};
-
- $JSON::true = ${"JSON::PP::true"};
- $JSON::false = ${"JSON::PP::false"};
-
- push @JSON::Backend::PP::ISA, 'JSON::PP';
- push @JSON::ISA, $class;
- $JSON::Backend = $class;
- $JSON::BackendModule = $module;
- ${"$class\::VERSION"} = $module->VERSION;
-
- for my $method (@XSOnlyMethods) {
- *{"JSON::$method"} = sub {
- Carp::carp("$method is not supported in $module.");
- $_[0];
- };
- }
-
- return 1;
-}
-
-sub is_xs { 0 };
-sub is_pp { 1 };
-
-#
-# To save memory, the below lines are read only when XS backend is used.
-#
-
-package JSON;
-
-1;
-__DATA__
-
-
-#
-# Helper classes for Backend Module (XS)
-#
-
-package JSON::Backend::XS;
-
-sub init {
- my ($class, $module) = @_;
-
- local $^W;
- no strict qw(refs);
- *{"JSON::decode_json"} = \&{"$module\::decode_json"};
- *{"JSON::encode_json"} = \&{"$module\::encode_json"};
- *{"JSON::is_bool"} = \&{"$module\::is_bool"};
-
- $JSON::true = ${"$module\::true"};
- $JSON::false = ${"$module\::false"};
-
- push @JSON::Backend::XS::ISA, $module;
- push @JSON::ISA, $class;
- $JSON::Backend = $class;
- $JSON::BackendModule = $module;
- ${"$class\::VERSION"} = $module->VERSION;
-
- if ( $module->VERSION < 3 ) {
- eval 'package JSON::PP::Boolean';
- push @{"$module\::Boolean::ISA"}, qw(JSON::PP::Boolean);
- }
-
- for my $method (@PPOnlyMethods) {
- *{"JSON::$method"} = sub {
- Carp::carp("$method is not supported in $module.");
- $_[0];
- };
- }
-
- return 1;
-}
-
-sub is_xs { 1 };
-sub is_pp { 0 };
-
-sub support_by_pp {
- my ($class, @methods) = @_;
-
- JSON::__load_pp('JSON::PP');
-
- local $^W;
- no strict qw(refs);
-
- for my $method (@methods) {
- my $pp_method = JSON::PP->can($method) or next;
- *{"JSON::$method"} = sub {
- if (!$_[0]->isa('JSON::PP')) {
- my $xs_self = $_[0];
- my $pp_self = JSON::PP->new;
- for (@Properties) {
- my $getter = "get_$_";
- $pp_self->$_($xs_self->$getter);
- }
- $_[0] = $pp_self;
- }
- $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 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
-C<convert_blessed> and provide a C<TO_JSON> method for each object's
-(base) class that may be found in the structure, in order to let the
-methods replace the objects with whatever scalar values the methods
-return.
-
-If you need to serialise data structures that may contain arbitrary
-objects, it's probably better to use other serialisers (such as
-L<Sereal> or L<Storable> for example), but if you do want to use
-this module for that purpose, C<-convert_blessed_universally> option
-may help, which tweaks C<encode> method of the backend to install
-C<UNIVERSAL::TO_JSON> method (locally) before encoding, so that
-all the objects that don't have their own C<TO_JSON> method can
-fall back on the method in the C<UNIVERSAL> namespace. Note that you
-still need to enable C<convert_blessed> flag to actually encode
-objects in a data structure, and C<UNIVERSAL::TO_JSON> method
-installed by this option only converts blessed hash/array references
-into their unblessed clone (including private keys/values that are
-not supposed to be exposed). Other blessed references will be
-converted into null.
-
-This feature is experimental and may be removed in the future.
-
-=item -no_export
-
-When you don't want to import functional interfaces from a module, you
-usually supply C<()> to its C<use> statement.
-
- use JSON (); # no functional interfaces
-
-If you don't want to import functional interfaces, but you also want to
-use any of the above options, add C<-no_export> to the option list.
-
- # no functional interfaces, while JSON::PP support is enabled.
- use JSON -support_by_pp, -no_export;
-
-=back
-
-=head1 FUNCTIONAL INTERFACE
-
-This section is taken from JSON::XS. C<encode_json> and C<decode_json>
-are exported by default.
-
-This module also exports C<to_json> and C<from_json> for backward
-compatibility. These are slower, and may expect/generate different stuff
-from what C<encode_json> and C<decode_json> do, depending on their
-options. It's better just to use Object-Oriented interfaces than using
-these two functions.
-
-=head2 encode_json
-
- $json_text = encode_json $perl_scalar
-
-Converts the given Perl data structure to a UTF-8 encoded, binary string
-(that is, the string contains octets only). Croaks on error.
-
-This function call is functionally identical to:
-
- $json_text = JSON->new->utf8->encode($perl_scalar)
-
-Except being faster.
-
-=head2 decode_json
-
- $perl_scalar = decode_json $json_text
-
-The opposite of C<encode_json>: expects an UTF-8 (binary) string and tries
-to parse that as an UTF-8 encoded JSON text, returning the resulting
-reference. Croaks on error.
-
-This function call is functionally identical to:
-
- $perl_scalar = JSON->new->utf8->decode($json_text)
-
-Except being faster.
-
-=head2 to_json
-
- $json_text = to_json($perl_scalar[, $optional_hashref])
-
-Converts the given Perl data structure to a Unicode string by default.
-Croaks on error.
-
-Basically, this function call is functionally identical to:
-
- $json_text = JSON->new->encode($perl_scalar)
-
-Except being slower.
-
-You can pass an optional hash reference to modify its behavior, but
-that may change what C<to_json> expects/generates (see
-C<ENCODING/CODESET FLAG NOTES> for details).
-
- $json_text = to_json($perl_scalar, {utf8 => 1, pretty => 1})
- # => JSON->new->utf8(1)->pretty(1)->encode($perl_scalar)
-
-=head2 from_json
-
- $perl_scalar = from_json($json_text[, $optional_hashref])
-
-The opposite of C<to_json>: expects a Unicode string and tries
-to parse it, returning the resulting reference. Croaks on error.
-
-Basically, this function call is functionally identical to:
-
- $perl_scalar = JSON->new->decode($json_text)
-
-You can pass an optional hash reference to modify its behavior, but
-that may change what C<from_json> expects/generates (see
-C<ENCODING/CODESET FLAG NOTES> for details).
-
- $perl_scalar = from_json($json_text, {utf8 => 1})
- # => JSON->new->utf8(1)->decode($json_text)
-
-=head2 JSON::is_bool
-
- $is_boolean = JSON::is_bool($scalar)
-
-Returns true if the passed scalar represents either JSON::true or
-JSON::false, two constants that act like C<1> and C<0> respectively
-and are also used to represent JSON C<true> and C<false> in Perl strings.
-
-See L<MAPPING>, below, for more information on how JSON values are mapped to
-Perl.
-
-=head1 COMMON OBJECT-ORIENTED INTERFACE
-
-This section is also taken from JSON::XS.
-
-The object oriented interface lets you configure your own encoding or
-decoding style, within the limits of supported formats.
-
-=head2 new
-
- $json = JSON->new
-
-Creates a new JSON::XS-compatible backend object that can be used to de/encode JSON
-strings. All boolean flags described below are by default I<disabled>.
-
-The mutators for flags all return the backend object again and thus calls can
-be chained:
-
- my $json = JSON->new->utf8->space_after->encode({a => [1,2]})
- => {"a": [1, 2]}
-
-=head2 ascii
-
- $json = $json->ascii([$enable])
-
- $enabled = $json->get_ascii
-
-If C<$enable> is true (or missing), then the C<encode> method will not
-generate characters outside the code range C<0..127> (which is ASCII). Any
-Unicode characters outside that range will be escaped using either a
-single \uXXXX (BMP characters) or a double \uHHHH\uLLLLL escape sequence,
-as per RFC4627. The resulting encoded JSON text can be treated as a native
-Unicode string, an ascii-encoded, latin1-encoded or UTF-8 encoded string,
-or any other superset of ASCII.
-
-If C<$enable> is false, then the C<encode> method will not escape Unicode
-characters unless required by the JSON syntax or other flags. This results
-in a faster and more compact format.
-
-See also the section I<ENCODING/CODESET FLAG NOTES> later in this document.
-
-The main use for this flag is to produce JSON texts that can be
-transmitted over a 7-bit channel, as the encoded JSON texts will not
-contain any 8 bit characters.
-
- JSON->new->ascii(1)->encode([chr 0x10401])
- => ["\ud801\udc01"]
-
-=head2 latin1
-
- $json = $json->latin1([$enable])
-
- $enabled = $json->get_latin1
-
-If C<$enable> is true (or missing), then the C<encode> method will encode
-the resulting JSON text as latin1 (or iso-8859-1), escaping any characters
-outside the code range C<0..255>. The resulting string can be treated as a
-latin1-encoded JSON text or a native Unicode string. The C<decode> method
-will not be affected in any way by this flag, as C<decode> by default
-expects Unicode, which is a strict superset of latin1.
-
-If C<$enable> is false, then the C<encode> method will not escape Unicode
-characters unless required by the JSON syntax or other flags.
-
-See also the section I<ENCODING/CODESET FLAG NOTES> later in this document.
-
-The main use for this flag is efficiently encoding binary data as JSON
-text, as most octets will not be escaped, resulting in a smaller encoded
-size. The disadvantage is that the resulting JSON text is encoded
-in latin1 (and must correctly be treated as such when storing and
-transferring), a rare encoding for JSON. It is therefore most useful when
-you want to store data structures known to contain binary data efficiently
-in files or databases, not when talking to other JSON encoders/decoders.
-
- JSON->new->latin1->encode (["\x{89}\x{abc}"]
- => ["\x{89}\\u0abc"] # (perl syntax, U+abc escaped, U+89 not)
-
-=head2 utf8
-
- $json = $json->utf8([$enable])
-
- $enabled = $json->get_utf8
-
-If C<$enable> is true (or missing), then the C<encode> method will encode
-the JSON result into UTF-8, as required by many protocols, while the
-C<decode> method expects to be handled an UTF-8-encoded string. Please
-note that UTF-8-encoded strings do not contain any characters outside the
-range C<0..255>, they are thus useful for bytewise/binary I/O. In future
-versions, enabling this option might enable autodetection of the UTF-16
-and UTF-32 encoding families, as described in RFC4627.
-
-If C<$enable> is false, then the C<encode> method will return the JSON
-string as a (non-encoded) Unicode string, while C<decode> expects thus a
-Unicode string. Any decoding or encoding (e.g. to UTF-8 or UTF-16) needs
-to be done yourself, e.g. using the Encode module.
-
-See also the section I<ENCODING/CODESET FLAG NOTES> later in this document.
-
-Example, output UTF-16BE-encoded JSON:
-
- use Encode;
- $jsontext = encode "UTF-16BE", JSON->new->encode ($object);
-
-Example, decode UTF-32LE-encoded JSON:
-
- use Encode;
- $object = JSON->new->decode (decode "UTF-32LE", $jsontext);
-
-=head2 pretty
-
- $json = $json->pretty([$enable])
-
-This enables (or disables) all of the C<indent>, C<space_before> and
-C<space_after> (and in the future possibly more) flags in one call to
-generate the most readable (or most compact) form possible.
-
-=head2 indent
-
- $json = $json->indent([$enable])
-
- $enabled = $json->get_indent
-
-If C<$enable> is true (or missing), then the C<encode> method will use a multiline
-format as output, putting every array member or object/hash key-value pair
-into its own line, indenting them properly.
-
-If C<$enable> is false, no newlines or indenting will be produced, and the
-resulting JSON text is guaranteed not to contain any C<newlines>.
-
-This setting has no effect when decoding JSON texts.
-
-=head2 space_before
-
- $json = $json->space_before([$enable])
-
- $enabled = $json->get_space_before
-
-If C<$enable> is true (or missing), then the C<encode> method will add an extra
-optional space before the C<:> separating keys from values in JSON objects.
-
-If C<$enable> is false, then the C<encode> method will not add any extra
-space at those places.
-
-This setting has no effect when decoding JSON texts. You will also
-most likely combine this setting with C<space_after>.
-
-Example, space_before enabled, space_after and indent disabled:
-
- {"key" :"value"}
-
-=head2 space_after
-
- $json = $json->space_after([$enable])
-
- $enabled = $json->get_space_after
-
-If C<$enable> is true (or missing), then the C<encode> method will add an extra
-optional space after the C<:> separating keys from values in JSON objects
-and extra whitespace after the C<,> separating key-value pairs and array
-members.
-
-If C<$enable> is false, then the C<encode> method will not add any extra
-space at those places.
-
-This setting has no effect when decoding JSON texts.
-
-Example, space_before and indent disabled, space_after enabled:
-
- {"key": "value"}
-
-=head2 relaxed
-
- $json = $json->relaxed([$enable])
-
- $enabled = $json->get_relaxed
-
-If C<$enable> is true (or missing), then C<decode> will accept some
-extensions to normal JSON syntax (see below). C<encode> will not be
-affected in anyway. I<Be aware that this option makes you accept invalid
-JSON texts as if they were valid!>. I suggest only to use this option to
-parse application-specific files written by humans (configuration files,
-resource files etc.)
-
-If C<$enable> is false (the default), then C<decode> will only accept
-valid JSON texts.
-
-Currently accepted extensions are:
-
-=over 4
-
-=item * list items can have an end-comma
-
-JSON I<separates> array elements and key-value pairs with commas. This
-can be annoying if you write JSON texts manually and want to be able to
-quickly append elements, so this extension accepts comma at the end of
-such items not just between them:
-
- [
- 1,
- 2, <- this comma not normally allowed
- ]
- {
- "k1": "v1",
- "k2": "v2", <- this comma not normally allowed
- }
-
-=item * shell-style '#'-comments
-
-Whenever JSON allows whitespace, shell-style comments are additionally
-allowed. They are terminated by the first carriage-return or line-feed
-character, after which more white-space and comments are allowed.
-
- [
- 1, # this comment not allowed in JSON
- # neither this one...
- ]
-
-=back
-
-=head2 canonical
-
- $json = $json->canonical([$enable])
-
- $enabled = $json->get_canonical
-
-If C<$enable> is true (or missing), then the C<encode> method will output JSON objects
-by sorting their keys. This is adding a comparatively high overhead.
-
-If C<$enable> is false, then the C<encode> method will output key-value
-pairs in the order Perl stores them (which will likely change between runs
-of the same script, and can change even within the same run from 5.18
-onwards).
-
-This option is useful if you want the same data structure to be encoded as
-the same JSON text (given the same overall settings). If it is disabled,
-the same hash might be encoded differently even if contains the same data,
-as key-value pairs have no inherent ordering in Perl.
-
-This setting has no effect when decoding JSON texts.
-
-This setting has currently no effect on tied hashes.
-
-=head2 allow_nonref
-
- $json = $json->allow_nonref([$enable])
-
- $enabled = $json->get_allow_nonref
-
-If C<$enable> is true (or missing), then the C<encode> method can convert a
-non-reference into its corresponding string, number or null JSON value,
-which is an extension to RFC4627. Likewise, C<decode> will accept those JSON
-values instead of croaking.
-
-If C<$enable> is false, then the C<encode> method will croak if it isn't
-passed an arrayref or hashref, as JSON texts must either be an object
-or array. Likewise, C<decode> will croak if given something that is not a
-JSON object or array.
-
-Example, encode a Perl scalar as JSON value with enabled C<allow_nonref>,
-resulting in an invalid JSON text:
-
- JSON->new->allow_nonref->encode ("Hello, World!")
- => "Hello, World!"
-
-=head2 allow_unknown
-
- $json = $json->allow_unknown ([$enable])
-
- $enabled = $json->get_allow_unknown
-
-If C<$enable> is true (or missing), then C<encode> will I<not> throw an
-exception when it encounters values it cannot represent in JSON (for
-example, filehandles) but instead will encode a JSON C<null> value. Note
-that blessed objects are not included here and are handled separately by
-c<allow_nonref>.
-
-If C<$enable> is false (the default), then C<encode> will throw an
-exception when it encounters anything it cannot encode as JSON.
-
-This option does not affect C<decode> in any way, and it is recommended to
-leave it off unless you know your communications partner.
-
-=head2 allow_blessed
-
- $json = $json->allow_blessed([$enable])
-
- $enabled = $json->get_allow_blessed
-
-See L<OBJECT SERIALISATION> for details.
-
-If C<$enable> is true (or missing), then the C<encode> method will not
-barf when it encounters a blessed reference that it cannot convert
-otherwise. Instead, a JSON C<null> value is encoded instead of the object.
-
-If C<$enable> is false (the default), then C<encode> will throw an
-exception when it encounters a blessed object that it cannot convert
-otherwise.
-
-This setting has no effect on C<decode>.
-
-=head2 convert_blessed
-
- $json = $json->convert_blessed([$enable])
-
- $enabled = $json->get_convert_blessed
-
-See L<OBJECT SERIALISATION> for details.
-
-If C<$enable> is true (or missing), then C<encode>, upon encountering a
-blessed object, will check for the availability of the C<TO_JSON> method
-on the object's class. If found, it will be called in scalar context and
-the resulting scalar will be encoded instead of the object.
-
-The C<TO_JSON> method may safely call die if it wants. If C<TO_JSON>
-returns other blessed objects, those will be handled in the same
-way. C<TO_JSON> must take care of not causing an endless recursion cycle
-(== crash) in this case. The name of C<TO_JSON> was chosen because other
-methods called by the Perl core (== not by the user of the object) are
-usually in upper case letters and to avoid collisions with any C<to_json>
-function or method.
-
-If C<$enable> is false (the default), then C<encode> will not consider
-this type of conversion.
-
-This setting has no effect on C<decode>.
-
-=head2 filter_json_object
-
- $json = $json->filter_json_object([$coderef])
-
-When C<$coderef> is specified, it will be called from C<decode> each
-time it decodes a JSON object. The only argument is a reference to the
-newly-created hash. If the code references returns a single scalar (which
-need not be a reference), this value (i.e. a copy of that scalar to avoid
-aliasing) is inserted into the deserialised data structure. If it returns
-an empty list (NOTE: I<not> C<undef>, which is a valid scalar), the
-original deserialised hash will be inserted. This setting can slow down
-decoding considerably.
-
-When C<$coderef> is omitted or undefined, any existing callback will
-be removed and C<decode> will not change the deserialised hash in any
-way.
-
-Example, convert all JSON objects into the integer 5:
-
- my $js = JSON->new->filter_json_object (sub { 5 });
- # returns [5]
- $js->decode ('[{}]'); # the given subroutine takes a hash reference.
- # throw an exception because allow_nonref is not enabled
- # so a lone 5 is not allowed.
- $js->decode ('{"a":1, "b":2}');
-
-=head2 filter_json_single_key_object
-
- $json = $json->filter_json_single_key_object($key [=> $coderef])
-
-Works remotely similar to C<filter_json_object>, but is only called for
-JSON objects having a single key named C<$key>.
-
-This C<$coderef> is called before the one specified via
-C<filter_json_object>, if any. It gets passed the single value in the JSON
-object. If it returns a single value, it will be inserted into the data
-structure. If it returns nothing (not even C<undef> but the empty list),
-the callback from C<filter_json_object> will be called next, as if no
-single-key callback were specified.
-
-If C<$coderef> is omitted or undefined, the corresponding callback will be
-disabled. There can only ever be one callback for a given key.
-
-As this callback gets called less often then the C<filter_json_object>
-one, decoding speed will not usually suffer as much. Therefore, single-key
-objects make excellent targets to serialise Perl objects into, especially
-as single-key JSON objects are as close to the type-tagged value concept
-as JSON gets (it's basically an ID/VALUE tuple). Of course, JSON does not
-support this in any way, so you need to make sure your data never looks
-like a serialised Perl hash.
-
-Typical names for the single object key are C<__class_whatever__>, or
-C<$__dollars_are_rarely_used__$> or C<}ugly_brace_placement>, or even
-things like C<__class_md5sum(classname)__>, to reduce the risk of clashing
-with real hashes.
-
-Example, decode JSON objects of the form C<< { "__widget__" => <id> } >>
-into the corresponding C<< $WIDGET{<id>} >> object:
-
- # return whatever is in $WIDGET{5}:
- JSON
- ->new
- ->filter_json_single_key_object (__widget__ => sub {
- $WIDGET{ $_[0] }
- })
- ->decode ('{"__widget__": 5')
-
- # this can be used with a TO_JSON method in some "widget" class
- # for serialisation to json:
- sub WidgetBase::TO_JSON {
- my ($self) = @_;
-
- unless ($self->{id}) {
- $self->{id} = ..get..some..id..;
- $WIDGET{$self->{id}} = $self;
- }
-
- { __widget__ => $self->{id} }
- }
-
-=head2 max_depth
-
- $json = $json->max_depth([$maximum_nesting_depth])
-
- $max_depth = $json->get_max_depth
-
-Sets the maximum nesting level (default C<512>) accepted while encoding
-or decoding. If a higher nesting level is detected in JSON text or a Perl
-data structure, then the encoder and decoder will stop and croak at that
-point.
-
-Nesting level is defined by number of hash- or arrayrefs that the encoder
-needs to traverse to reach a given point or the number of C<{> or C<[>
-characters without their matching closing parenthesis crossed to reach a
-given character in a string.
-
-Setting the maximum depth to one disallows any nesting, so that ensures
-that the object is only a single hash/object or array.
-
-If no argument is given, the highest possible setting will be used, which
-is rarely useful.
-
-=head2 max_size
-
- $json = $json->max_size([$maximum_string_size])
-
- $max_size = $json->get_max_size
-
-Set the maximum length a JSON text may have (in bytes) where decoding is
-being attempted. The default is C<0>, meaning no limit. When C<decode>
-is called on a string that is longer then this many bytes, it will not
-attempt to decode the string but throw an exception. This setting has no
-effect on C<encode> (yet).
-
-If no argument is given, the limit check will be deactivated (same as when
-C<0> is specified).
-
-=head2 encode
-
- $json_text = $json->encode($perl_scalar)
-
-Converts the given Perl value or data structure to its JSON
-representation. Croaks on error.
-
-=head2 decode
-
- $perl_scalar = $json->decode($json_text)
-
-The opposite of C<encode>: expects a JSON text and tries to parse it,
-returning the resulting simple scalar or reference. Croaks on error.
-
-=head2 decode_prefix
-
- ($perl_scalar, $characters) = $json->decode_prefix($json_text)
-
-This works like the C<decode> method, but instead of raising an exception
-when there is trailing garbage after the first JSON object, it will
-silently stop parsing there and return the number of characters consumed
-so far.
-
-This is useful if your JSON texts are not delimited by an outer protocol
-and you need to know where the JSON text ends.
-
- JSON->new->decode_prefix ("[1] the tail")
- => ([1], 3)
-
-=head1 ADDITIONAL METHODS
-
-The following methods are for this module only.
-
-=head2 backend
-
- $backend = $json->backend
-
-Since 2.92, C<backend> method returns an abstract backend module used currently,
-which should be JSON::Backend::XS (which inherits JSON::XS or Cpanel::JSON::XS),
-or JSON::Backend::PP (which inherits JSON::PP), not to monkey-patch the actual
-backend module globally.
-
-If you need to know what is used actually, use C<isa>, instead of string comparison.
-
-=head2 is_xs
-
- $boolean = $json->is_xs
-
-Returns true if the backend inherits JSON::XS or Cpanel::JSON::XS.
-
-=head2 is_pp
-
- $boolean = $json->is_pp
-
-Returns true if the backend inherits JSON::PP.
-
-=head2 property
-
- $settings = $json->property()
-
-Returns a reference to a hash that holds all the common flag settings.
-
- $json = $json->property('utf8' => 1)
- $value = $json->property('utf8') # 1
-
-You can use this to get/set a value of a particular flag.
-
-=head1 INCREMENTAL PARSING
-
-This section is also taken from JSON::XS.
-
-In some cases, there is the need for incremental parsing of JSON
-texts. While this module always has to keep both JSON text and resulting
-Perl data structure in memory at one time, it does allow you to parse a
-JSON stream incrementally. It does so by accumulating text until it has
-a full JSON object, which it then can decode. This process is similar to
-using C<decode_prefix> to see if a full JSON object is available, but
-is much more efficient (and can be implemented with a minimum of method
-calls).
-
-This module will only attempt to parse the JSON text once it is sure it
-has enough text to get a decisive result, using a very simple but
-truly incremental parser. This means that it sometimes won't stop as
-early as the full parser, for example, it doesn't detect mismatched
-parentheses. The only thing it guarantees is that it starts decoding as
-soon as a syntactically valid JSON text has been seen. This means you need
-to set resource limits (e.g. C<max_size>) to ensure the parser will stop
-parsing in the presence if syntax errors.
-
-The following methods implement this incremental parser.
-
-=head2 incr_parse
-
- $json->incr_parse( [$string] ) # void context
-
- $obj_or_undef = $json->incr_parse( [$string] ) # scalar context
-
- @obj_or_empty = $json->incr_parse( [$string] ) # list context
-
-This is the central parsing function. It can both append new text and
-extract objects from the stream accumulated so far (both of these
-functions are optional).
-
-If C<$string> is given, then this string is appended to the already
-existing JSON fragment stored in the C<$json> object.
-
-After that, if the function is called in void context, it will simply
-return without doing anything further. This can be used to add more text
-in as many chunks as you want.
-
-If the method is called in scalar context, then it will try to extract
-exactly I<one> JSON object. If that is successful, it will return this
-object, otherwise it will return C<undef>. If there is a parse error,
-this method will croak just as C<decode> would do (one can then use
-C<incr_skip> to skip the erroneous part). This is the most common way of
-using the method.
-
-And finally, in list context, it will try to extract as many objects
-from the stream as it can find and return them, or the empty list
-otherwise. For this to work, there must be no separators (other than
-whitespace) between the JSON objects or arrays, instead they must be
-concatenated back-to-back. If an error occurs, an exception will be
-raised as in the scalar context case. Note that in this case, any
-previously-parsed JSON texts will be lost.
-
-Example: Parse some JSON arrays/objects in a given string and return
-them.
-
- my @objs = JSON->new->incr_parse ("[5][7][1,2]");
-
-=head2 incr_text
-
- $lvalue_string = $json->incr_text
-
-This method returns the currently stored JSON fragment as an lvalue, that
-is, you can manipulate it. This I<only> works when a preceding call to
-C<incr_parse> in I<scalar context> successfully returned an object. Under
-all other circumstances you must not call this function (I mean it.
-although in simple tests it might actually work, it I<will> fail under
-real world conditions). As a special exception, you can also call this
-method before having parsed anything.
-
-That means you can only use this function to look at or manipulate text
-before or after complete JSON objects, not while the parser is in the
-middle of parsing a JSON object.
-
-This function is useful in two cases: a) finding the trailing text after a
-JSON object or b) parsing multiple JSON objects separated by non-JSON text
-(such as commas).
-
-=head2 incr_skip
-
- $json->incr_skip
-
-This will reset the state of the incremental parser and will remove
-the parsed text from the input buffer so far. This is useful after
-C<incr_parse> died, in which case the input buffer and incremental parser
-state is left unchanged, to skip the text parsed so far and to reset the
-parse state.
-
-The difference to C<incr_reset> is that only text until the parse error
-occurred is removed.
-
-=head2 incr_reset
-
- $json->incr_reset
-
-This completely resets the incremental parser, that is, after this call,
-it will be as if the parser had never parsed anything.
-
-This is useful if you want to repeatedly parse JSON objects and want to
-ignore any trailing data, which means you have to reset the parser after
-each successful decode.
-
-=head1 MAPPING
-
-Most of this section is also taken from JSON::XS.
-
-This section describes how the backend modules map Perl values to JSON values and
-vice versa. These mappings are designed to "do the right thing" in most
-circumstances automatically, preserving round-tripping characteristics
-(what you put in comes out as something equivalent).
-
-For the more enlightened: note that in the following descriptions,
-lowercase I<perl> refers to the Perl interpreter, while uppercase I<Perl>
-refers to the abstract Perl language itself.
-
-=head2 JSON -> PERL
-
-=over 4
-
-=item object
-
-A JSON object becomes a reference to a hash in Perl. No ordering of object
-keys is preserved (JSON does not preserver object key ordering itself).
-
-=item array
-
-A JSON array becomes a reference to an array in Perl.
-
-=item string
-
-A JSON string becomes a string scalar in Perl - Unicode codepoints in JSON
-are represented by the same codepoints in the Perl string, so no manual
-decoding is necessary.
-
-=item number
-
-A JSON number becomes either an integer, numeric (floating point) or
-string scalar in perl, depending on its range and any fractional parts. On
-the Perl level, there is no difference between those as Perl handles all
-the conversion details, but an integer may take slightly less memory and
-might represent more values exactly than floating point numbers.
-
-If the number consists of digits only, this module will try to represent
-it as an integer value. If that fails, it will try to represent it as
-a numeric (floating point) value if that is possible without loss of
-precision. Otherwise it will preserve the number as a string value (in
-which case you lose roundtripping ability, as the JSON number will be
-re-encoded to a JSON string).
-
-Numbers containing a fractional or exponential part will always be
-represented as numeric (floating point) values, possibly at a loss of
-precision (in which case you might lose perfect roundtripping ability, but
-the JSON number will still be re-encoded as a JSON number).
-
-Note that precision is not accuracy - binary floating point values cannot
-represent most decimal fractions exactly, and when converting from and to
-floating point, this module only guarantees precision up to but not including
-the least significant bit.
-
-=item true, false
-
-These JSON atoms become C<JSON::true> and C<JSON::false>,
-respectively. They are overloaded to act almost exactly like the numbers
-C<1> and C<0>. You can check whether a scalar is a JSON boolean by using
-the C<JSON::is_bool> function.
-
-=item null
-
-A JSON null atom becomes C<undef> in Perl.
-
-=item shell-style comments (C<< # I<text> >>)
-
-As a nonstandard extension to the JSON syntax that is enabled by the
-C<relaxed> setting, shell-style comments are allowed. They can start
-anywhere outside strings and go till the end of the line.
-
-=back
-
-
-=head2 PERL -> JSON
-
-The mapping from Perl to JSON is slightly more difficult, as Perl is a
-truly typeless language, so we can only guess which JSON type is meant by
-a Perl value.
-
-=over 4
-
-=item hash references
-
-Perl hash references become JSON objects. As there is no inherent
-ordering in hash keys (or JSON objects), they will usually be encoded
-in a pseudo-random order. This module can optionally sort the hash keys
-(determined by the I<canonical> flag), so the same data structure will
-serialise to the same JSON text (given same settings and version of
-the same backend), but this incurs a runtime overhead and is only rarely useful,
-e.g. when you want to compare some JSON text against another for equality.
-
-=item array references
-
-Perl array references become JSON arrays.
-
-=item other references
-
-Other unblessed references are generally not allowed and will cause an
-exception to be thrown, except for references to the integers C<0> and
-C<1>, which get turned into C<false> and C<true> atoms in JSON. You can
-also use C<JSON::false> and C<JSON::true> to improve readability.
-
- encode_json [\0,JSON::true] # yields [false,true]
-
-=item JSON::true, JSON::false, JSON::null
-
-These special values become JSON true and JSON false values,
-respectively. You can also use C<\1> and C<\0> directly if you want.
-
-=item blessed objects
-
-Blessed objects are not directly representable in JSON, but C<JSON::XS>
-allows various ways of handling objects. See L<OBJECT SERIALISATION>,
-below, for details.
-
-=item 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 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, 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.
-
-=back
-
-=head2 OBJECT SERIALISATION
-
-As for Perl objects, this module only supports a pure JSON representation
-(without the ability to deserialise the object automatically again).
-
-=head3 SERIALISATION
-
-What happens when this module encounters a Perl object depends on the
-C<allow_blessed> and C<convert_blessed> settings, which are used in
-this order:
-
-=over 4
-
-=item 1. 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 serialised. The fact that these values
-originally were L<URI> objects is lost.
-
- sub URI::TO_JSON {
- my ($uri) = @_;
- $uri->as_string
- }
-
-=item 2. C<allow_blessed> is enabled.
-
-The object will be serialised as a JSON null value.
-
-=item 3. none of the above
-
-If none of the settings are enabled or the respective methods are missing,
-this module throws an exception.
-
-=back
-
-=head1 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 - C<utf8>, C<latin1> and C<ascii>. There seems to be
-some confusion on what these do, so here is a short comparison:
-
-C<utf8> controls whether the JSON text created by C<encode> (and expected
-by C<decode>) is UTF-8 encoded or not, while C<latin1> and C<ascii> only
-control whether C<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
-C<encode> and C<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 I<encodes> them, in our case into
-octets. Unicode is (among other things) a codeset, UTF-8 is an encoding,
-and ISO-8859-1 (= latin 1) and ASCII are both codesets I<and> encodings at
-the same time, which can be confusing.
-
-=over 4
-
-=item C<utf8> flag disabled
-
-When C<utf8> is disabled (the default), then C<encode>/C<decode> generate
-and expect Unicode strings, that is, characters with high ordinal Unicode
-values (> 255) will be encoded as such characters, and likewise such
-characters are decoded as-is, no changes to them will be done, except
-"(re-)interpreting" them as Unicode codepoints or Unicode characters,
-respectively (to Perl, these are the same thing in strings unless you do
-funny/weird/dumb stuff).
-
-This is useful when you want to do the encoding yourself (e.g. when you
-want to have UTF-16 encoded JSON texts) or when some other layer does
-the encoding for you (for example, when printing to a terminal using a
-filehandle that transparently encodes to UTF-8 you certainly do NOT want
-to UTF-8 encode your data first and have Perl encode it another time).
-
-=item C<utf8> flag enabled
-
-If the C<utf8>-flag is enabled, C<encode>/C<decode> will encode all
-characters using the corresponding UTF-8 multi-byte sequence, and will
-expect your input strings to be encoded as UTF-8, that is, no "character"
-of the input string must have any value > 255, as UTF-8 does not allow
-that.
-
-The C<utf8> flag therefore switches between two modes: disabled means you
-will get a Unicode string in Perl, enabled means you get an UTF-8 encoded
-octet/binary string in Perl.
-
-=item C<latin1> or C<ascii> flags enabled
-
-With C<latin1> (or C<ascii>) enabled, C<encode> will escape characters
-with ordinal values > 255 (> 127 with C<ascii>) and encode the remaining
-characters as specified by the C<utf8> flag.
-
-If C<utf8> is disabled, then the result is also correctly encoded in those
-character sets (as both are proper subsets of Unicode, meaning that a
-Unicode string with all character values < 256 is the same thing as a
-ISO-8859-1 string, and a Unicode string with all character values < 128 is
-the same thing as an ASCII string in Perl).
-
-If C<utf8> is enabled, you still get a correct UTF-8-encoded string,
-regardless of these flags, just some more characters will be escaped using
-C<\uXXXX> then before.
-
-Note that ISO-8859-1-I<encoded> strings are not compatible with UTF-8
-encoding, while ASCII-encoded strings are. That is because the ISO-8859-1
-encoding is NOT a subset of UTF-8 (despite the ISO-8859-1 I<codeset> being
-a subset of Unicode), while ASCII is.
-
-Surprisingly, C<decode> will ignore these flags and so treat all input
-values as governed by the C<utf8> flag. If it is disabled, this allows you
-to decode ISO-8859-1- and ASCII-encoded strings, as both strict subsets of
-Unicode. If it is enabled, you can correctly decode UTF-8 encoded strings.
-
-So neither C<latin1> nor C<ascii> are incompatible with the C<utf8> flag -
-they only govern when the JSON output engine escapes a character or not.
-
-The main use for C<latin1> is to relatively efficiently store binary data
-as JSON, at the expense of breaking compatibility with most JSON decoders.
-
-The main use for C<ascii> is to force the output to not contain characters
-with values > 127, which means you can interpret the resulting string
-as UTF-8, ISO-8859-1, ASCII, KOI8-R or most about any character set and
-8-bit-encoding, and still get the same data structure back. This is useful
-when your channel for JSON transfer is not 8-bit clean or the encoding
-might be mangled in between (e.g. in mail), and works because ASCII is a
-proper subset of most 8-bit and multibyte encodings in use in the world.
-
-=back
-
-=head1 BACKWARD INCOMPATIBILITY
-
-Since version 2.90, stringification (and string comparison) for
-C<JSON::true> and C<JSON::false> has not been overloaded. It shouldn't
-matter as long as you treat them as boolean values, but a code that
-expects they are stringified as "true" or "false" doesn't work as
-you have expected any more.
-
- if (JSON::true eq 'true') { # now fails
-
- print "The result is $JSON::true now."; # => The result is 1 now.
-
-And now these boolean values don't inherit JSON::Boolean, either.
-When you need to test a value is a JSON boolean value or not, use
-C<JSON::is_bool> function, instead of testing the value inherits
-a particular boolean class or not.
-
-=head1 BUGS
-
-Please report bugs on backend selection and additional features
-this module provides to RT or GitHub issues for this module:
-
-=over 4
-
-=item https://rt.cpan.org/Public/Dist/Display.html?Queue=JSON
-
-=item https://github.com/makamaka/JSON/issues
-
-=back
-
-Please report bugs and feature requests on decoding/encoding
-and boolean behaviors to the author of the backend module you
-are using.
-
-=head1 SEE ALSO
-
-L<JSON::XS>, L<Cpanel::JSON::XS>, L<JSON::PP> for backends.
-
-L<JSON::MaybeXS>, an alternative that prefers Cpanel::JSON::XS.
-
-C<RFC4627>(L<http://www.ietf.org/rfc/rfc4627.txt>)
-
-=head1 AUTHOR
-
-Makamaka Hannyaharamitu, E<lt>makamaka[at]cpan.orgE<gt>
-
-JSON::XS was written by Marc Lehmann <schmorp[at]schmorp.de>
-
-The release of this new version owes to the courtesy of Marc Lehmann.
-
-
-=head1 COPYRIGHT AND LICENSE
-
-Copyright 2005-2013 by Makamaka Hannyaharamitu
-
-This library is free software; you can redistribute it and/or modify
-it under the same terms as Perl itself.
-
-=cut
-