Add JSON.pm to third_party

third_party/JSON/JSON-2.58/README

+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
+
+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.
+