Add JSON.pm to third_party

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.