Revert 205057 "Add JSON.pm to third_party"

trunk/src/third_party/JSON/JSON-2.59/blib/man3/JSON__backportPP.3pm

-.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
-.\"
-.\" Standard preamble:
-.\" ========================================================================
-.de Sp \" Vertical space (when we can't use .PP)
-.if t .sp .5v
-.if n .sp
-..
-.de Vb \" Begin verbatim text
-.ft CW
-.nf
-.ne \\$1
-..
-.de Ve \" End verbatim text
-.ft R
-.fi
-..
-.\" Set up some character translations and predefined strings.  \*(-- will
-.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
-.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
-.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
-.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
-.\" nothing in troff, for use with C<>.
-.tr \(*W-
-.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
-.ie n \{\
-.    ds -- \(*W-
-.    ds PI pi
-.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
-.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
-.    ds L" ""
-.    ds R" ""
-.    ds C` ""
-.    ds C' ""
-'br\}
-.el\{\
-.    ds -- \|\(em\|
-.    ds PI \(*p
-.    ds L" ``
-.    ds R" ''
-'br\}
-.\"
-.\" Escape single quotes in literal strings from groff's Unicode transform.
-.ie \n(.g .ds Aq \(aq
-.el       .ds Aq '
-.\"
-.\" If the F register is turned on, we'll generate index entries on stderr for
-.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
-.\" entries marked with X<> in POD.  Of course, you'll have to process the
-.\" output yourself in some meaningful fashion.
-.ie \nF \{\
-.    de IX
-.    tm Index:\\$1\t\\n%\t"\\$2"
-..
-.    nr % 0
-.    rr F
-.\}
-.el \{\
-.    de IX
-..
-.\}
-.\"
-.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
-.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
-.    \" fudge factors for nroff and troff
-.if n \{\
-.    ds #H 0
-.    ds #V .8m
-.    ds #F .3m
-.    ds #[ \f1
-.    ds #] \fP
-.\}
-.if t \{\
-.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
-.    ds #V .6m
-.    ds #F 0
-.    ds #[ \&
-.    ds #] \&
-.\}
-.    \" simple accents for nroff and troff
-.if n \{\
-.    ds ' \&
-.    ds ` \&
-.    ds ^ \&
-.    ds , \&
-.    ds ~ ~
-.    ds /
-.\}
-.if t \{\
-.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
-.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
-.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
-.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
-.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
-.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
-.\}
-.    \" troff and (daisy-wheel) nroff accents
-.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
-.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
-.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
-.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
-.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
-.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
-.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
-.ds ae a\h'-(\w'a'u*4/10)'e
-.ds Ae A\h'-(\w'A'u*4/10)'E
-.    \" corrections for vroff
-.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
-.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
-.    \" for low resolution devices (crt and lpr)
-.if \n(.H>23 .if \n(.V>19 \
-\{\
-.    ds : e
-.    ds 8 ss
-.    ds o a
-.    ds d- d\h'-1'\(ga
-.    ds D- D\h'-1'\(hy
-.    ds th \o'bp'
-.    ds Th \o'LP'
-.    ds ae ae
-.    ds Ae AE
-.\}
-.rm #[ #] #H #V #F C
-.\" ========================================================================
-.\"
-.IX Title "JSON::backportPP 3pm"
-.TH JSON::backportPP 3pm "2013-05-23" "perl v5.14.2" "User Contributed Perl Documentation"
-.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
-.\" way too many mistakes in technical documents.
-.if n .ad l
-.nh
-.SH "NAME"
-JSON::PP \- JSON::XS compatible pure\-Perl module.
-.SH "SYNOPSIS"
-.IX Header "SYNOPSIS"
-.Vb 1
-\& use JSON::PP;
-\&
-\& # exported functions, they croak on error
-\& # and 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
-\&
-\& $coder = JSON::PP\->new\->ascii\->pretty\->allow_nonref;
-\& 
-\& $json_text   = $json\->encode( $perl_scalar );
-\& $perl_scalar = $json\->decode( $json_text );
-\& 
-\& $pretty_printed = $json\->pretty\->encode( $perl_scalar ); # pretty\-printing
-\& 
-\& # Note that JSON version 2.0 and above will automatically use
-\& # JSON::XS or JSON::PP, so you should be able to just:
-\& 
-\& use JSON;
-.Ve
-.SH "VERSION"
-.IX Header "VERSION"
-.Vb 1
-\&    2.27200
-.Ve
-.PP
-\&\s-1JSON::XS\s0 2.27 (~2.30) compatible.
-.SH "DESCRIPTION"
-.IX Header "DESCRIPTION"
-This module is \s-1JSON::XS\s0 compatible pure Perl module.
-(Perl 5.8 or later is recommended)
-.PP
-\&\s-1JSON::XS\s0 is the fastest and most proper \s-1JSON\s0 module on \s-1CPAN\s0.
-It is written by Marc Lehmann in C, so must be compiled and
-installed in the used environment.
-.PP
-\&\s-1JSON::PP\s0 is a pure-Perl module and has compatibility to \s-1JSON::XS\s0.
-.SS "\s-1FEATURES\s0"
-.IX Subsection "FEATURES"
-.IP "\(bu" 4
-correct unicode handling
-.Sp
-This module knows how to handle Unicode (depending on Perl version).
-.Sp
-See to \*(L"A \s-1FEW\s0 \s-1NOTES\s0 \s-1ON\s0 \s-1UNICODE\s0 \s-1AND\s0 \s-1PERL\s0\*(R" in \s-1JSON::XS\s0 and
-\&\*(L"\s-1UNICODE\s0 \s-1HANDLING\s0 \s-1ON\s0 \s-1PERLS\s0\*(R".
-.IP "\(bu" 4
-round-trip integrity
-.Sp
-When you serialise a perl data structure using only data types
-supported by \s-1JSON\s0 and Perl, the deserialised data structure is
-identical on the Perl level. (e.g. the string \*(L"2.0\*(R" doesn't suddenly
-become \*(L"2\*(R" just because it looks like a number). There \fIare\fR minor
-exceptions to this, read the \s-1MAPPING\s0 section below to learn about
-those.
-.IP "\(bu" 4
-strict checking of \s-1JSON\s0 correctness
-.Sp
-There is no guessing, no generating of illegal \s-1JSON\s0 texts by default,
-and only \s-1JSON\s0 is accepted as input by default (the latter is a
-security feature). But when some options are set, loose checking
-features are available.
-.SH "FUNCTIONAL INTERFACE"
-.IX Header "FUNCTIONAL INTERFACE"
-Some documents are copied and modified from \*(L"\s-1FUNCTIONAL\s0 \s-1INTERFACE\s0\*(R" in \s-1JSON::XS\s0.
-.SS "encode_json"
-.IX Subsection "encode_json"
-.Vb 1
-\&    $json_text = encode_json $perl_scalar
-.Ve
-.PP
-Converts the given Perl data structure to a \s-1UTF\-8\s0 encoded, binary string.
-.PP
-This function call is functionally identical to:
-.PP
-.Vb 1
-\&    $json_text = JSON::PP\->new\->utf8\->encode($perl_scalar)
-.Ve
-.SS "decode_json"
-.IX Subsection "decode_json"
-.Vb 1
-\&    $perl_scalar = decode_json $json_text
-.Ve
-.PP
-The opposite of \f(CW\*(C`encode_json\*(C'\fR: expects an \s-1UTF\-8\s0 (binary) string and tries
-to parse that as an \s-1UTF\-8\s0 encoded \s-1JSON\s0 text, returning the resulting
-reference.
-.PP
-This function call is functionally identical to:
-.PP
-.Vb 1
-\&    $perl_scalar = JSON::PP\->new\->utf8\->decode($json_text)
-.Ve
-.SS "JSON::PP::is_bool"
-.IX Subsection "JSON::PP::is_bool"
-.Vb 1
-\&    $is_boolean = JSON::PP::is_bool($scalar)
-.Ve
-.PP
-Returns true if the passed scalar represents either JSON::PP::true or
-JSON::PP::false, two constants that act like \f(CW1\fR and \f(CW0\fR respectively
-and are also used to represent \s-1JSON\s0 \f(CW\*(C`true\*(C'\fR and \f(CW\*(C`false\*(C'\fR in Perl strings.
-.SS "JSON::PP::true"
-.IX Subsection "JSON::PP::true"
-Returns \s-1JSON\s0 true value which is blessed object.
-It \f(CW\*(C`isa\*(C'\fR JSON::PP::Boolean object.
-.SS "JSON::PP::false"
-.IX Subsection "JSON::PP::false"
-Returns \s-1JSON\s0 false value which is blessed object.
-It \f(CW\*(C`isa\*(C'\fR JSON::PP::Boolean object.
-.SS "JSON::PP::null"
-.IX Subsection "JSON::PP::null"
-Returns \f(CW\*(C`undef\*(C'\fR.
-.PP
-See \s-1MAPPING\s0, below, for more information on how \s-1JSON\s0 values are mapped to
-Perl.
-.SH "HOW DO I DECODE A DATA FROM OUTER AND ENCODE TO OUTER"
-.IX Header "HOW DO I DECODE A DATA FROM OUTER AND ENCODE TO OUTER"
-This section supposes that your perl version is 5.8 or later.
-.PP
-If you know a \s-1JSON\s0 text from an outer world \- a network, a file content, and so on,
-is encoded in \s-1UTF\-8\s0, you should use \f(CW\*(C`decode_json\*(C'\fR or \f(CW\*(C`JSON\*(C'\fR module object
-with \f(CW\*(C`utf8\*(C'\fR enable. And the decoded result will contain \s-1UNICODE\s0 characters.
-.PP
-.Vb 4
-\&  # from network
-\&  my $json        = JSON::PP\->new\->utf8;
-\&  my $json_text   = CGI\->new\->param( \*(Aqjson_data\*(Aq );
-\&  my $perl_scalar = $json\->decode( $json_text );
-\&  
-\&  # from file content
-\&  local $/;
-\&  open( my $fh, \*(Aq<\*(Aq, \*(Aqjson.data\*(Aq );
-\&  $json_text   = <$fh>;
-\&  $perl_scalar = decode_json( $json_text );
-.Ve
-.PP
-If an outer data is not encoded in \s-1UTF\-8\s0, firstly you should \f(CW\*(C`decode\*(C'\fR it.
-.PP
-.Vb 5
-\&  use Encode;
-\&  local $/;
-\&  open( my $fh, \*(Aq<\*(Aq, \*(Aqjson.data\*(Aq );
-\&  my $encoding = \*(Aqcp932\*(Aq;
-\&  my $unicode_json_text = decode( $encoding, <$fh> ); # UNICODE
-\&  
-\&  # or you can write the below code.
-\&  #
-\&  # open( my $fh, "<:encoding($encoding)", \*(Aqjson.data\*(Aq );
-\&  # $unicode_json_text = <$fh>;
-.Ve
-.PP
-In this case, \f(CW$unicode_json_text\fR is of course \s-1UNICODE\s0 string.
-So you \fBcannot\fR use \f(CW\*(C`decode_json\*(C'\fR nor \f(CW\*(C`JSON\*(C'\fR module object with \f(CW\*(C`utf8\*(C'\fR enable.
-Instead of them, you use \f(CW\*(C`JSON\*(C'\fR module object with \f(CW\*(C`utf8\*(C'\fR disable.
-.PP
-.Vb 1
-\&  $perl_scalar = $json\->utf8(0)\->decode( $unicode_json_text );
-.Ve
-.PP
-Or \f(CW\*(C`encode \*(Aqutf8\*(Aq\*(C'\fR and \f(CW\*(C`decode_json\*(C'\fR:
-.PP
-.Vb 2
-\&  $perl_scalar = decode_json( encode( \*(Aqutf8\*(Aq, $unicode_json_text ) );
-\&  # this way is not efficient.
-.Ve
-.PP
-And now, you want to convert your \f(CW$perl_scalar\fR into \s-1JSON\s0 data and
-send it to an outer world \- a network or a file content, and so on.
-.PP
-Your data usually contains \s-1UNICODE\s0 strings and you want the converted data to be encoded
-in \s-1UTF\-8\s0, you should use \f(CW\*(C`encode_json\*(C'\fR or \f(CW\*(C`JSON\*(C'\fR module object with \f(CW\*(C`utf8\*(C'\fR enable.
-.PP
-.Vb 3
-\&  print encode_json( $perl_scalar ); # to a network? file? or display?
-\&  # or
-\&  print $json\->utf8\->encode( $perl_scalar );
-.Ve
-.PP
-If \f(CW$perl_scalar\fR does not contain \s-1UNICODE\s0 but \f(CW$encoding\fR\-encoded strings
-for some reason, then its characters are regarded as \fBlatin1\fR for perl
-(because it does not concern with your \f(CW$encoding\fR).
-You \fBcannot\fR use \f(CW\*(C`encode_json\*(C'\fR nor \f(CW\*(C`JSON\*(C'\fR module object with \f(CW\*(C`utf8\*(C'\fR enable.
-Instead of them, you use \f(CW\*(C`JSON\*(C'\fR module object with \f(CW\*(C`utf8\*(C'\fR disable.
-Note that the resulted text is a \s-1UNICODE\s0 string but no problem to print it.
-.PP
-.Vb 4
-\&  # $perl_scalar contains $encoding encoded string values
-\&  $unicode_json_text = $json\->utf8(0)\->encode( $perl_scalar );
-\&  # $unicode_json_text consists of characters less than 0x100
-\&  print $unicode_json_text;
-.Ve
-.PP
-Or \f(CW\*(C`decode $encoding\*(C'\fR all string values and \f(CW\*(C`encode_json\*(C'\fR:
-.PP
-.Vb 3
-\&  $perl_scalar\->{ foo } = decode( $encoding, $perl_scalar\->{ foo } );
-\&  # ... do it to each string values, then encode_json
-\&  $json_text = encode_json( $perl_scalar );
-.Ve
-.PP
-This method is a proper way but probably not efficient.
-.PP
-See to Encode, perluniintro.
-.SH "METHODS"
-.IX Header "METHODS"
-Basically, check to \s-1JSON\s0 or \s-1JSON::XS\s0.
-.SS "new"
-.IX Subsection "new"
-.Vb 1
-\&    $json = JSON::PP\->new
-.Ve
-.PP
-Returns a new \s-1JSON::PP\s0 object that can be used to de/encode \s-1JSON\s0
-strings.
-.PP
-All boolean flags described below are by default \fIdisabled\fR.
-.PP
-The mutators for flags all return the \s-1JSON\s0 object again and thus calls can
-be chained:
-.PP
-.Vb 2
-\&   my $json = JSON::PP\->new\->utf8\->space_after\->encode({a => [1,2]})
-\&   => {"a": [1, 2]}
-.Ve
-.SS "ascii"
-.IX Subsection "ascii"
-.Vb 1
-\&    $json = $json\->ascii([$enable])
-\&    
-\&    $enabled = $json\->get_ascii
-.Ve
-.PP
-If \f(CW$enable\fR 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 \euXXXX or a double \euHHHH\euLLLLL escape sequence, as per \s-1RFC4627\s0.
-(See to \*(L"OBJECT-ORIENTED \s-1INTERFACE\s0\*(R" in \s-1JSON::XS\s0).
-.PP
-In Perl 5.005, there is no character having high value (more than 255).
-See to \*(L"\s-1UNICODE\s0 \s-1HANDLING\s0 \s-1ON\s0 \s-1PERLS\s0\*(R".
-.PP
-If \f(CW$enable\fR is false, then the encode method will not escape Unicode characters unless
-required by the \s-1JSON\s0 syntax or other flags. This results in a faster and more compact format.
-.PP
-.Vb 2
-\&  JSON::PP\->new\->ascii(1)\->encode([chr 0x10401])
-\&  => ["\eud801\eudc01"]
-.Ve
-.SS "latin1"
-.IX Subsection "latin1"
-.Vb 1
-\&    $json = $json\->latin1([$enable])
-\&    
-\&    $enabled = $json\->get_latin1
-.Ve
-.PP
-If \f(CW$enable\fR is true (or missing), then the encode method will encode the resulting \s-1JSON\s0
-text as latin1 (or iso\-8859\-1), escaping any characters outside the code range 0..255.
-.PP
-If \f(CW$enable\fR is false, then the encode method will not escape Unicode characters
-unless required by the \s-1JSON\s0 syntax or other flags.
-.PP
-.Vb 2
-\&  JSON::XS\->new\->latin1\->encode (["\ex{89}\ex{abc}"]
-\&  => ["\ex{89}\e\eu0abc"]    # (perl syntax, U+abc escaped, U+89 not)
-.Ve
-.PP
-See to \*(L"\s-1UNICODE\s0 \s-1HANDLING\s0 \s-1ON\s0 \s-1PERLS\s0\*(R".
-.SS "utf8"
-.IX Subsection "utf8"
-.Vb 1
-\&    $json = $json\->utf8([$enable])
-\&    
-\&    $enabled = $json\->get_utf8
-.Ve
-.PP
-If \f(CW$enable\fR is true (or missing), then the encode method will encode the \s-1JSON\s0 result
-into \s-1UTF\-8\s0, 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.
-.PP
-(In Perl 5.005, any character outside the range 0..255 does not exist.
-See to \*(L"\s-1UNICODE\s0 \s-1HANDLING\s0 \s-1ON\s0 \s-1PERLS\s0\*(R".)
-.PP
-In future versions, enabling this option might enable autodetection of the \s-1UTF\-16\s0 and \s-1UTF\-32\s0
-encoding families, as described in \s-1RFC4627\s0.
-.PP
-If \f(CW$enable\fR is false, then the encode method will return the \s-1JSON\s0 string as a (non-encoded)
-Unicode string, while decode expects thus a Unicode string. Any decoding or encoding
-(e.g. to \s-1UTF\-8\s0 or \s-1UTF\-16\s0) needs to be done yourself, e.g. using the Encode module.
-.PP
-Example, output UTF\-16BE\-encoded \s-1JSON:\s0
-.PP
-.Vb 2
-\&  use Encode;
-\&  $jsontext = encode "UTF\-16BE", JSON::PP\->new\->encode ($object);
-.Ve
-.PP
-Example, decode UTF\-32LE\-encoded \s-1JSON:\s0
-.PP
-.Vb 2
-\&  use Encode;
-\&  $object = JSON::PP\->new\->decode (decode "UTF\-32LE", $jsontext);
-.Ve
-.SS "pretty"
-.IX Subsection "pretty"
-.Vb 1
-\&    $json = $json\->pretty([$enable])
-.Ve
-.PP
-This enables (or disables) all of the \f(CW\*(C`indent\*(C'\fR, \f(CW\*(C`space_before\*(C'\fR and
-\&\f(CW\*(C`space_after\*(C'\fR flags in one call to generate the most readable
-(or most compact) form possible.
-.PP
-Equivalent to:
-.PP
-.Vb 1
-\&   $json\->indent\->space_before\->space_after
-.Ve
-.SS "indent"
-.IX Subsection "indent"
-.Vb 1
-\&    $json = $json\->indent([$enable])
-\&    
-\&    $enabled = $json\->get_indent
-.Ve
-.PP
-The default indent space length is three.
-You can use \f(CW\*(C`indent_length\*(C'\fR to change the length.
-.SS "space_before"
-.IX Subsection "space_before"
-.Vb 1
-\&    $json = $json\->space_before([$enable])
-\&    
-\&    $enabled = $json\->get_space_before
-.Ve
-.PP
-If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will add an extra
-optional space before the \f(CW\*(C`:\*(C'\fR separating keys from values in \s-1JSON\s0 objects.
-.PP
-If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will not add any extra
-space at those places.
-.PP
-This setting has no effect when decoding \s-1JSON\s0 texts.
-.PP
-Example, space_before enabled, space_after and indent disabled:
-.PP
-.Vb 1
-\&   {"key" :"value"}
-.Ve
-.SS "space_after"
-.IX Subsection "space_after"
-.Vb 1
-\&    $json = $json\->space_after([$enable])
-\&    
-\&    $enabled = $json\->get_space_after
-.Ve
-.PP
-If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will add an extra
-optional space after the \f(CW\*(C`:\*(C'\fR separating keys from values in \s-1JSON\s0 objects
-and extra whitespace after the \f(CW\*(C`,\*(C'\fR separating key-value pairs and array
-members.
-.PP
-If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will not add any extra
-space at those places.
-.PP
-This setting has no effect when decoding \s-1JSON\s0 texts.
-.PP
-Example, space_before and indent disabled, space_after enabled:
-.PP
-.Vb 1
-\&   {"key": "value"}
-.Ve
-.SS "relaxed"
-.IX Subsection "relaxed"
-.Vb 1
-\&    $json = $json\->relaxed([$enable])
-\&    
-\&    $enabled = $json\->get_relaxed
-.Ve
-.PP
-If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`decode\*(C'\fR will accept some
-extensions to normal \s-1JSON\s0 syntax (see below). \f(CW\*(C`encode\*(C'\fR will not be
-affected in anyway. \fIBe aware that this option makes you accept invalid
-\&\s-1JSON\s0 texts as if they were valid!\fR. I suggest only to use this option to
-parse application-specific files written by humans (configuration files,
-resource files etc.)
-.PP
-If \f(CW$enable\fR is false (the default), then \f(CW\*(C`decode\*(C'\fR will only accept
-valid \s-1JSON\s0 texts.
-.PP
-Currently accepted extensions are:
-.IP "\(bu" 4
-list items can have an end-comma
-.Sp
-\&\s-1JSON\s0 \fIseparates\fR array elements and key-value pairs with commas. This
-can be annoying if you write \s-1JSON\s0 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:
-.Sp
-.Vb 8
-\&   [
-\&      1,
-\&      2, <\- this comma not normally allowed
-\&   ]
-\&   {
-\&      "k1": "v1",
-\&      "k2": "v2", <\- this comma not normally allowed
-\&   }
-.Ve
-.IP "\(bu" 4
-shell-style '#'\-comments
-.Sp
-Whenever \s-1JSON\s0 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.
-.Sp
-.Vb 4
-\&  [
-\&     1, # this comment not allowed in JSON
-\&        # neither this one...
-\&  ]
-.Ve
-.SS "canonical"
-.IX Subsection "canonical"
-.Vb 1
-\&    $json = $json\->canonical([$enable])
-\&    
-\&    $enabled = $json\->get_canonical
-.Ve
-.PP
-If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will output \s-1JSON\s0 objects
-by sorting their keys. This is adding a comparatively high overhead.
-.PP
-If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will output key-value
-pairs in the order Perl stores them (which will likely change between runs
-of the same script).
-.PP
-This option is useful if you want the same data structure to be encoded as
-the same \s-1JSON\s0 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.
-.PP
-This setting has no effect when decoding \s-1JSON\s0 texts.
-.PP
-If you want your own sorting routine, you can give a code reference
-or a subroutine name to \f(CW\*(C`sort_by\*(C'\fR. See to \f(CW\*(C`JSON::PP OWN METHODS\*(C'\fR.
-.SS "allow_nonref"
-.IX Subsection "allow_nonref"
-.Vb 1
-\&    $json = $json\->allow_nonref([$enable])
-\&    
-\&    $enabled = $json\->get_allow_nonref
-.Ve
-.PP
-If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method can convert a
-non-reference into its corresponding string, number or null \s-1JSON\s0 value,
-which is an extension to \s-1RFC4627\s0. Likewise, \f(CW\*(C`decode\*(C'\fR will accept those \s-1JSON\s0
-values instead of croaking.
-.PP
-If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will croak if it isn't
-passed an arrayref or hashref, as \s-1JSON\s0 texts must either be an object
-or array. Likewise, \f(CW\*(C`decode\*(C'\fR will croak if given something that is not a
-\&\s-1JSON\s0 object or array.
-.PP
-.Vb 2
-\&   JSON::PP\->new\->allow_nonref\->encode ("Hello, World!")
-\&   => "Hello, World!"
-.Ve
-.SS "allow_unknown"
-.IX Subsection "allow_unknown"
-.Vb 1
-\&    $json = $json\->allow_unknown ([$enable])
-\&    
-\&    $enabled = $json\->get_allow_unknown
-.Ve
-.PP
-If \f(CW$enable\fR is true (or missing), then \*(L"encode\*(R" will *not* throw an
-exception when it encounters values it cannot represent in \s-1JSON\s0 (for
-example, filehandles) but instead will encode a \s-1JSON\s0 \*(L"null\*(R" value.
-Note that blessed objects are not included here and are handled
-separately by c<allow_nonref>.
-.PP
-If \f(CW$enable\fR is false (the default), then \*(L"encode\*(R" will throw an
-exception when it encounters anything it cannot encode as \s-1JSON\s0.
-.PP
-This option does not affect \*(L"decode\*(R" in any way, and it is
-recommended to leave it off unless you know your communications
-partner.
-.SS "allow_blessed"
-.IX Subsection "allow_blessed"
-.Vb 1
-\&    $json = $json\->allow_blessed([$enable])
-\&    
-\&    $enabled = $json\->get_allow_blessed
-.Ve
-.PP
-If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will not
-barf when it encounters a blessed reference. Instead, the value of the
-\&\fBconvert_blessed\fR option will decide whether \f(CW\*(C`null\*(C'\fR (\f(CW\*(C`convert_blessed\*(C'\fR
-disabled or no \f(CW\*(C`TO_JSON\*(C'\fR method found) or a representation of the
-object (\f(CW\*(C`convert_blessed\*(C'\fR enabled and \f(CW\*(C`TO_JSON\*(C'\fR method found) is being
-encoded. Has no effect on \f(CW\*(C`decode\*(C'\fR.
-.PP
-If \f(CW$enable\fR is false (the default), then \f(CW\*(C`encode\*(C'\fR will throw an
-exception when it encounters a blessed object.
-.SS "convert_blessed"
-.IX Subsection "convert_blessed"
-.Vb 1
-\&    $json = $json\->convert_blessed([$enable])
-\&    
-\&    $enabled = $json\->get_convert_blessed
-.Ve
-.PP
-If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`encode\*(C'\fR, upon encountering a
-blessed object, will check for the availability of the \f(CW\*(C`TO_JSON\*(C'\fR 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
-\&\f(CW\*(C`TO_JSON\*(C'\fR method is found, the value of \f(CW\*(C`allow_blessed\*(C'\fR will decide what
-to do.
-.PP
-The \f(CW\*(C`TO_JSON\*(C'\fR method may safely call die if it wants. If \f(CW\*(C`TO_JSON\*(C'\fR
-returns other blessed objects, those will be handled in the same
-way. \f(CW\*(C`TO_JSON\*(C'\fR must take care of not causing an endless recursion cycle
-(== crash) in this case. The name of \f(CW\*(C`TO_JSON\*(C'\fR 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 \f(CW\*(C`to_json\*(C'\fR
-function or method.
-.PP
-This setting does not yet influence \f(CW\*(C`decode\*(C'\fR in any way.
-.PP
-If \f(CW$enable\fR is false, then the \f(CW\*(C`allow_blessed\*(C'\fR setting will decide what
-to do when a blessed object is found.
-.SS "filter_json_object"
-.IX Subsection "filter_json_object"
-.Vb 1
-\&    $json = $json\->filter_json_object([$coderef])
-.Ve
-.PP
-When \f(CW$coderef\fR is specified, it will be called from \f(CW\*(C`decode\*(C'\fR each
-time it decodes a \s-1JSON\s0 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
-(\s-1NOTE:\s0 \fInot\fR \f(CW\*(C`undef\*(C'\fR, which is a valid scalar), the original deserialised
-hash will be inserted. This setting can slow down decoding considerably.
-.PP
-When \f(CW$coderef\fR is omitted or undefined, any existing callback will
-be removed and \f(CW\*(C`decode\*(C'\fR will not change the deserialised hash in any
-way.
-.PP
-Example, convert all \s-1JSON\s0 objects into the integer 5:
-.PP
-.Vb 6
-\&   my $js = JSON::PP\->new\->filter_json_object (sub { 5 });
-\&   # returns [5]
-\&   $js\->decode (\*(Aq[{}]\*(Aq); # 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 (\*(Aq{"a":1, "b":2}\*(Aq);
-.Ve
-.SS "filter_json_single_key_object"
-.IX Subsection "filter_json_single_key_object"
-.Vb 1
-\&    $json = $json\->filter_json_single_key_object($key [=> $coderef])
-.Ve
-.PP
-Works remotely similar to \f(CW\*(C`filter_json_object\*(C'\fR, but is only called for
-\&\s-1JSON\s0 objects having a single key named \f(CW$key\fR.
-.PP
-This \f(CW$coderef\fR is called before the one specified via
-\&\f(CW\*(C`filter_json_object\*(C'\fR, if any. It gets passed the single value in the \s-1JSON\s0
-object. If it returns a single value, it will be inserted into the data
-structure. If it returns nothing (not even \f(CW\*(C`undef\*(C'\fR but the empty list),
-the callback from \f(CW\*(C`filter_json_object\*(C'\fR will be called next, as if no
-single-key callback were specified.
-.PP
-If \f(CW$coderef\fR is omitted or undefined, the corresponding callback will be
-disabled. There can only ever be one callback for a given key.
-.PP
-As this callback gets called less often then the \f(CW\*(C`filter_json_object\*(C'\fR
-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 \s-1JSON\s0 objects are as close to the type-tagged value concept
-as \s-1JSON\s0 gets (it's basically an \s-1ID/VALUE\s0 tuple). Of course, \s-1JSON\s0 does not
-support this in any way, so you need to make sure your data never looks
-like a serialised Perl hash.
-.PP
-Typical names for the single object key are \f(CW\*(C`_\|_class_whatever_\|_\*(C'\fR, or
-\&\f(CW\*(C`$_\|_dollars_are_rarely_used_\|_$\*(C'\fR or \f(CW\*(C`}ugly_brace_placement\*(C'\fR, or even
-things like \f(CW\*(C`_\|_class_md5sum(classname)_\|_\*(C'\fR, to reduce the risk of clashing
-with real hashes.
-.PP
-Example, decode \s-1JSON\s0 objects of the form \f(CW\*(C`{ "_\|_widget_\|_" => <id> }\*(C'\fR
-into the corresponding \f(CW$WIDGET{<id>}\fR object:
-.PP
-.Vb 7
-\&   # return whatever is in $WIDGET{5}:
-\&   JSON::PP
-\&      \->new
-\&      \->filter_json_single_key_object (_\|_widget_\|_ => sub {
-\&            $WIDGET{ $_[0] }
-\&         })
-\&      \->decode (\*(Aq{"_\|_widget_\|_": 5\*(Aq)
-\&
-\&   # 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} }
-\&   }
-.Ve
-.SS "shrink"
-.IX Subsection "shrink"
-.Vb 1
-\&    $json = $json\->shrink([$enable])
-\&    
-\&    $enabled = $json\->get_shrink
-.Ve
-.PP
-In \s-1JSON::XS\s0, this flag resizes strings generated by either
-\&\f(CW\*(C`encode\*(C'\fR or \f(CW\*(C`decode\*(C'\fR to their minimum size possible.
-It will also try to downgrade any strings to octet-form if possible.
-.PP
-In \s-1JSON::PP\s0, it is noop about resizing strings but tries
-\&\f(CW\*(C`utf8::downgrade\*(C'\fR to the returned string by \f(CW\*(C`encode\*(C'\fR.
-See to utf8.
-.PP
-See to \*(L"OBJECT-ORIENTED \s-1INTERFACE\s0\*(R" in \s-1JSON::XS\s0
-.SS "max_depth"
-.IX Subsection "max_depth"
-.Vb 1
-\&    $json = $json\->max_depth([$maximum_nesting_depth])
-\&    
-\&    $max_depth = $json\->get_max_depth
-.Ve
-.PP
-Sets the maximum nesting level (default \f(CW512\fR) accepted while encoding
-or decoding. If a higher nesting level is detected in \s-1JSON\s0 text or a Perl
-data structure, then the encoder and decoder will stop and croak at that
-point.
-.PP
-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 \f(CW\*(C`{\*(C'\fR or \f(CW\*(C`[\*(C'\fR
-characters without their matching closing parenthesis crossed to reach a
-given character in a string.
-.PP
-If no argument is given, the highest possible setting will be used, which
-is rarely useful.
-.PP
-See \*(L"\s-1SSECURITY\s0 \s-1CONSIDERATIONS\s0\*(R" in \s-1JSON::XS\s0 for more info on why this is useful.
-.PP
-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.
-.SS "max_size"
-.IX Subsection "max_size"
-.Vb 1
-\&    $json = $json\->max_size([$maximum_string_size])
-\&    
-\&    $max_size = $json\->get_max_size
-.Ve
-.PP
-Set the maximum length a \s-1JSON\s0 text may have (in bytes) where decoding is
-being attempted. The default is \f(CW0\fR, meaning no limit. When \f(CW\*(C`decode\*(C'\fR
-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 \f(CW\*(C`encode\*(C'\fR (yet).
-.PP
-If no argument is given, the limit check will be deactivated (same as when
-\&\f(CW0\fR is specified).
-.PP
-See \*(L"\s-1SECURITY\s0 \s-1CONSIDERATIONS\s0\*(R" in \s-1JSON::XS\s0 for more info on why this is useful.
-.SS "encode"
-.IX Subsection "encode"
-.Vb 1
-\&    $json_text = $json\->encode($perl_scalar)
-.Ve
-.PP
-Converts the given Perl data structure (a simple scalar or a reference
-to a hash or array) to its \s-1JSON\s0 representation. Simple scalars will be
-converted into \s-1JSON\s0 string or number sequences, while references to arrays
-become \s-1JSON\s0 arrays and references to hashes become \s-1JSON\s0 objects. Undefined
-Perl values (e.g. \f(CW\*(C`undef\*(C'\fR) become \s-1JSON\s0 \f(CW\*(C`null\*(C'\fR values.
-References to the integers \f(CW0\fR and \f(CW1\fR are converted into \f(CW\*(C`true\*(C'\fR and \f(CW\*(C`false\*(C'\fR.
-.SS "decode"
-.IX Subsection "decode"
-.Vb 1
-\&    $perl_scalar = $json\->decode($json_text)
-.Ve
-.PP
-The opposite of \f(CW\*(C`encode\*(C'\fR: expects a \s-1JSON\s0 text and tries to parse it,
-returning the resulting simple scalar or reference. Croaks on error.
-.PP
-\&\s-1JSON\s0 numbers and strings become simple Perl scalars. \s-1JSON\s0 arrays become
-Perl arrayrefs and \s-1JSON\s0 objects become Perl hashrefs. \f(CW\*(C`true\*(C'\fR becomes
-\&\f(CW1\fR (\f(CW\*(C`JSON::true\*(C'\fR), \f(CW\*(C`false\*(C'\fR becomes \f(CW0\fR (\f(CW\*(C`JSON::false\*(C'\fR) and
-\&\f(CW\*(C`null\*(C'\fR becomes \f(CW\*(C`undef\*(C'\fR.
-.SS "decode_prefix"
-.IX Subsection "decode_prefix"
-.Vb 1
-\&    ($perl_scalar, $characters) = $json\->decode_prefix($json_text)
-.Ve
-.PP
-This works like the \f(CW\*(C`decode\*(C'\fR method, but instead of raising an exception
-when there is trailing garbage after the first \s-1JSON\s0 object, it will
-silently stop parsing there and return the number of characters consumed
-so far.
-.PP
-.Vb 2
-\&   JSON\->new\->decode_prefix ("[1] the tail")
-\&   => ([], 3)
-.Ve
-.SH "INCREMENTAL PARSING"
-.IX Header "INCREMENTAL PARSING"
-Most of this section are copied and modified from \*(L"\s-1INCREMENTAL\s0 \s-1PARSING\s0\*(R" in \s-1JSON::XS\s0.
-.PP
-In some cases, there is the need for incremental parsing of \s-1JSON\s0 texts.
-This module does allow you to parse a \s-1JSON\s0 stream incrementally.
-It does so by accumulating text until it has a full \s-1JSON\s0 object, which
-it then can decode. This process is similar to using \f(CW\*(C`decode_prefix\*(C'\fR
-to see if a full \s-1JSON\s0 object is available, but is much more efficient
-(and can be implemented with a minimum of method calls).
-.PP
-This module will only attempt to parse the \s-1JSON\s0 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 \s-1JSON\s0 text has been seen. This means you need
-to set resource limits (e.g. \f(CW\*(C`max_size\*(C'\fR) to ensure the parser will stop
-parsing in the presence if syntax errors.
-.PP
-The following methods implement this incremental parser.
-.SS "incr_parse"
-.IX Subsection "incr_parse"
-.Vb 1
-\&    $json\->incr_parse( [$string] ) # void context
-\&    
-\&    $obj_or_undef = $json\->incr_parse( [$string] ) # scalar context
-\&    
-\&    @obj_or_empty = $json\->incr_parse( [$string] ) # list context
-.Ve
-.PP
-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).
-.PP
-If \f(CW$string\fR is given, then this string is appended to the already
-existing \s-1JSON\s0 fragment stored in the \f(CW$json\fR object.
-.PP
-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.
-.PP
-If the method is called in scalar context, then it will try to extract
-exactly \fIone\fR \s-1JSON\s0 object. If that is successful, it will return this
-object, otherwise it will return \f(CW\*(C`undef\*(C'\fR. If there is a parse error,
-this method will croak just as \f(CW\*(C`decode\*(C'\fR would do (one can then use
-\&\f(CW\*(C`incr_skip\*(C'\fR to skip the erroneous part). This is the most common way of
-using the method.
-.PP
-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 \s-1JSON\s0
-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 \s-1JSON\s0 texts will be
-lost.
-.PP
-Example: Parse some \s-1JSON\s0 arrays/objects in a given string and return them.
-.PP
-.Vb 1
-\&    my @objs = JSON\->new\->incr_parse ("[5][7][1,2]");
-.Ve
-.SS "incr_text"
-.IX Subsection "incr_text"
-.Vb 1
-\&    $lvalue_string = $json\->incr_text
-.Ve
-.PP
-This method returns the currently stored \s-1JSON\s0 fragment as an lvalue, that
-is, you can manipulate it. This \fIonly\fR works when a preceding call to
-\&\f(CW\*(C`incr_parse\*(C'\fR in \fIscalar context\fR 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 \fIwill\fR fail under
-real world conditions). As a special exception, you can also call this
-method before having parsed anything.
-.PP
-This function is useful in two cases: a) finding the trailing text after a
-\&\s-1JSON\s0 object or b) parsing multiple \s-1JSON\s0 objects separated by non-JSON text
-(such as commas).
-.PP
-.Vb 1
-\&    $json\->incr_text =~ s/\es*,\es*//;
-.Ve
-.PP
-In Perl 5.005, \f(CW\*(C`lvalue\*(C'\fR attribute is not available.
-You must write codes like the below:
-.PP
-.Vb 3
-\&    $string = $json\->incr_text;
-\&    $string =~ s/\es*,\es*//;
-\&    $json\->incr_text( $string );
-.Ve
-.SS "incr_skip"
-.IX Subsection "incr_skip"
-.Vb 1
-\&    $json\->incr_skip
-.Ve
-.PP
-This will reset the state of the incremental parser and will remove the
-parsed text from the input buffer. This is useful after \f(CW\*(C`incr_parse\*(C'\fR
-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.
-.SS "incr_reset"
-.IX Subsection "incr_reset"
-.Vb 1
-\&    $json\->incr_reset
-.Ve
-.PP
-This completely resets the incremental parser, that is, after this call,
-it will be as if the parser had never parsed anything.
-.PP
-This is useful if you want to repeatedly parse \s-1JSON\s0 objects and want to
-ignore any trailing data, which means you have to reset the parser after
-each successful decode.
-.PP
-See to \*(L"\s-1INCREMENTAL\s0 \s-1PARSING\s0\*(R" in \s-1JSON::XS\s0 for examples.
-.SH "JSON::PP OWN METHODS"
-.IX Header "JSON::PP OWN METHODS"
-.SS "allow_singlequote"
-.IX Subsection "allow_singlequote"
-.Vb 1
-\&    $json = $json\->allow_singlequote([$enable])
-.Ve
-.PP
-If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`decode\*(C'\fR will accept
-\&\s-1JSON\s0 strings quoted by single quotations that are invalid \s-1JSON\s0
-format.
-.PP
-.Vb 3
-\&    $json\->allow_singlequote\->decode({"foo":\*(Aqbar\*(Aq});
-\&    $json\->allow_singlequote\->decode({\*(Aqfoo\*(Aq:"bar"});
-\&    $json\->allow_singlequote\->decode({\*(Aqfoo\*(Aq:\*(Aqbar\*(Aq});
-.Ve
-.PP
-As same as the \f(CW\*(C`relaxed\*(C'\fR option, this option may be used to parse
-application-specific files written by humans.
-.SS "allow_barekey"
-.IX Subsection "allow_barekey"
-.Vb 1
-\&    $json = $json\->allow_barekey([$enable])
-.Ve
-.PP
-If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`decode\*(C'\fR will accept
-bare keys of \s-1JSON\s0 object that are invalid \s-1JSON\s0 format.
-.PP
-As same as the \f(CW\*(C`relaxed\*(C'\fR option, this option may be used to parse
-application-specific files written by humans.
-.PP
-.Vb 1
-\&    $json\->allow_barekey\->decode(\*(Aq{foo:"bar"}\*(Aq);
-.Ve
-.SS "allow_bignum"
-.IX Subsection "allow_bignum"
-.Vb 1
-\&    $json = $json\->allow_bignum([$enable])
-.Ve
-.PP
-If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`decode\*(C'\fR 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.
-.PP
-On the contrary, \f(CW\*(C`encode\*(C'\fR converts \f(CW\*(C`Math::BigInt\*(C'\fR objects and \f(CW\*(C`Math::BigFloat\*(C'\fR
-objects into \s-1JSON\s0 numbers with \f(CW\*(C`allow_blessed\*(C'\fR enable.
-.PP
-.Vb 4
-\&   $json\->allow_nonref\->allow_blessed\->allow_bignum;
-\&   $bigfloat = $json\->decode(\*(Aq2.000000000000000000000000001\*(Aq);
-\&   print $json\->encode($bigfloat);
-\&   # => 2.000000000000000000000000001
-.Ve
-.PP
-See to \*(L"\s-1MAPPING\s0\*(R" in \s-1JSON::XS\s0 about the normal conversion of \s-1JSON\s0 number.
-.SS "loose"
-.IX Subsection "loose"
-.Vb 1
-\&    $json = $json\->loose([$enable])
-.Ve
-.PP
-The unescaped [\ex00\-\ex1f\ex22\ex2f\ex5c] strings are invalid in \s-1JSON\s0 strings
-and the module doesn't allow to \f(CW\*(C`decode\*(C'\fR to these (except for \ex2f).
-If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`decode\*(C'\fR  will accept these
-unescaped strings.
-.PP
-.Vb 2
-\&    $json\->loose\->decode(qq|["abc
-\&                                   def"]|);
-.Ve
-.PP
-See \*(L"\s-1SSECURITY\s0 \s-1CONSIDERATIONS\s0\*(R" in \s-1JSON::XS\s0.
-.SS "escape_slash"
-.IX Subsection "escape_slash"
-.Vb 1
-\&    $json = $json\->escape_slash([$enable])
-.Ve
-.PP
-According to \s-1JSON\s0 Grammar, \fIslash\fR (U+002F) is escaped. But default
-\&\s-1JSON::PP\s0 (as same as \s-1JSON::XS\s0) encodes strings without escaping slash.
-.PP
-If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`encode\*(C'\fR will escape slashes.
-.SS "indent_length"
-.IX Subsection "indent_length"
-.Vb 1
-\&    $json = $json\->indent_length($length)
-.Ve
-.PP
-\&\s-1JSON::XS\s0 indent space length is 3 and cannot be changed.
-\&\s-1JSON::PP\s0 set the indent space length with the given \f(CW$length\fR.
-The default is 3. The acceptable range is 0 to 15.
-.SS "sort_by"
-.IX Subsection "sort_by"
-.Vb 2
-\&    $json = $json\->sort_by($function_name)
-\&    $json = $json\->sort_by($subroutine_ref)
-.Ve
-.PP
-If \f(CW$function_name\fR or \f(CW$subroutine_ref\fR are set, its sort routine are used
-in encoding \s-1JSON\s0 objects.
-.PP
-.Vb 2
-\&   $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(\*(Aqown_sort\*(Aq)\->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 }
-.Ve
-.PP
-As the sorting routine runs in the \s-1JSON::PP\s0 scope, the given
-subroutine name and the special variables \f(CW$a\fR, \f(CW$b\fR will begin
-\&'\s-1JSON::PP::\s0'.
-.PP
-If \f(CW$integer\fR is set, then the effect is same as \f(CW\*(C`canonical\*(C'\fR on.
-.SH "INTERNAL"
-.IX Header "INTERNAL"
-For developers.
-.IP "PP_encode_box" 4
-.IX Item "PP_encode_box"
-Returns
-.Sp
-.Vb 4
-\&        {
-\&            depth        => $depth,
-\&            indent_count => $indent_count,
-\&        }
-.Ve
-.IP "PP_decode_box" 4
-.IX Item "PP_decode_box"
-Returns
-.Sp
-.Vb 9
-\&        {
-\&            text    => $text,
-\&            at      => $at,
-\&            ch      => $ch,
-\&            len     => $len,
-\&            depth   => $depth,
-\&            encoding      => $encoding,
-\&            is_valid_utf8 => $is_valid_utf8,
-\&        };
-.Ve
-.SH "MAPPING"
-.IX Header "MAPPING"
-This section is copied from \s-1JSON::XS\s0 and modified to \f(CW\*(C`JSON::PP\*(C'\fR.
-\&\s-1JSON::XS\s0 and \s-1JSON::PP\s0 mapping mechanisms are almost equivalent.
-.PP
-See to \*(L"\s-1MAPPING\s0\*(R" in \s-1JSON::XS\s0.
-.SS "\s-1JSON\s0 \-> \s-1PERL\s0"
-.IX Subsection "JSON -> PERL"
-.IP "object" 4
-.IX Item "object"
-A \s-1JSON\s0 object becomes a reference to a hash in Perl. No ordering of object
-keys is preserved (\s-1JSON\s0 does not preserver object key ordering itself).
-.IP "array" 4
-.IX Item "array"
-A \s-1JSON\s0 array becomes a reference to an array in Perl.
-.IP "string" 4
-.IX Item "string"
-A \s-1JSON\s0 string becomes a string scalar in Perl \- Unicode codepoints in \s-1JSON\s0
-are represented by the same codepoints in the Perl string, so no manual
-decoding is necessary.
-.IP "number" 4
-.IX Item "number"
-A \s-1JSON\s0 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.
-.Sp
-If the number consists of digits only, \f(CW\*(C`JSON\*(C'\fR 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 \s-1JSON\s0 number will be
-re-encoded to a \s-1JSON\s0 string).
-.Sp
-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 \s-1JSON\s0 number will still be re-encoded as a \s-1JSON\s0 number).
-.Sp
-Note that precision is not accuracy \- binary floating point values cannot
-represent most decimal fractions exactly, and when converting from and to
-floating point, \f(CW\*(C`JSON\*(C'\fR only guarantees precision up to but not including
-the least significant bit.
-.Sp
-When \f(CW\*(C`allow_bignum\*(C'\fR is enable, the big integers 
-and the numeric can be optionally converted into Math::BigInt and
-Math::BigFloat objects.
-.IP "true, false" 4
-.IX Item "true, false"
-These \s-1JSON\s0 atoms become \f(CW\*(C`JSON::PP::true\*(C'\fR and \f(CW\*(C`JSON::PP::false\*(C'\fR,
-respectively. They are overloaded to act almost exactly like the numbers
-\&\f(CW1\fR and \f(CW0\fR. You can check whether a scalar is a \s-1JSON\s0 boolean by using
-the \f(CW\*(C`JSON::is_bool\*(C'\fR function.
-.Sp
-.Vb 4
-\&   print JSON::PP::true . "\en";
-\&    => true
-\&   print JSON::PP::true + 1;
-\&    => 1
-\&
-\&   ok(JSON::true eq  \*(Aq1\*(Aq);
-\&   ok(JSON::true == 1);
-.Ve
-.Sp
-\&\f(CW\*(C`JSON\*(C'\fR will install these missing overloading features to the backend modules.
-.IP "null" 4
-.IX Item "null"
-A \s-1JSON\s0 null atom becomes \f(CW\*(C`undef\*(C'\fR in Perl.
-.Sp
-\&\f(CW\*(C`JSON::PP::null\*(C'\fR returns \f(CW\*(C`undef\*(C'\fR.
-.SS "\s-1PERL\s0 \-> \s-1JSON\s0"
-.IX Subsection "PERL -> JSON"
-The mapping from Perl to \s-1JSON\s0 is slightly more difficult, as Perl is a
-truly typeless language, so we can only guess which \s-1JSON\s0 type is meant by
-a Perl value.
-.IP "hash references" 4
-.IX Item "hash references"
-Perl hash references become \s-1JSON\s0 objects. As there is no inherent ordering
-in hash keys (or \s-1JSON\s0 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. \f(CW\*(C`JSON\*(C'\fR
-optionally sort the hash keys (determined by the \fIcanonical\fR flag), so
-the same data structure will serialise to the same \s-1JSON\s0 text (given same
-settings and version of \s-1JSON::XS\s0), but this incurs a runtime overhead
-and is only rarely useful, e.g. when you want to compare some \s-1JSON\s0 text
-against another for equality.
-.IP "array references" 4
-.IX Item "array references"
-Perl array references become \s-1JSON\s0 arrays.
-.IP "other references" 4
-.IX Item "other references"
-Other unblessed references are generally not allowed and will cause an
-exception to be thrown, except for references to the integers \f(CW0\fR and
-\&\f(CW1\fR, which get turned into \f(CW\*(C`false\*(C'\fR and \f(CW\*(C`true\*(C'\fR atoms in \s-1JSON\s0. You can
-also use \f(CW\*(C`JSON::false\*(C'\fR and \f(CW\*(C`JSON::true\*(C'\fR to improve readability.
-.Sp
-.Vb 1
-\&   to_json [\e0,JSON::PP::true]      # yields [false,true]
-.Ve
-.IP "JSON::PP::true, JSON::PP::false, JSON::PP::null" 4
-.IX Item "JSON::PP::true, JSON::PP::false, JSON::PP::null"
-These special values become \s-1JSON\s0 true and \s-1JSON\s0 false values,
-respectively. You can also use \f(CW\*(C`\e1\*(C'\fR and \f(CW\*(C`\e0\*(C'\fR directly if you want.
-.Sp
-JSON::PP::null returns \f(CW\*(C`undef\*(C'\fR.
-.IP "blessed objects" 4
-.IX Item "blessed objects"
-Blessed objects are not directly representable in \s-1JSON\s0. See the
-\&\f(CW\*(C`allow_blessed\*(C'\fR and \f(CW\*(C`convert_blessed\*(C'\fR 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.
-.Sp
-See to convert_blessed.
-.IP "simple scalars" 4
-.IX Item "simple scalars"
-Simple Perl scalars (any scalar that is not a reference) are the most
-difficult objects to encode: \s-1JSON::XS\s0 and \s-1JSON::PP\s0 will encode undefined scalars as
-\&\s-1JSON\s0 \f(CW\*(C`null\*(C'\fR values, scalars that have last been used in a string context
-before encoding as \s-1JSON\s0 strings, and anything else as number value:
-.Sp
-.Vb 4
-\&   # 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]
-.Ve
-.Sp
-You can force the type to be a string by stringifying it:
-.Sp
-.Vb 4
-\&   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
-.Ve
-.Sp
-You can force the type to be a number by numifying it:
-.Sp
-.Vb 3
-\&   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.
-.Ve
-.Sp
-You can not currently force the type in other, less obscure, ways.
-.Sp
-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 \s-1JSON\s0, and it is an
-error to pass those in.
-.IP "Big Number" 4
-.IX Item "Big Number"
-When \f(CW\*(C`allow_bignum\*(C'\fR is enable, 
-\&\f(CW\*(C`encode\*(C'\fR converts \f(CW\*(C`Math::BigInt\*(C'\fR objects and \f(CW\*(C`Math::BigFloat\*(C'\fR
-objects into \s-1JSON\s0 numbers.
-.SH "UNICODE HANDLING ON PERLS"
-.IX Header "UNICODE HANDLING ON PERLS"
-If you do not know about Unicode on Perl well,
-please check \*(L"A \s-1FEW\s0 \s-1NOTES\s0 \s-1ON\s0 \s-1UNICODE\s0 \s-1AND\s0 \s-1PERL\s0\*(R" in \s-1JSON::XS\s0.
-.SS "Perl 5.8 and later"
-.IX Subsection "Perl 5.8 and later"
-Perl can handle Unicode and the \s-1JSON::PP\s0 de/encode methods also work properly.
-.PP
-.Vb 2
-\&    $json\->allow_nonref\->encode(chr hex 3042);
-\&    $json\->allow_nonref\->encode(chr hex 12345);
-.Ve
-.PP
-Returns \f(CW"\eu3042"\fR and \f(CW"\eud808\eudf45"\fR respectively.
-.PP
-.Vb 2
-\&    $json\->allow_nonref\->decode(\*(Aq"\eu3042"\*(Aq);
-\&    $json\->allow_nonref\->decode(\*(Aq"\eud808\eudf45"\*(Aq);
-.Ve
-.PP
-Returns \s-1UTF\-8\s0 encoded strings with \s-1UTF8\s0 flag, regarded as \f(CW\*(C`U+3042\*(C'\fR and \f(CW\*(C`U+12345\*(C'\fR.
-.PP
-Note that the versions from Perl 5.8.0 to 5.8.2, Perl built-in \f(CW\*(C`join\*(C'\fR was broken,
-so \s-1JSON::PP\s0 wraps the \f(CW\*(C`join\*(C'\fR with a subroutine. Thus \s-1JSON::PP\s0 works slow in the versions.
-.SS "Perl 5.6"
-.IX Subsection "Perl 5.6"
-Perl can handle Unicode and the \s-1JSON::PP\s0 de/encode methods also work.
-.SS "Perl 5.005"
-.IX Subsection "Perl 5.005"
-Perl 5.005 is a byte semantics world \*(-- all strings are sequences of bytes.
-That means the unicode handling is not available.
-.PP
-In encoding,
-.PP
-.Vb 2
-\&    $json\->allow_nonref\->encode(chr hex 3042);  # hex 3042 is 12354.
-\&    $json\->allow_nonref\->encode(chr hex 12345); # hex 12345 is 74565.
-.Ve
-.PP
-Returns \f(CW\*(C`B\*(C'\fR and \f(CW\*(C`E\*(C'\fR, as \f(CW\*(C`chr\*(C'\fR takes a value more than 255, it treats
-as \f(CW\*(C`$value % 256\*(C'\fR, so the above codes are equivalent to :
-.PP
-.Vb 2
-\&    $json\->allow_nonref\->encode(chr 66);
-\&    $json\->allow_nonref\->encode(chr 69);
-.Ve
-.PP
-In decoding,
-.PP
-.Vb 1
-\&    $json\->decode(\*(Aq"\eu00e3\eu0081\eu0082"\*(Aq);
-.Ve
-.PP
-The returned is a byte sequence \f(CW\*(C`0xE3 0x81 0x82\*(C'\fR for \s-1UTF\-8\s0 encoded
-japanese character (\f(CW\*(C`HIRAGANA LETTER A\*(C'\fR).
-And if it is represented in Unicode code point, \f(CW\*(C`U+3042\*(C'\fR.
-.PP
-Next,
-.PP
-.Vb 1
-\&    $json\->decode(\*(Aq"\eu3042"\*(Aq);
-.Ve
-.PP
-We ordinary expect the returned value is a Unicode character \f(CW\*(C`U+3042\*(C'\fR.
-But here is 5.005 world. This is \f(CW\*(C`0xE3 0x81 0x82\*(C'\fR.
-.PP
-.Vb 1
-\&    $json\->decode(\*(Aq"\eud808\eudf45"\*(Aq);
-.Ve
-.PP
-This is not a character \f(CW\*(C`U+12345\*(C'\fR but bytes \- \f(CW\*(C`0xf0 0x92 0x8d 0x85\*(C'\fR.
-.SH "TODO"
-.IX Header "TODO"
-.IP "speed" 4
-.IX Item "speed"
-.PD 0
-.IP "memory saving" 4
-.IX Item "memory saving"
-.PD
-.SH "SEE ALSO"
-.IX Header "SEE ALSO"
-Most of the document are copied and modified from \s-1JSON::XS\s0 doc.
-.PP
-\&\s-1JSON::XS\s0
-.PP
-\&\s-1RFC4627\s0 (<http://www.ietf.org/rfc/rfc4627.txt>)
-.SH "AUTHOR"
-.IX Header "AUTHOR"
-Makamaka Hannyaharamitu, <makamaka[at]cpan.org>
-.SH "COPYRIGHT AND LICENSE"
-.IX Header "COPYRIGHT AND LICENSE"
-Copyright 2007\-2012 by Makamaka Hannyaharamitu
-.PP
-This library is free software; you can redistribute it and/or modify
-it under the same terms as Perl itself.