mirror of
https://github.com/xcat2/xcat-dep.git
synced 2024-12-25 12:41:33 +00:00
537389f033
Former-commit-id: 16cd3ac688ba0ebd1cc5749e6aebcbe9bf90e057
1553 lines
56 KiB
Plaintext
1553 lines
56 KiB
Plaintext
JSON version 2.53
|
|
=================
|
|
|
|
JSON::PP was inculded in JSON distribution (CPAN module).
|
|
It comes to be a perl core module in Perl 5.14.
|
|
And JSON::PP well be split away it.
|
|
|
|
This developer-versoin is for the preparation.
|
|
|
|
* JSON distribution will inculde yet another JSON::PP modules.
|
|
They are JSNO::backportPP. So JSON.pm should work as it did at all!
|
|
|
|
=================
|
|
|
|
INSTALLATION
|
|
|
|
To install this module type the following:
|
|
|
|
perl Makefile.PL
|
|
make
|
|
make test
|
|
make install
|
|
|
|
NAME
|
|
JSON - JSON (JavaScript Object Notation) encoder/decoder
|
|
|
|
SYNOPSIS
|
|
use JSON; # imports encode_json, decode_json, to_json and from_json.
|
|
|
|
# simple and fast interfaces (expect/generate UTF-8)
|
|
|
|
$utf8_encoded_json_text = encode_json $perl_hash_or_arrayref;
|
|
$perl_hash_or_arrayref = decode_json $utf8_encoded_json_text;
|
|
|
|
# OO-interface
|
|
|
|
$json = JSON->new->allow_nonref;
|
|
|
|
$json_text = $json->encode( $perl_scalar );
|
|
$perl_scalar = $json->decode( $json_text );
|
|
|
|
$pretty_printed = $json->pretty->encode( $perl_scalar ); # pretty-printing
|
|
|
|
# If you want to use PP only support features, call with '-support_by_pp'
|
|
# When XS unsupported feature is enable, using PP (de|en)code instead of XS ones.
|
|
|
|
use JSON -support_by_pp;
|
|
|
|
# option-acceptable interfaces (expect/generate UNICODE by default)
|
|
|
|
$json_text = to_json( $perl_scalar, { ascii => 1, pretty => 1 } );
|
|
$perl_scalar = from_json( $json_text, { utf8 => 1 } );
|
|
|
|
# Between (en|de)code_json and (to|from)_json, if you want to write
|
|
# a code which communicates to an outer world (encoded in UTF-8),
|
|
# recommend to use (en|de)code_json.
|
|
|
|
VERSION
|
|
2.53
|
|
|
|
This version is compatible with JSON::XS 2.27 and later.
|
|
|
|
NOTE
|
|
JSON::PP was inculded in "JSON" distribution. It comes to be a perl core
|
|
module in Perl 5.14. And JSON::PP will be split away it.
|
|
|
|
"JSON" distribution will inculde yet another JSON::PP modules. They are
|
|
JSNO::backportPP and so on. JSON.pm should work as it did at all.
|
|
|
|
DESCRIPTION
|
|
************************** CAUTION ********************************
|
|
* This is 'JSON module version 2' and there are many differences *
|
|
* to version 1.xx *
|
|
* Please check your applications useing old version. *
|
|
* See to 'INCOMPATIBLE CHANGES TO OLD VERSION' *
|
|
*******************************************************************
|
|
|
|
JSON (JavaScript Object Notation) is a simple data format. See to
|
|
<http://www.json.org/> and
|
|
"RFC4627"(<http://www.ietf.org/rfc/rfc4627.txt>).
|
|
|
|
This module converts Perl data structures to JSON and vice versa using
|
|
either JSON::XS or JSON::PP.
|
|
|
|
JSON::XS is the fastest and most proper JSON module on CPAN which must
|
|
be compiled and installed in your environment. JSON::PP is a pure-Perl
|
|
module which is bundled in this distribution and has a strong
|
|
compatibility to JSON::XS.
|
|
|
|
This module try to use JSON::XS by default and fail to it, use JSON::PP
|
|
instead. So its features completely depend on JSON::XS or JSON::PP.
|
|
|
|
See to "BACKEND MODULE DECISION".
|
|
|
|
To distinguish the module name 'JSON' and the format type JSON, the
|
|
former is quoted by C<> (its results vary with your using media), and
|
|
the latter is left just as it is.
|
|
|
|
Module name : "JSON"
|
|
|
|
Format type : JSON
|
|
|
|
FEATURES
|
|
* correct unicode handling
|
|
|
|
This module (i.e. backend modules) knows how to handle Unicode,
|
|
documents how and when it does so, and even documents what "correct"
|
|
means.
|
|
|
|
Even though there are limitations, this feature is available since
|
|
Perl version 5.6.
|
|
|
|
JSON::XS requires Perl 5.8.2 (but works correctly in 5.8.8 or
|
|
later), so in older versions "JSON" sholud call JSON::PP as the
|
|
backend which can be used since Perl 5.005.
|
|
|
|
With Perl 5.8.x JSON::PP works, but from 5.8.0 to 5.8.2, because of
|
|
a Perl side problem, JSON::PP works slower in the versions. And in
|
|
5.005, the Unicode handling is not available. See to "UNICODE
|
|
HANDLING ON PERLS" in JSON::PP for more information.
|
|
|
|
See also to "A FEW NOTES ON UNICODE AND PERL" in JSON::XS and
|
|
"ENCODING/CODESET_FLAG_NOTES" in JSON::XS.
|
|
|
|
* round-trip integrity
|
|
|
|
When you serialise a perl data structure using only data types
|
|
supported by JSON and Perl, the deserialised data structure is
|
|
identical on the Perl level. (e.g. the string "2.0" doesn't suddenly
|
|
become "2" just because it looks like a number). There *are* minor
|
|
exceptions to this, read the "MAPPING" section below to learn about
|
|
those.
|
|
|
|
* strict checking of JSON correctness
|
|
|
|
There is no guessing, no generating of illegal JSON texts by
|
|
default, and only JSON is accepted as input by default (the latter
|
|
is a security feature).
|
|
|
|
See to "FEATURES" in JSON::XS and "FEATURES" in JSON::PP.
|
|
|
|
* fast
|
|
|
|
This module returns a JSON::XS object itself if available. Compared
|
|
to other JSON modules and other serialisers such as Storable,
|
|
JSON::XS usually compares favourably in terms of speed, too.
|
|
|
|
If not available, "JSON" returns a JSON::PP object instead of
|
|
JSON::XS and it is very slow as pure-Perl.
|
|
|
|
* simple to use
|
|
|
|
This module has both a simple functional interface as well as an
|
|
object oriented interface interface.
|
|
|
|
* reasonably versatile output formats
|
|
|
|
You can choose between the most compact guaranteed-single-line
|
|
format possible (nice for simple line-based protocols), a pure-ASCII
|
|
format (for when your transport is not 8-bit clean, still supports
|
|
the whole Unicode range), or a pretty-printed format (for when you
|
|
want to read that stuff). Or you can combine those features in
|
|
whatever way you like.
|
|
|
|
FUNCTIONAL INTERFACE
|
|
Some documents are copied and modified from "FUNCTIONAL INTERFACE" in
|
|
JSON::XS. "to_json" and "from_json" are additional functions.
|
|
|
|
encode_json
|
|
$json_text = encode_json $perl_scalar
|
|
|
|
Converts the given Perl data structure to a UTF-8 encoded, binary
|
|
string.
|
|
|
|
This function call is functionally identical to:
|
|
|
|
$json_text = JSON->new->utf8->encode($perl_scalar)
|
|
|
|
decode_json
|
|
$perl_scalar = decode_json $json_text
|
|
|
|
The opposite of "encode_json": expects an UTF-8 (binary) string and
|
|
tries to parse that as an UTF-8 encoded JSON text, returning the
|
|
resulting reference.
|
|
|
|
This function call is functionally identical to:
|
|
|
|
$perl_scalar = JSON->new->utf8->decode($json_text)
|
|
|
|
to_json
|
|
$json_text = to_json($perl_scalar)
|
|
|
|
Converts the given Perl data structure to a json string.
|
|
|
|
This function call is functionally identical to:
|
|
|
|
$json_text = JSON->new->encode($perl_scalar)
|
|
|
|
Takes a hash reference as the second.
|
|
|
|
$json_text = to_json($perl_scalar, $flag_hashref)
|
|
|
|
So,
|
|
|
|
$json_text = to_json($perl_scalar, {utf8 => 1, pretty => 1})
|
|
|
|
equivalent to:
|
|
|
|
$json_text = JSON->new->utf8(1)->pretty(1)->encode($perl_scalar)
|
|
|
|
If you want to write a modern perl code which communicates to outer
|
|
world, you should use "encode_json" (supposed that JSON data are encoded
|
|
in UTF-8).
|
|
|
|
from_json
|
|
$perl_scalar = from_json($json_text)
|
|
|
|
The opposite of "to_json": expects a json string and tries to parse it,
|
|
returning the resulting reference.
|
|
|
|
This function call is functionally identical to:
|
|
|
|
$perl_scalar = JSON->decode($json_text)
|
|
|
|
Takes a hash reference as the second.
|
|
|
|
$perl_scalar = from_json($json_text, $flag_hashref)
|
|
|
|
So,
|
|
|
|
$perl_scalar = from_json($json_text, {utf8 => 1})
|
|
|
|
equivalent to:
|
|
|
|
$perl_scalar = JSON->new->utf8(1)->decode($json_text)
|
|
|
|
If you want to write a modern perl code which communicates to outer
|
|
world, you should use "decode_json" (supposed that JSON data are encoded
|
|
in UTF-8).
|
|
|
|
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 1 and 0 respectively and are
|
|
also used to represent JSON "true" and "false" in Perl strings.
|
|
|
|
JSON::true
|
|
Returns JSON true value which is blessed object. It "isa" JSON::Boolean
|
|
object.
|
|
|
|
JSON::false
|
|
Returns JSON false value which is blessed object. It "isa" JSON::Boolean
|
|
object.
|
|
|
|
JSON::null
|
|
Returns "undef".
|
|
|
|
See MAPPING, below, for more information on how JSON values are mapped
|
|
to Perl.
|
|
|
|
HOW DO I DECODE A DATA FROM OUTER AND ENCODE TO OUTER
|
|
This section supposes that your perl vresion is 5.8 or later.
|
|
|
|
If you know a JSON text from an outer world - a network, a file content,
|
|
and so on, is encoded in UTF-8, you should use "decode_json" or "JSON"
|
|
module object with "utf8" enable. And the decoded result will contain
|
|
UNICODE characters.
|
|
|
|
# from network
|
|
my $json = JSON->new->utf8;
|
|
my $json_text = CGI->new->param( 'json_data' );
|
|
my $perl_scalar = $json->decode( $json_text );
|
|
|
|
# from file content
|
|
local $/;
|
|
open( my $fh, '<', 'json.data' );
|
|
$json_text = <$fh>;
|
|
$perl_scalar = decode_json( $json_text );
|
|
|
|
If an outer data is not encoded in UTF-8, firstly you should "decode"
|
|
it.
|
|
|
|
use Encode;
|
|
local $/;
|
|
open( my $fh, '<', 'json.data' );
|
|
my $encoding = 'cp932';
|
|
my $unicode_json_text = decode( $encoding, <$fh> ); # UNICODE
|
|
|
|
# or you can write the below code.
|
|
#
|
|
# open( my $fh, "<:encoding($encoding)", 'json.data' );
|
|
# $unicode_json_text = <$fh>;
|
|
|
|
In this case, $unicode_json_text is of course UNICODE string. So you
|
|
cannot use "decode_json" nor "JSON" module object with "utf8" enable.
|
|
Instead of them, you use "JSON" module object with "utf8" disable or
|
|
"from_json".
|
|
|
|
$perl_scalar = $json->utf8(0)->decode( $unicode_json_text );
|
|
# or
|
|
$perl_scalar = from_json( $unicode_json_text );
|
|
|
|
Or "encode 'utf8'" and "decode_json":
|
|
|
|
$perl_scalar = decode_json( encode( 'utf8', $unicode_json_text ) );
|
|
# this way is not efficient.
|
|
|
|
And now, you want to convert your $perl_scalar into JSON data and send
|
|
it to an outer world - a network or a file content, and so on.
|
|
|
|
Your data usually contains UNICODE strings and you want the converted
|
|
data to be encoded in UTF-8, you should use "encode_json" or "JSON"
|
|
module object with "utf8" enable.
|
|
|
|
print encode_json( $perl_scalar ); # to a network? file? or display?
|
|
# or
|
|
print $json->utf8->encode( $perl_scalar );
|
|
|
|
If $perl_scalar does not contain UNICODE but $encoding-encoded strings
|
|
for some reason, then its characters are regarded as latin1 for perl
|
|
(because it does not concern with your $encoding). You cannot use
|
|
"encode_json" nor "JSON" module object with "utf8" enable. Instead of
|
|
them, you use "JSON" module object with "utf8" disable or "to_json".
|
|
Note that the resulted text is a UNICODE string but no problem to print
|
|
it.
|
|
|
|
# $perl_scalar contains $encoding encoded string values
|
|
$unicode_json_text = $json->utf8(0)->encode( $perl_scalar );
|
|
# or
|
|
$unicode_json_text = to_json( $perl_scalar );
|
|
# $unicode_json_text consists of characters less than 0x100
|
|
print $unicode_json_text;
|
|
|
|
Or "decode $encoding" all string values and "encode_json":
|
|
|
|
$perl_scalar->{ foo } = decode( $encoding, $perl_scalar->{ foo } );
|
|
# ... do it to each string values, then encode_json
|
|
$json_text = encode_json( $perl_scalar );
|
|
|
|
This method is a proper way but probably not efficient.
|
|
|
|
See to Encode, perluniintro.
|
|
|
|
COMMON OBJECT-ORIENTED INTERFACE
|
|
new
|
|
$json = JSON->new
|
|
|
|
Returns a new "JSON" object inherited from either JSON::XS or JSON::PP
|
|
that can be used to de/encode JSON strings.
|
|
|
|
All boolean flags described below are by default *disabled*.
|
|
|
|
The mutators for flags all return the JSON object again and thus calls
|
|
can be chained:
|
|
|
|
my $json = JSON->new->utf8->space_after->encode({a => [1,2]})
|
|
=> {"a": [1, 2]}
|
|
|
|
ascii
|
|
$json = $json->ascii([$enable])
|
|
|
|
$enabled = $json->get_ascii
|
|
|
|
If $enable is true (or missing), then the encode method will not
|
|
generate characters outside the code range 0..127. Any Unicode
|
|
characters outside that range will be escaped using either a single
|
|
\uXXXX or a double \uHHHH\uLLLLL escape sequence, as per RFC4627.
|
|
|
|
If $enable is false, then the 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.
|
|
|
|
This feature depends on the used Perl version and environment.
|
|
|
|
See to "UNICODE HANDLING ON PERLS" in JSON::PP if the backend is PP.
|
|
|
|
JSON->new->ascii(1)->encode([chr 0x10401])
|
|
=> ["\ud801\udc01"]
|
|
|
|
latin1
|
|
$json = $json->latin1([$enable])
|
|
|
|
$enabled = $json->get_latin1
|
|
|
|
If $enable is true (or missing), then the encode method will encode the
|
|
resulting JSON text as latin1 (or iso-8859-1), escaping any characters
|
|
outside the code range 0..255.
|
|
|
|
If $enable is false, then the encode method will not escape Unicode
|
|
characters unless required by the JSON syntax or other flags.
|
|
|
|
JSON->new->latin1->encode (["\x{89}\x{abc}"]
|
|
=> ["\x{89}\\u0abc"] # (perl syntax, U+abc escaped, U+89 not)
|
|
|
|
utf8
|
|
$json = $json->utf8([$enable])
|
|
|
|
$enabled = $json->get_utf8
|
|
|
|
If $enable is true (or missing), then the encode method will encode the
|
|
JSON result into UTF-8, as required by many protocols, while the 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
|
|
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 $enable is false, then the encode method will return the JSON string
|
|
as a (non-encoded) Unicode string, while 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.
|
|
|
|
Example, output UTF-16BE-encoded JSON:
|
|
|
|
use Encode;
|
|
$jsontext = encode "UTF-16BE", JSON::XS->new->encode ($object);
|
|
|
|
Example, decode UTF-32LE-encoded JSON:
|
|
|
|
use Encode;
|
|
$object = JSON::XS->new->decode (decode "UTF-32LE", $jsontext);
|
|
|
|
See to "UNICODE HANDLING ON PERLS" in JSON::PP if the backend is PP.
|
|
|
|
pretty
|
|
$json = $json->pretty([$enable])
|
|
|
|
This enables (or disables) all of the "indent", "space_before" and
|
|
"space_after" (and in the future possibly more) flags in one call to
|
|
generate the most readable (or most compact) form possible.
|
|
|
|
Equivalent to:
|
|
|
|
$json->indent->space_before->space_after
|
|
|
|
The indent space length is three and JSON::XS cannot change the indent
|
|
space length.
|
|
|
|
indent
|
|
$json = $json->indent([$enable])
|
|
|
|
$enabled = $json->get_indent
|
|
|
|
If $enable is true (or missing), then the "encode" method will use a
|
|
multiline format as output, putting every array member or object/hash
|
|
key-value pair into its own line, identing them properly.
|
|
|
|
If $enable is false, no newlines or indenting will be produced, and the
|
|
resulting JSON text is guarenteed not to contain any "newlines".
|
|
|
|
This setting has no effect when decoding JSON texts.
|
|
|
|
The indent space length is three. With JSON::PP, you can also access
|
|
"indent_length" to change indent space length.
|
|
|
|
space_before
|
|
$json = $json->space_before([$enable])
|
|
|
|
$enabled = $json->get_space_before
|
|
|
|
If $enable is true (or missing), then the "encode" method will add an
|
|
extra optional space before the ":" separating keys from values in JSON
|
|
objects.
|
|
|
|
If $enable is false, then the "encode" method will not add any extra
|
|
space at those places.
|
|
|
|
This setting has no effect when decoding JSON texts.
|
|
|
|
Example, space_before enabled, space_after and indent disabled:
|
|
|
|
{"key" :"value"}
|
|
|
|
space_after
|
|
$json = $json->space_after([$enable])
|
|
|
|
$enabled = $json->get_space_after
|
|
|
|
If $enable is true (or missing), then the "encode" method will add an
|
|
extra optional space after the ":" separating keys from values in JSON
|
|
objects and extra whitespace after the "," separating key-value pairs
|
|
and array members.
|
|
|
|
If $enable is false, then the "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"}
|
|
|
|
relaxed
|
|
$json = $json->relaxed([$enable])
|
|
|
|
$enabled = $json->get_relaxed
|
|
|
|
If $enable is true (or missing), then "decode" will accept some
|
|
extensions to normal JSON syntax (see below). "encode" will not be
|
|
affected in anyway. *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 $enable is false (the default), then "decode" will only accept valid
|
|
JSON texts.
|
|
|
|
Currently accepted extensions are:
|
|
|
|
* list items can have an end-comma
|
|
|
|
JSON *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
|
|
}
|
|
|
|
* 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...
|
|
]
|
|
|
|
canonical
|
|
$json = $json->canonical([$enable])
|
|
|
|
$enabled = $json->get_canonical
|
|
|
|
If $enable is true (or missing), then the "encode" method will output
|
|
JSON objects by sorting their keys. This is adding a comparatively high
|
|
overhead.
|
|
|
|
If $enable is false, then the "encode" method will output key-value
|
|
pairs in the order Perl stores them (which will likely change between
|
|
runs of the same script).
|
|
|
|
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.
|
|
|
|
allow_nonref
|
|
$json = $json->allow_nonref([$enable])
|
|
|
|
$enabled = $json->get_allow_nonref
|
|
|
|
If $enable is true (or missing), then the "encode" method can convert a
|
|
non-reference into its corresponding string, number or null JSON value,
|
|
which is an extension to RFC4627. Likewise, "decode" will accept those
|
|
JSON values instead of croaking.
|
|
|
|
If $enable is false, then the "encode" method will croak if it isn't
|
|
passed an arrayref or hashref, as JSON texts must either be an object or
|
|
array. Likewise, "decode" will croak if given something that is not a
|
|
JSON object or array.
|
|
|
|
JSON->new->allow_nonref->encode ("Hello, World!")
|
|
=> "Hello, World!"
|
|
|
|
allow_unknown
|
|
$json = $json->allow_unknown ([$enable])
|
|
|
|
$enabled = $json->get_allow_unknown
|
|
|
|
If $enable is true (or missing), then "encode" will *not* throw an
|
|
exception when it encounters values it cannot represent in JSON (for
|
|
example, filehandles) but instead will encode a JSON "null" value. Note
|
|
that blessed objects are not included here and are handled separately by
|
|
c<allow_nonref>.
|
|
|
|
If $enable is false (the default), then "encode" will throw an exception
|
|
when it encounters anything it cannot encode as JSON.
|
|
|
|
This option does not affect "decode" in any way, and it is recommended
|
|
to leave it off unless you know your communications partner.
|
|
|
|
allow_blessed
|
|
$json = $json->allow_blessed([$enable])
|
|
|
|
$enabled = $json->get_allow_blessed
|
|
|
|
If $enable is true (or missing), then the "encode" method will not barf
|
|
when it encounters a blessed reference. Instead, the value of the
|
|
convert_blessed option will decide whether "null" ("convert_blessed"
|
|
disabled or no "TO_JSON" method found) or a representation of the object
|
|
("convert_blessed" enabled and "TO_JSON" method found) is being encoded.
|
|
Has no effect on "decode".
|
|
|
|
If $enable is false (the default), then "encode" will throw an exception
|
|
when it encounters a blessed object.
|
|
|
|
convert_blessed
|
|
$json = $json->convert_blessed([$enable])
|
|
|
|
$enabled = $json->get_convert_blessed
|
|
|
|
If $enable is true (or missing), then "encode", upon encountering a
|
|
blessed object, will check for the availability of the "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. If no
|
|
"TO_JSON" method is found, the value of "allow_blessed" will decide what
|
|
to do.
|
|
|
|
The "TO_JSON" method may safely call die if it wants. If "TO_JSON"
|
|
returns other blessed objects, those will be handled in the same way.
|
|
"TO_JSON" must take care of not causing an endless recursion cycle (==
|
|
crash) in this case. The name of "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 the "to_json"
|
|
function or method.
|
|
|
|
This setting does not yet influence "decode" in any way.
|
|
|
|
If $enable is false, then the "allow_blessed" setting will decide what
|
|
to do when a blessed object is found.
|
|
|
|
convert_blessed_universally mode
|
|
If use "JSON" with "-convert_blessed_universally", the
|
|
"UNIVERSAL::TO_JSON" subroutine is defined as the below code:
|
|
|
|
*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
|
|
;
|
|
}
|
|
|
|
This will cause that "encode" method converts simple blessed objects
|
|
into JSON objects as non-blessed object.
|
|
|
|
JSON -convert_blessed_universally;
|
|
$json->allow_blessed->convert_blessed->encode( $blessed_object )
|
|
|
|
This feature is experimental and may be removed in the future.
|
|
|
|
filter_json_object
|
|
$json = $json->filter_json_object([$coderef])
|
|
|
|
When $coderef is specified, it will be called from "decode" each time it
|
|
decodes a JSON object. The only argument passed to the coderef 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: *not* "undef", which is a
|
|
valid scalar), the original deserialised hash will be inserted. This
|
|
setting can slow down decoding considerably.
|
|
|
|
When $coderef is omitted or undefined, any existing callback will be
|
|
removed and "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}');
|
|
|
|
filter_json_single_key_object
|
|
$json = $json->filter_json_single_key_object($key [=> $coderef])
|
|
|
|
Works remotely similar to "filter_json_object", but is only called for
|
|
JSON objects having a single key named $key.
|
|
|
|
This $coderef is called before the one specified via
|
|
"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 "undef" but the empty
|
|
list), the callback from "filter_json_object" will be called next, as if
|
|
no single-key callback were specified.
|
|
|
|
If $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 "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 "__class_whatever__", or
|
|
"$__dollars_are_rarely_used__$" or "}ugly_brace_placement", or even
|
|
things like "__class_md5sum(classname)__", to reduce the risk of
|
|
clashing with real hashes.
|
|
|
|
Example, decode JSON objects of the form "{ "__widget__" => <id> }" into
|
|
the corresponding $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} }
|
|
}
|
|
|
|
shrink
|
|
$json = $json->shrink([$enable])
|
|
|
|
$enabled = $json->get_shrink
|
|
|
|
With JSON::XS, this flag resizes strings generated by either "encode" or
|
|
"decode" to their minimum size possible. This can save memory when your
|
|
JSON texts are either very very long or you have many short strings. It
|
|
will also try to downgrade any strings to octet-form if possible: perl
|
|
stores strings internally either in an encoding called UTF-X or in
|
|
octet-form. The latter cannot store everything but uses less space in
|
|
general (and some buggy Perl or C code might even rely on that internal
|
|
representation being used).
|
|
|
|
With JSON::PP, it is noop about resizing strings but tries
|
|
"utf8::downgrade" to the returned string by "encode". See to utf8.
|
|
|
|
See to "OBJECT-ORIENTED INTERFACE" in JSON::XS and "METHODS" in
|
|
JSON::PP.
|
|
|
|
max_depth
|
|
$json = $json->max_depth([$maximum_nesting_depth])
|
|
|
|
$max_depth = $json->get_max_depth
|
|
|
|
Sets the maximum nesting level (default 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 "{" or
|
|
"[" characters without their matching closing parenthesis crossed to
|
|
reach a given character in a string.
|
|
|
|
If no argument is given, the highest possible setting will be used,
|
|
which is rarely useful.
|
|
|
|
Note that nesting is implemented by recursion in C. The default value
|
|
has been chosen to be as large as typical operating systems allow
|
|
without crashing. (JSON::XS)
|
|
|
|
With JSON::PP as the backend, when a large value (100 or more) was set
|
|
and it de/encodes a deep nested object/text, it may raise a warning
|
|
'Deep recursion on subroutin' at the perl runtime phase.
|
|
|
|
See "SECURITY CONSIDERATIONS" in JSON::XS for more info on why this is
|
|
useful.
|
|
|
|
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 0, meaning no limit. When "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 "encode" (yet).
|
|
|
|
If no argument is given, the limit check will be deactivated (same as
|
|
when 0 is specified).
|
|
|
|
See "SECURITY CONSIDERATIONS" in JSON::XS, below, for more info on why
|
|
this is useful.
|
|
|
|
encode
|
|
$json_text = $json->encode($perl_scalar)
|
|
|
|
Converts the given Perl data structure (a simple scalar or a reference
|
|
to a hash or array) to its JSON representation. Simple scalars will be
|
|
converted into JSON string or number sequences, while references to
|
|
arrays become JSON arrays and references to hashes become JSON objects.
|
|
Undefined Perl values (e.g. "undef") become JSON "null" values.
|
|
References to the integers 0 and 1 are converted into "true" and
|
|
"false".
|
|
|
|
decode
|
|
$perl_scalar = $json->decode($json_text)
|
|
|
|
The opposite of "encode": expects a JSON text and tries to parse it,
|
|
returning the resulting simple scalar or reference. Croaks on error.
|
|
|
|
JSON numbers and strings become simple Perl scalars. JSON arrays become
|
|
Perl arrayrefs and JSON objects become Perl hashrefs. "true" becomes 1
|
|
("JSON::true"), "false" becomes 0 ("JSON::false") and "null" becomes
|
|
"undef".
|
|
|
|
decode_prefix
|
|
($perl_scalar, $characters) = $json->decode_prefix($json_text)
|
|
|
|
This works like the "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.
|
|
|
|
JSON->new->decode_prefix ("[1] the tail")
|
|
=> ([], 3)
|
|
|
|
See to "OBJECT-ORIENTED INTERFACE" in JSON::XS
|
|
|
|
property
|
|
$boolean = $json->property($property_name)
|
|
|
|
Returns a boolean value about above some properties.
|
|
|
|
The available properties are "ascii", "latin1", "utf8",
|
|
"indent","space_before", "space_after", "relaxed", "canonical",
|
|
"allow_nonref", "allow_unknown", "allow_blessed", "convert_blessed",
|
|
"shrink", "max_depth" and "max_size".
|
|
|
|
$boolean = $json->property('utf8');
|
|
=> 0
|
|
$json->utf8;
|
|
$boolean = $json->property('utf8');
|
|
=> 1
|
|
|
|
Sets the property with a given boolean value.
|
|
|
|
$json = $json->property($property_name => $boolean);
|
|
|
|
With no argumnt, it returns all the above properties as a hash
|
|
reference.
|
|
|
|
$flag_hashref = $json->property();
|
|
|
|
INCREMENTAL PARSING
|
|
Most of this section are copied and modified from "INCREMENTAL PARSING"
|
|
in JSON::XS.
|
|
|
|
In some cases, there is the need for incremental parsing of JSON texts.
|
|
This module 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 "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).
|
|
|
|
The backend 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 parenthese
|
|
mismatches. 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. "max_size") to ensure the parser will
|
|
stop parsing in the presence if syntax errors.
|
|
|
|
The following methods implement this incremental parser.
|
|
|
|
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 $string is given, then this string is appended to the already
|
|
existing JSON fragment stored in the $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 *one* JSON object. If that is successful, it will return this
|
|
object, otherwise it will return "undef". If there is a parse error,
|
|
this method will croak just as "decode" would do (one can then use
|
|
"incr_skip" to skip the errornous 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 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]");
|
|
|
|
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 *only* works when a preceding call
|
|
to "incr_parse" in *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 *will* fail
|
|
under real world conditions). As a special exception, you can also call
|
|
this method before having parsed anything.
|
|
|
|
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).
|
|
|
|
$json->incr_text =~ s/\s*,\s*//;
|
|
|
|
In Perl 5.005, "lvalue" attribute is not available. You must write codes
|
|
like the below:
|
|
|
|
$string = $json->incr_text;
|
|
$string =~ s/\s*,\s*//;
|
|
$json->incr_text( $string );
|
|
|
|
incr_skip
|
|
$json->incr_skip
|
|
|
|
This will reset the state of the incremental parser and will remove the
|
|
parsed text from the input buffer. This is useful after "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.
|
|
|
|
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 ot repeatedly parse JSON objects and want to
|
|
ignore any trailing data, which means you have to reset the parser after
|
|
each successful decode.
|
|
|
|
See to "INCREMENTAL PARSING" in JSON::XS for examples.
|
|
|
|
JSON::PP SUPPORT METHODS
|
|
The below methods are JSON::PP own methods, so when "JSON" works with
|
|
JSON::PP (i.e. the created object is a JSON::PP object), available. See
|
|
to "JSON::PP OWN METHODS" in JSON::PP in detail.
|
|
|
|
If you use "JSON" with additonal "-support_by_pp", some methods are
|
|
available even with JSON::XS. See to "USE PP FEATURES EVEN THOUGH XS
|
|
BACKEND".
|
|
|
|
BEING { $ENV{PERL_JSON_BACKEND} = 'JSON::XS' }
|
|
|
|
use JSON -support_by_pp;
|
|
|
|
my $json = new JSON;
|
|
$json->allow_nonref->escape_slash->encode("/");
|
|
|
|
# functional interfaces too.
|
|
print to_json(["/"], {escape_slash => 1});
|
|
print from_json('["foo"]', {utf8 => 1});
|
|
|
|
If you do not want to all functions but "-support_by_pp", use
|
|
"-no_export".
|
|
|
|
use JSON -support_by_pp, -no_export;
|
|
# functional interfaces are not exported.
|
|
|
|
allow_singlequote
|
|
$json = $json->allow_singlequote([$enable])
|
|
|
|
If $enable is true (or missing), then "decode" will accept any JSON
|
|
strings quoted by single quotations that are invalid JSON format.
|
|
|
|
$json->allow_singlequote->decode({"foo":'bar'});
|
|
$json->allow_singlequote->decode({'foo':"bar"});
|
|
$json->allow_singlequote->decode({'foo':'bar'});
|
|
|
|
As same as the "relaxed" option, this option may be used to parse
|
|
application-specific files written by humans.
|
|
|
|
allow_barekey
|
|
$json = $json->allow_barekey([$enable])
|
|
|
|
If $enable is true (or missing), then "decode" will accept bare keys of
|
|
JSON object that are invalid JSON format.
|
|
|
|
As same as the "relaxed" option, this option may be used to parse
|
|
application-specific files written by humans.
|
|
|
|
$json->allow_barekey->decode('{foo:"bar"}');
|
|
|
|
allow_bignum
|
|
$json = $json->allow_bignum([$enable])
|
|
|
|
If $enable is true (or missing), then "decode" will convert the big
|
|
integer Perl cannot handle as integer into a Math::BigInt object and
|
|
convert a floating number (any) into a Math::BigFloat.
|
|
|
|
On the contary, "encode" converts "Math::BigInt" objects and
|
|
"Math::BigFloat" objects into JSON numbers with "allow_blessed" enable.
|
|
|
|
$json->allow_nonref->allow_blessed->allow_bignum;
|
|
$bigfloat = $json->decode('2.000000000000000000000000001');
|
|
print $json->encode($bigfloat);
|
|
# => 2.000000000000000000000000001
|
|
|
|
See to MAPPING aboout the conversion of JSON number.
|
|
|
|
loose
|
|
$json = $json->loose([$enable])
|
|
|
|
The unescaped [\x00-\x1f\x22\x2f\x5c] strings are invalid in JSON
|
|
strings and the module doesn't allow to "decode" to these (except for
|
|
\x2f). If $enable is true (or missing), then "decode" will accept these
|
|
unescaped strings.
|
|
|
|
$json->loose->decode(qq|["abc
|
|
def"]|);
|
|
|
|
See to "JSON::PP OWN METHODS" in JSON::PP.
|
|
|
|
escape_slash
|
|
$json = $json->escape_slash([$enable])
|
|
|
|
According to JSON Grammar, *slash* (U+002F) is escaped. But by default
|
|
JSON backend modules encode strings without escaping slash.
|
|
|
|
If $enable is true (or missing), then "encode" will escape slashes.
|
|
|
|
indent_length
|
|
$json = $json->indent_length($length)
|
|
|
|
With JSON::XS, The indent space length is 3 and cannot be changed. With
|
|
JSON::PP, it sets the indent space length with the given $length. The
|
|
default is 3. The acceptable range is 0 to 15.
|
|
|
|
sort_by
|
|
$json = $json->sort_by($function_name)
|
|
$json = $json->sort_by($subroutine_ref)
|
|
|
|
If $function_name or $subroutine_ref are set, its sort routine are used.
|
|
|
|
$js = $pc->sort_by(sub { $JSON::PP::a cmp $JSON::PP::b })->encode($obj);
|
|
# is($js, q|{"a":1,"b":2,"c":3,"d":4,"e":5,"f":6,"g":7,"h":8,"i":9}|);
|
|
|
|
$js = $pc->sort_by('own_sort')->encode($obj);
|
|
# is($js, q|{"a":1,"b":2,"c":3,"d":4,"e":5,"f":6,"g":7,"h":8,"i":9}|);
|
|
|
|
sub JSON::PP::own_sort { $JSON::PP::a cmp $JSON::PP::b }
|
|
|
|
As the sorting routine runs in the JSON::PP scope, the given subroutine
|
|
name and the special variables $a, $b will begin with 'JSON::PP::'.
|
|
|
|
If $integer is set, then the effect is same as "canonical" on.
|
|
|
|
See to "JSON::PP OWN METHODS" in JSON::PP.
|
|
|
|
MAPPING
|
|
This section is copied from JSON::XS and modified to "JSON". JSON::XS
|
|
and JSON::PP mapping mechanisms are almost equivalent.
|
|
|
|
See to "MAPPING" in JSON::XS.
|
|
|
|
JSON -> PERL
|
|
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).
|
|
|
|
array
|
|
A JSON array becomes a reference to an array in Perl.
|
|
|
|
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.
|
|
|
|
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, "JSON" 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 toa 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, "JSON" only guarantees precision up to
|
|
but not including the leats significant bit.
|
|
|
|
If the backend is JSON::PP and "allow_bignum" is enable, the big
|
|
integers and the numeric can be optionally converted into
|
|
Math::BigInt and Math::BigFloat objects.
|
|
|
|
true, false
|
|
These JSON atoms become "JSON::true" and "JSON::false",
|
|
respectively. They are overloaded to act almost exactly like the
|
|
numbers 1 and 0. You can check wether a scalar is a JSON boolean by
|
|
using the "JSON::is_bool" function.
|
|
|
|
If "JSON::true" and "JSON::false" are used as strings or compared as
|
|
strings, they represent as "true" and "false" respectively.
|
|
|
|
print JSON::true . "\n";
|
|
=> true
|
|
print JSON::true + 1;
|
|
=> 1
|
|
|
|
ok(JSON::true eq 'true');
|
|
ok(JSON::true eq '1');
|
|
ok(JSON::true == 1);
|
|
|
|
"JSON" will install these missing overloading features to the
|
|
backend modules.
|
|
|
|
null
|
|
A JSON null atom becomes "undef" in Perl.
|
|
|
|
"JSON::null" returns "unddef".
|
|
|
|
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.
|
|
|
|
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 that can change between runs of the
|
|
same program but stays generally the same within a single run of a
|
|
program. "JSON" optionally sort the hash keys (determined by the
|
|
*canonical* flag), so the same datastructure will serialise to the
|
|
same JSON text (given same settings and version of JSON::XS), 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.
|
|
|
|
In future, the ordered object feature will be added to JSON::PP
|
|
using "tie" mechanism.
|
|
|
|
array references
|
|
Perl array references become JSON arrays.
|
|
|
|
other references
|
|
Other unblessed references are generally not allowed and will cause
|
|
an exception to be thrown, except for references to the integers 0
|
|
and 1, which get turned into "false" and "true" atoms in JSON. You
|
|
can also use "JSON::false" and "JSON::true" to improve readability.
|
|
|
|
to_json [\0,JSON::true] # yields [false,true]
|
|
|
|
JSON::true, JSON::false, JSON::null
|
|
These special values become JSON true and JSON false values,
|
|
respectively. You can also use "\1" and "\0" directly if you want.
|
|
|
|
JSON::null returns "undef".
|
|
|
|
blessed objects
|
|
Blessed objects are not directly representable in JSON. See the
|
|
"allow_blessed" and "convert_blessed" methods on various options on
|
|
how to deal with this: basically, you can choose between throwing an
|
|
exception, encoding the reference as if it weren't blessed, or
|
|
provide your own serialiser method.
|
|
|
|
With "convert_blessed_universally" mode, "encode" converts blessed
|
|
hash references or blessed array references (contains other blessed
|
|
references) into JSON members and arrays.
|
|
|
|
use JSON -convert_blessed_universally;
|
|
JSON->new->allow_blessed->convert_blessed->encode( $blessed_object );
|
|
|
|
See to convert_blessed.
|
|
|
|
simple scalars
|
|
Simple Perl scalars (any scalar that is not a reference) are the
|
|
most difficult objects to encode: JSON::XS and JSON::PP will encode
|
|
undefined scalars as JSON "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 choise is yours.
|
|
|
|
You can not currently force the type in other, less obscure, ways.
|
|
|
|
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.
|
|
|
|
Big Number
|
|
If the backend is JSON::PP and "allow_bignum" is enable, "encode"
|
|
converts "Math::BigInt" objects and "Math::BigFloat" objects into
|
|
JSON numbers.
|
|
|
|
JSON and ECMAscript
|
|
See to "JSON and ECMAscript" in JSON::XS.
|
|
|
|
JSON and YAML
|
|
JSON is not a subset of YAML. See to "JSON and YAML" in JSON::XS.
|
|
|
|
BACKEND MODULE DECISION
|
|
When you use "JSON", "JSON" tries to "use" JSON::XS. If this call
|
|
failed, it will "uses" JSON::PP. The required JSON::XS version is *2.2*
|
|
or later.
|
|
|
|
The "JSON" constructor method returns an object inherited from the
|
|
backend module, and JSON::XS object is a blessed scaler reference while
|
|
JSON::PP is a blessed hash reference.
|
|
|
|
So, your program should not depend on the backend module, especially
|
|
returned objects should not be modified.
|
|
|
|
my $json = JSON->new; # XS or PP?
|
|
$json->{stash} = 'this is xs object'; # this code may raise an error!
|
|
|
|
To check the backend module, there are some methods - "backend", "is_pp"
|
|
and "is_xs".
|
|
|
|
JSON->backend; # 'JSON::XS' or 'JSON::PP'
|
|
|
|
JSON->backend->is_pp: # 0 or 1
|
|
|
|
JSON->backend->is_xs: # 1 or 0
|
|
|
|
$json->is_xs; # 1 or 0
|
|
|
|
$json->is_pp; # 0 or 1
|
|
|
|
If you set an enviornment variable "PERL_JSON_BACKEND", The calling
|
|
action will be changed.
|
|
|
|
PERL_JSON_BACKEND = 0 or PERL_JSON_BACKEND = 'JSON::PP'
|
|
Always use JSON::PP
|
|
|
|
PERL_JSON_BACKEND == 1 or PERL_JSON_BACKEND = 'JSON::XS,JSON::PP'
|
|
(The default) Use compiled JSON::XS if it is properly compiled &
|
|
installed, otherwise use JSON::PP.
|
|
|
|
PERL_JSON_BACKEND == 2 or PERL_JSON_BACKEND = 'JSON::XS'
|
|
Always use compiled JSON::XS, die if it isn't properly compiled &
|
|
installed.
|
|
|
|
PERL_JSON_BACKEND = 'JSON::backportPP'
|
|
Always use JSON::backportPP. JSON::backportPP is JSON::PP back port
|
|
module. "JSON" includs JSON::backportPP instead of JSON::PP.
|
|
|
|
These ideas come from DBI::PurePerl mechanism.
|
|
|
|
example:
|
|
|
|
BEGIN { $ENV{PERL_JSON_BACKEND} = 'JSON::PP' }
|
|
use JSON; # always uses JSON::PP
|
|
|
|
In future, it may be able to specify another module.
|
|
|
|
USE PP FEATURES EVEN THOUGH XS BACKEND
|
|
Many methods are available with either JSON::XS or JSON::PP and when the
|
|
backend module is JSON::XS, if any JSON::PP specific (i.e. JSON::XS
|
|
unspported) method is called, it will "warn" and be noop.
|
|
|
|
But If you "use" "JSON" passing the optional string "-support_by_pp", it
|
|
makes a part of those unupported methods available. This feature is
|
|
achieved by using JSON::PP in "de/encode".
|
|
|
|
BEGIN { $ENV{PERL_JSON_BACKEND} = 2 } # with JSON::XS
|
|
use JSON -support_by_pp;
|
|
my $json = new JSON;
|
|
$json->allow_nonref->escape_slash->encode("/");
|
|
|
|
At this time, the returned object is a "JSON::Backend::XS::Supportable"
|
|
object (re-blessed XS object), and by checking JSON::XS unsupported
|
|
flags in de/encoding, can support some unsupported methods - "loose",
|
|
"allow_bignum", "allow_barekey", "allow_singlequote", "escape_slash" and
|
|
"indent_length".
|
|
|
|
When any unsupported methods are not enable, "XS de/encode" will be used
|
|
as is. The switch is achieved by changing the symbolic tables.
|
|
|
|
"-support_by_pp" is effective only when the backend module is JSON::XS
|
|
and it makes the de/encoding speed down a bit.
|
|
|
|
See to "JSON::PP SUPPORT METHODS".
|
|
|
|
INCOMPATIBLE CHANGES TO OLD VERSION
|
|
There are big incompatibility between new version (2.00) and old (1.xx).
|
|
If you use old "JSON" 1.xx in your code, please check it.
|
|
|
|
See to "Transition ways from 1.xx to 2.xx."
|
|
|
|
jsonToObj and objToJson are obsoleted.
|
|
Non Perl-style name "jsonToObj" and "objToJson" are obsoleted (but
|
|
not yet deleted from the source). If you use these functions in your
|
|
code, please replace them with "from_json" and "to_json".
|
|
|
|
Global variables are no longer available.
|
|
"JSON" class variables - $JSON::AUTOCONVERT, $JSON::BareKey, etc...
|
|
- are not available any longer. Instead, various features can be
|
|
used through object methods.
|
|
|
|
Package JSON::Converter and JSON::Parser are deleted.
|
|
Now "JSON" bundles with JSON::PP which can handle JSON more properly
|
|
than them.
|
|
|
|
Package JSON::NotString is deleted.
|
|
There was "JSON::NotString" class which represents JSON value
|
|
"true", "false", "null" and numbers. It was deleted and replaced by
|
|
"JSON::Boolean".
|
|
|
|
"JSON::Boolean" represents "true" and "false".
|
|
|
|
"JSON::Boolean" does not represent "null".
|
|
|
|
"JSON::null" returns "undef".
|
|
|
|
"JSON" makes JSON::XS::Boolean and JSON::PP::Boolean is-a relation
|
|
to JSON::Boolean.
|
|
|
|
function JSON::Number is obsoleted.
|
|
"JSON::Number" is now needless because JSON::XS and JSON::PP have
|
|
round-trip integrity.
|
|
|
|
JSONRPC modules are deleted.
|
|
Perl implementation of JSON-RPC protocol - "JSONRPC ",
|
|
"JSONRPC::Transport::HTTP" and "Apache::JSONRPC " are deleted in
|
|
this distribution. Instead of them, there is JSON::RPC which
|
|
supports JSON-RPC protocol version 1.1.
|
|
|
|
Transition ways from 1.xx to 2.xx.
|
|
You should set "suport_by_pp" mode firstly, because it is always
|
|
successful for the below codes even with JSON::XS.
|
|
|
|
use JSON -support_by_pp;
|
|
|
|
Exported jsonToObj (simple)
|
|
from_json($json_text);
|
|
|
|
Exported objToJson (simple)
|
|
to_json($perl_scalar);
|
|
|
|
Exported jsonToObj (advanced)
|
|
$flags = {allow_barekey => 1, allow_singlequote => 1};
|
|
from_json($json_text, $flags);
|
|
|
|
equivalent to:
|
|
|
|
$JSON::BareKey = 1;
|
|
$JSON::QuotApos = 1;
|
|
jsonToObj($json_text);
|
|
|
|
Exported objToJson (advanced)
|
|
$flags = {allow_blessed => 1, allow_barekey => 1};
|
|
to_json($perl_scalar, $flags);
|
|
|
|
equivalent to:
|
|
|
|
$JSON::BareKey = 1;
|
|
objToJson($perl_scalar);
|
|
|
|
jsonToObj as object method
|
|
$json->decode($json_text);
|
|
|
|
objToJson as object method
|
|
$json->encode($perl_scalar);
|
|
|
|
new method with parameters
|
|
The "new" method in 2.x takes any parameters no longer. You can set
|
|
parameters instead;
|
|
|
|
$json = JSON->new->pretty;
|
|
|
|
$JSON::Pretty, $JSON::Indent, $JSON::Delimiter
|
|
If "indent" is enable, that means $JSON::Pretty flag set. And
|
|
$JSON::Delimiter was substituted by "space_before" and
|
|
"space_after". In conclusion:
|
|
|
|
$json->indent->space_before->space_after;
|
|
|
|
Equivalent to:
|
|
|
|
$json->pretty;
|
|
|
|
To change indent length, use "indent_length".
|
|
|
|
(Only with JSON::PP, if "-support_by_pp" is not used.)
|
|
|
|
$json->pretty->indent_length(2)->encode($perl_scalar);
|
|
|
|
$JSON::BareKey
|
|
(Only with JSON::PP, if "-support_by_pp" is not used.)
|
|
|
|
$json->allow_barekey->decode($json_text)
|
|
|
|
$JSON::ConvBlessed
|
|
use "-convert_blessed_universally". See to convert_blessed.
|
|
|
|
$JSON::QuotApos
|
|
(Only with JSON::PP, if "-support_by_pp" is not used.)
|
|
|
|
$json->allow_singlequote->decode($json_text)
|
|
|
|
$JSON::SingleQuote
|
|
Disable. "JSON" does not make such a invalid JSON string any longer.
|
|
|
|
$JSON::KeySort
|
|
$json->canonical->encode($perl_scalar)
|
|
|
|
This is the ascii sort.
|
|
|
|
If you want to use with your own sort routine, check the "sort_by"
|
|
method.
|
|
|
|
(Only with JSON::PP, even if "-support_by_pp" is used currently.)
|
|
|
|
$json->sort_by($sort_routine_ref)->encode($perl_scalar)
|
|
|
|
$json->sort_by(sub { $JSON::PP::a <=> $JSON::PP::b })->encode($perl_scalar)
|
|
|
|
Can't access $a and $b but $JSON::PP::a and $JSON::PP::b.
|
|
|
|
$JSON::SkipInvalid
|
|
$json->allow_unknown
|
|
|
|
$JSON::AUTOCONVERT
|
|
Needless. "JSON" backend modules have the round-trip integrity.
|
|
|
|
$JSON::UTF8
|
|
Needless because "JSON" (JSON::XS/JSON::PP) sets the UTF8 flag on
|
|
properly.
|
|
|
|
# With UTF8-flagged strings
|
|
|
|
$json->allow_nonref;
|
|
$str = chr(1000); # UTF8-flagged
|
|
|
|
$json_text = $json->utf8(0)->encode($str);
|
|
utf8::is_utf8($json_text);
|
|
# true
|
|
$json_text = $json->utf8(1)->encode($str);
|
|
utf8::is_utf8($json_text);
|
|
# false
|
|
|
|
$str = '"' . chr(1000) . '"'; # UTF8-flagged
|
|
|
|
$perl_scalar = $json->utf8(0)->decode($str);
|
|
utf8::is_utf8($perl_scalar);
|
|
# true
|
|
$perl_scalar = $json->utf8(1)->decode($str);
|
|
# died because of 'Wide character in subroutine'
|
|
|
|
See to "A FEW NOTES ON UNICODE AND PERL" in JSON::XS.
|
|
|
|
$JSON::UnMapping
|
|
Disable. See to MAPPING.
|
|
|
|
$JSON::SelfConvert
|
|
This option was deleted. Instead of it, if a givien blessed object
|
|
has the "TO_JSON" method, "TO_JSON" will be executed with
|
|
"convert_blessed".
|
|
|
|
$json->convert_blessed->encode($bleesed_hashref_or_arrayref)
|
|
# if need, call allow_blessed
|
|
|
|
Note that it was "toJson" in old version, but now not "toJson" but
|
|
"TO_JSON".
|
|
|
|
TODO
|
|
example programs
|
|
|
|
THREADS
|
|
No test with JSON::PP. If with JSON::XS, See to "THREADS" in JSON::XS.
|
|
|
|
BUGS
|
|
Please report bugs relevant to "JSON" to <makamaka[at]cpan.org>.
|
|
|
|
SEE ALSO
|
|
Most of the document is copied and modified from JSON::XS doc.
|
|
|
|
JSON::XS, JSON::PP
|
|
|
|
"RFC4627"(<http://www.ietf.org/rfc/rfc4627.txt>)
|
|
|
|
AUTHOR
|
|
Makamaka Hannyaharamitu, <makamaka[at]cpan.org>
|
|
|
|
JSON::XS was written by Marc Lehmann <schmorp[at]schmorp.de>
|
|
|
|
The relese of this new version owes to the courtesy of Marc Lehmann.
|
|
|
|
COPYRIGHT AND LICENSE
|
|
Copyright 2005-2011 by Makamaka Hannyaharamitu
|
|
|
|
This library is free software; you can redistribute it and/or modify it
|
|
under the same terms as Perl itself.
|
|
|