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