| Index: third_party/JSON/JSON-2.59/README
|
| diff --git a/third_party/JSON/JSON-2.59/README b/third_party/JSON/JSON-2.59/README
|
| deleted file mode 100644
|
| index 839c46212f4671ecd5b19b4534a134870b7c63b9..0000000000000000000000000000000000000000
|
| --- a/third_party/JSON/JSON-2.59/README
|
| +++ /dev/null
|
| @@ -1,1566 +0,0 @@
|
| -JSON version 2.58
|
| -=================
|
| -
|
| -"JSON::PP" was earlier included in the "JSON" distribution,
|
| -but has since Perl 5.14 been a core module. For this reason,
|
| -"JSON::PP" was removed from the "JSON" distribution and can
|
| -now be found also in the Perl5 repository at
|
| -
|
| - http://perl5.git.perl.org/perl.git
|
| -
|
| -(The newest "JSON::PP" version still exists in CPAN.)
|
| -
|
| -Instead, the "JSON" distribution will include "JSON::backportPP"
|
| -for backwards computability. JSON.pm should thus work as it did before.
|
| -
|
| -=================
|
| -
|
| -INSTALLATION
|
| -
|
| -To install this module type the following:
|
| -
|
| - perl Makefile.PL
|
| - make
|
| - make test
|
| - make install
|
| -
|
| -if you use cpanm, can install JSON::XS at once.
|
| -
|
| - cpanm --with-recommends JSON
|
| -
|
| -
|
| -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.58
|
| -
|
| - This version is compatible with JSON::XS 2.27 and later.
|
| -
|
| -NOTE
|
| - JSON::PP was earlier included in the "JSON" distribution, but has since
|
| - Perl 5.14 been a core module. For this reason, JSON::PP was removed from
|
| - the JSON distribution and can now be found also in the Perl5 repository
|
| - at
|
| -
|
| - * <http://perl5.git.perl.org/perl.git>
|
| -
|
| - (The newest JSON::PP version still exists in CPAN.)
|
| -
|
| - Instead, the "JSON" distribution will include JSON::backportPP for
|
| - backwards computability. JSON.pm should thus work as it did before.
|
| -
|
| -DESCRIPTION
|
| - ************************** CAUTION ********************************
|
| - * This is 'JSON module version 2' and there are many differences *
|
| - * to version 1.xx *
|
| - * Please check your applications using 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" should 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 favorably 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 version 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, identifying them properly.
|
| -
|
| - If $enable is false, no newlines or indenting will be produced, and the
|
| - resulting JSON text is guaranteed 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 subroutine' 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 argument, 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 parenthesis
|
| - 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 erroneous part). This is the most common way of
|
| - using the method.
|
| -
|
| - And finally, in list context, it will try to extract as many objects
|
| - from the stream as it can find and return them, or the empty list
|
| - otherwise. For this to work, there must be no separators 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 to 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 additional "-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 = JSON->new;
|
| - $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 contrary, "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 about 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 to a JSON string).
|
| -
|
| - Numbers containing a fractional or exponential part will always be
|
| - represented as numeric (floating point) values, possibly at a loss
|
| - of precision (in which case you might lose perfect roundtripping
|
| - ability, but the JSON number will still be re-encoded as a JSON
|
| - number).
|
| -
|
| - Note that precision is not accuracy - binary floating point values
|
| - cannot represent most decimal fractions exactly, and when converting
|
| - from and to floating point, "JSON" only guarantees precision up to
|
| - but not including the least 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 whether 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 "undef".
|
| -
|
| - 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 data structure 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 choice 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 scalar 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 environment 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" includes 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
|
| - unsupported) 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 unsupported 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 = JSON->new;
|
| - $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 given blessed object
|
| - has the "TO_JSON" method, "TO_JSON" will be executed with
|
| - "convert_blessed".
|
| -
|
| - $json->convert_blessed->encode($blessed_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 release of this new version owes to the courtesy of Marc Lehmann.
|
| -
|
| -COPYRIGHT AND LICENSE
|
| - Copyright 2005-2013 by Makamaka Hannyaharamitu
|
| -
|
| - This library is free software; you can redistribute it and/or modify it
|
| - under the same terms as Perl itself.
|
| -
|
|
|
Chromium Code Reviews
