local-lib5/man/man3/JSON::PP.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "JSON::PP 3"
 132 .TH JSON::PP 3 "2009-10-16" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 JSON::PP \- JSON::XS compatible pure\-Perl module.
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 1
 138 \& use JSON::PP;
 139 .Ve
 140 .PP
 141 .Vb 2
 142 \& # exported functions, they croak on error
 143 \& # and expect/generate UTF\-8
 144 .Ve
 145 .PP
 146 .Vb 2
 147 \& $utf8_encoded_json_text = encode_json $perl_hash_or_arrayref;
 148 \& $perl_hash_or_arrayref  = decode_json $utf8_encoded_json_text;
 149 .Ve
 150 .PP
 151 .Vb 1
 152 \& # OO\-interface
 153 .Ve
 154 .PP
 155 .Vb 3
 156 \& $coder = JSON::PP\->new\->ascii\->pretty\->allow_nonref;
 157 \& $pretty_printed_unencoded = $coder\->encode ($perl_scalar);
 158 \& $perl_scalar = $coder\->decode ($unicode_json_text);
 159 .Ve
 160 .PP
 161 .Vb 2
 162 \& # Note that JSON version 2.0 and above will automatically use
 163 \& # JSON::XS or JSON::PP, so you should be able to just:
 164 .Ve
 165 .PP
 166 .Vb 1
 167 \& use JSON;
 168 .Ve
 169 .SH "DESCRIPTION"
 170 .IX Header "DESCRIPTION"
 171 This module is \s-1JSON::XS\s0 compatible pure Perl module.
 172 (Perl 5.8 or later is recommended)
 173 .PP
 174 \&\s-1JSON::XS\s0 is the fastest and most proper \s-1JSON\s0 module on \s-1CPAN\s0.
 175 It is written by Marc Lehmann in C, so must be compiled and
 176 installed in the used environment.
 177 .PP
 178 \&\s-1JSON::PP\s0 is a pure-Perl module and has compatibility to \s-1JSON::XS\s0.
 179 .Sh "\s-1FEATURES\s0"
 180 .IX Subsection "FEATURES"
 181 .IP "* correct unicode handling" 4
 182 .IX Item "correct unicode handling"
 183 This module knows how to handle Unicode (depending on Perl version).
 184 .Sp
 185 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".
 186 .IP "* round-trip integrity" 4
 187 .IX Item "round-trip integrity"
 188 When you serialise a perl data structure using only datatypes supported by \s-1JSON\s0,
 189 the deserialised data structure is identical on the Perl level.
 190 (e.g. the string \*(L"2.0\*(R" doesn't suddenly become \*(L"2\*(R" just because it looks like a number).
 191 .IP "* strict checking of \s-1JSON\s0 correctness" 4
 192 .IX Item "strict checking of JSON correctness"
 193 There is no guessing, no generating of illegal \s-1JSON\s0 texts by default,
 194 and only \s-1JSON\s0 is accepted as input by default (the latter is a security feature).
 195 But when some options are set, loose chcking features are available.
 196 .SH "FUNCTIONS"
 197 .IX Header "FUNCTIONS"
 198 Basically, check to \s-1JSON\s0 or \s-1JSON::XS\s0.
 199 .Sh "encode_json"
 200 .IX Subsection "encode_json"
 201 .Vb 1
 202 \&    $json_text = encode_json $perl_scalar
 203 .Ve
 204 .Sh "decode_json"
 205 .IX Subsection "decode_json"
 206 .Vb 1
 207 \&    $perl_scalar = decode_json $json_text
 208 .Ve
 209 .Sh "JSON::PP::true"
 210 .IX Subsection "JSON::PP::true"
 211 Returns \s-1JSON\s0 true value which is blessed object.
 212 It \f(CW\*(C`isa\*(C'\fR JSON::PP::Boolean object.
 213 .Sh "JSON::PP::false"
 214 .IX Subsection "JSON::PP::false"
 215 Returns \s-1JSON\s0 false value which is blessed object.
 216 It \f(CW\*(C`isa\*(C'\fR JSON::PP::Boolean object.
 217 .Sh "JSON::PP::null"
 218 .IX Subsection "JSON::PP::null"
 219 Returns \f(CW\*(C`undef\*(C'\fR.
 220 .SH "METHODS"
 221 .IX Header "METHODS"
 222 Basically, check to \s-1JSON\s0 or \s-1JSON::XS\s0.
 223 .Sh "new"
 224 .IX Subsection "new"
 225 .Vb 1
 226 \&    $json = new JSON::PP
 227 .Ve
 228 .PP
 229 Rturns a new \s-1JSON::PP\s0 object that can be used to de/encode \s-1JSON\s0
 230 strings.
 231 .Sh "ascii"
 232 .IX Subsection "ascii"
 233 .Vb 1
 234 \&    $json = $json\->ascii([$enable])
 235 .Ve
 236 .PP
 237 .Vb 1
 238 \&    $enabled = $json\->get_ascii
 239 .Ve
 240 .PP
 241 If \f(CW$enable\fR is true (or missing), then the encode method will not generate characters outside
 242 the code range 0..127. Any Unicode characters outside that range will be escaped using either
 243 a single \euXXXX or a double \euHHHH\euLLLLL escape sequence, as per \s-1RFC4627\s0.
 244 (See to \*(L"\s-1OBJECT\-ORIENTED\s0 \s-1INTERFACE\s0\*(R" in \s-1JSON::XS\s0).
 245 .PP
 246 In Perl 5.005, there is no character having high value (more than 255).
 247 See to \*(L"\s-1UNICODE\s0 \s-1HANDLING\s0 \s-1ON\s0 \s-1PERLS\s0\*(R".
 248 .PP
 249 If \f(CW$enable\fR is false, then the encode method will not escape Unicode characters unless
 250 required by the \s-1JSON\s0 syntax or other flags. This results in a faster and more compact format.
 251 .PP
 252 .Vb 2
 253 \&  JSON::PP\->new\->ascii(1)\->encode([chr 0x10401])
 254 \&  => ["\eud801\eudc01"]
 255 .Ve
 256 .Sh "latin1"
 257 .IX Subsection "latin1"
 258 .Vb 1
 259 \&    $json = $json\->latin1([$enable])
 260 .Ve
 261 .PP
 262 .Vb 1
 263 \&    $enabled = $json\->get_latin1
 264 .Ve
 265 .PP
 266 If \f(CW$enable\fR is true (or missing), then the encode method will encode the resulting \s-1JSON\s0
 267 text as latin1 (or iso\-8859\-1), escaping any characters outside the code range 0..255.
 268 .PP
 269 If \f(CW$enable\fR is false, then the encode method will not escape Unicode characters
 270 unless required by the \s-1JSON\s0 syntax or other flags.
 271 .PP
 272 .Vb 2
 273 \&  JSON::XS\->new\->latin1\->encode (["\ex{89}\ex{abc}"]
 274 \&  => ["\ex{89}\e\eu0abc"]    # (perl syntax, U+abc escaped, U+89 not)
 275 .Ve
 276 .PP
 277 See to \*(L"\s-1UNICODE\s0 \s-1HANDLING\s0 \s-1ON\s0 \s-1PERLS\s0\*(R".
 278 .Sh "utf8"
 279 .IX Subsection "utf8"
 280 .Vb 1
 281 \&    $json = $json\->utf8([$enable])
 282 .Ve
 283 .PP
 284 .Vb 1
 285 \&    $enabled = $json\->get_utf8
 286 .Ve
 287 .PP
 288 If \f(CW$enable\fR is true (or missing), then the encode method will encode the \s-1JSON\s0 result
 289 into \s-1UTF\-8\s0, as required by many protocols, while the decode method expects to be handled
 290 an UTF\-8\-encoded string. Please note that UTF\-8\-encoded strings do not contain any
 291 characters outside the range 0..255, they are thus useful for bytewise/binary I/O.
 292 .PP
 293 (In Perl 5.005, any character outside the range 0..255 does not exist.
 294 See to \*(L"\s-1UNICODE\s0 \s-1HANDLING\s0 \s-1ON\s0 \s-1PERLS\s0\*(R".)
 295 .PP
 296 In future versions, enabling this option might enable autodetection of the \s-1UTF\-16\s0 and \s-1UTF\-32\s0
 297 encoding families, as described in \s-1RFC4627\s0.
 298 .PP
 299 If \f(CW$enable\fR is false, then the encode method will return the \s-1JSON\s0 string as a (non\-encoded)
 300 Unicode string, while decode expects thus a Unicode string. Any decoding or encoding
 301 (e.g. to \s-1UTF\-8\s0 or \s-1UTF\-16\s0) needs to be done yourself, e.g. using the Encode module.
 302 .PP
 303 Example, output UTF\-16BE\-encoded \s-1JSON:\s0
 304 .PP
 305 .Vb 2
 306 \&  use Encode;
 307 \&  $jsontext = encode "UTF\-16BE", JSON::XS\->new\->encode ($object);
 308 .Ve
 309 .PP
 310 Example, decode UTF\-32LE\-encoded \s-1JSON:\s0
 311 .PP
 312 .Vb 2
 313 \&  use Encode;
 314 \&  $object = JSON::XS\->new\->decode (decode "UTF\-32LE", $jsontext);
 315 .Ve
 316 .Sh "pretty"
 317 .IX Subsection "pretty"
 318 .Vb 1
 319 \&    $json = $json\->pretty([$enable])
 320 .Ve
 321 .PP
 322 This enables (or disables) all of the \f(CW\*(C`indent\*(C'\fR, \f(CW\*(C`space_before\*(C'\fR and
 323 \&\f(CW\*(C`space_after\*(C'\fR flags in one call to generate the most readable
 324 (or most compact) form possible.
 325 .Sh "indent"
 326 .IX Subsection "indent"
 327 .Vb 1
 328 \&    $json = $json\->indent([$enable])
 329 .Ve
 330 .PP
 331 .Vb 1
 332 \&    $enabled = $json\->get_indent
 333 .Ve
 334 .PP
 335 The default indent space lenght is three.
 336 You can use \f(CW\*(C`indent_length\*(C'\fR to change the length.
 337 .Sh "space_before"
 338 .IX Subsection "space_before"
 339 .Vb 1
 340 \&    $json = $json\->space_before([$enable])
 341 .Ve
 342 .PP
 343 .Vb 1
 344 \&    $enabled = $json\->get_space_before
 345 .Ve
 346 .Sh "space_after"
 347 .IX Subsection "space_after"
 348 .Vb 1
 349 \&    $json = $json\->space_after([$enable])
 350 .Ve
 351 .PP
 352 .Vb 1
 353 \&    $enabled = $json\->get_space_after
 354 .Ve
 355 .Sh "relaxed"
 356 .IX Subsection "relaxed"
 357 .Vb 1
 358 \&    $json = $json\->relaxed([$enable])
 359 .Ve
 360 .PP
 361 .Vb 1
 362 \&    $enabled = $json\->get_relaxed
 363 .Ve
 364 .Sh "canonical"
 365 .IX Subsection "canonical"
 366 .Vb 1
 367 \&    $json = $json\->canonical([$enable])
 368 .Ve
 369 .PP
 370 .Vb 1
 371 \&    $enabled = $json\->get_canonical
 372 .Ve
 373 .PP
 374 If you want your own sorting routine, you can give a code referece
 375 or a subroutine name to \f(CW\*(C`sort_by\*(C'\fR. See to \f(CW\*(C`JSON::PP OWN METHODS\*(C'\fR.
 376 .Sh "allow_nonref"
 377 .IX Subsection "allow_nonref"
 378 .Vb 1
 379 \&    $json = $json\->allow_nonref([$enable])
 380 .Ve
 381 .PP
 382 .Vb 1
 383 \&    $enabled = $json\->get_allow_nonref
 384 .Ve
 385 .Sh "allow_unknown"
 386 .IX Subsection "allow_unknown"
 387 .Vb 1
 388 \&    $json = $json\->allow_unknown ([$enable])
 389 .Ve
 390 .PP
 391 .Vb 1
 392 \&    $enabled = $json\->get_allow_unknown
 393 .Ve
 394 .Sh "allow_blessed"
 395 .IX Subsection "allow_blessed"
 396 .Vb 1
 397 \&    $json = $json\->allow_blessed([$enable])
 398 .Ve
 399 .PP
 400 .Vb 1
 401 \&    $enabled = $json\->get_allow_blessed
 402 .Ve
 403 .Sh "convert_blessed"
 404 .IX Subsection "convert_blessed"
 405 .Vb 1
 406 \&    $json = $json\->convert_blessed([$enable])
 407 .Ve
 408 .PP
 409 .Vb 1
 410 \&    $enabled = $json\->get_convert_blessed
 411 .Ve
 412 .Sh "filter_json_object"
 413 .IX Subsection "filter_json_object"
 414 .Vb 1
 415 \&    $json = $json\->filter_json_object([$coderef])
 416 .Ve
 417 .Sh "filter_json_single_key_object"
 418 .IX Subsection "filter_json_single_key_object"
 419 .Vb 1
 420 \&    $json = $json\->filter_json_single_key_object($key [=> $coderef])
 421 .Ve
 422 .Sh "shrink"
 423 .IX Subsection "shrink"
 424 .Vb 1
 425 \&    $json = $json\->shrink([$enable])
 426 .Ve
 427 .PP
 428 .Vb 1
 429 \&    $enabled = $json\->get_shrink
 430 .Ve
 431 .PP
 432 In \s-1JSON::XS\s0, this flag resizes strings generated by either
 433 \&\f(CW\*(C`encode\*(C'\fR or \f(CW\*(C`decode\*(C'\fR to their minimum size possible.
 434 It will also try to downgrade any strings to octet-form if possible.
 435 .PP
 436 In \s-1JSON::PP\s0, it is noop about resizing strings but tries
 437 \&\f(CW\*(C`utf8::downgrade\*(C'\fR to the returned string by \f(CW\*(C`encode\*(C'\fR.
 438 See to utf8.
 439 .PP
 440 See to \*(L"\s-1OBJECT\-ORIENTED\s0 \s-1INTERFACE\s0\*(R" in \s-1JSON::XS\s0
 441 .Sh "max_depth"
 442 .IX Subsection "max_depth"
 443 .Vb 1
 444 \&    $json = $json\->max_depth([$maximum_nesting_depth])
 445 .Ve
 446 .PP
 447 .Vb 1
 448 \&    $max_depth = $json\->get_max_depth
 449 .Ve
 450 .PP
 451 Sets the maximum nesting level (default \f(CW512\fR) accepted while encoding
 452 or decoding. If a higher nesting level is detected in \s-1JSON\s0 text or a Perl
 453 data structure, then the encoder and decoder will stop and croak at that
 454 point.
 455 .PP
 456 Nesting level is defined by number of hash\- or arrayrefs that the encoder
 457 needs to traverse to reach a given point or the number of \f(CW\*(C`{\*(C'\fR or \f(CW\*(C`[\*(C'\fR
 458 characters without their matching closing parenthesis crossed to reach a
 459 given character in a string.
 460 .PP
 461 If no argument is given, the highest possible setting will be used, which
 462 is rarely useful.
 463 .PP
 464 See \*(L"\s-1SSECURITY\s0 \s-1CONSIDERATIONS\s0\*(R" in \s-1JSON::XS\s0 for more info on why this is useful.
 465 .PP
 466 When a large value (100 or more) was set and it de/encodes a deep nested object/text,
 467 it may raise a warning 'Deep recursion on subroutin' at the perl runtime phase.
 468 .Sh "max_size"
 469 .IX Subsection "max_size"
 470 .Vb 1
 471 \&    $json = $json\->max_size([$maximum_string_size])
 472 .Ve
 473 .PP
 474 .Vb 1
 475 \&    $max_size = $json\->get_max_size
 476 .Ve
 477 .PP
 478 Set the maximum length a \s-1JSON\s0 text may have (in bytes) where decoding is
 479 being attempted. The default is \f(CW0\fR, meaning no limit. When \f(CW\*(C`decode\*(C'\fR
 480 is called on a string that is longer then this many bytes, it will not
 481 attempt to decode the string but throw an exception. This setting has no
 482 effect on \f(CW\*(C`encode\*(C'\fR (yet).
 483 .PP
 484 If no argument is given, the limit check will be deactivated (same as when
 485 \&\f(CW0\fR is specified).
 486 .PP
 487 See \*(L"\s-1SSECURITY\s0 \s-1CONSIDERATIONS\s0\*(R" in \s-1JSON::XS\s0 for more info on why this is useful.
 488 .Sh "encode"
 489 .IX Subsection "encode"
 490 .Vb 1
 491 \&    $json_text = $json\->encode($perl_scalar)
 492 .Ve
 493 .Sh "decode"
 494 .IX Subsection "decode"
 495 .Vb 1
 496 \&    $perl_scalar = $json\->decode($json_text)
 497 .Ve
 498 .Sh "decode_prefix"
 499 .IX Subsection "decode_prefix"
 500 .Vb 1
 501 \&    ($perl_scalar, $characters) = $json\->decode_prefix($json_text)
 502 .Ve
 503 .SH "INCREMENTAL PARSING"
 504 .IX Header "INCREMENTAL PARSING"
 505 In \s-1JSON::XS\s0 2.2, incremental parsing feature of \s-1JSON\s0
 506 texts was experimentally implemented.
 507 Please check to \*(L"\s-1INCREMENTAL\s0 \s-1PARSING\s0\*(R" in \s-1JSON::XS\s0.
 508 .ie n .IP "[void, scalar or list context] = $json\->incr_parse ([$string])" 4
 509 .el .IP "[void, scalar or list context] = \f(CW$json\fR\->incr_parse ([$string])" 4
 510 .IX Item "[void, scalar or list context] = $json->incr_parse ([$string])"
 511 This is the central parsing function. It can both append new text and
 512 extract objects from the stream accumulated so far (both of these
 513 functions are optional).
 514 .Sp
 515 If \f(CW$string\fR is given, then this string is appended to the already
 516 existing \s-1JSON\s0 fragment stored in the \f(CW$json\fR object.
 517 .Sp
 518 After that, if the function is called in void context, it will simply
 519 return without doing anything further. This can be used to add more text
 520 in as many chunks as you want.
 521 .Sp
 522 If the method is called in scalar context, then it will try to extract
 523 exactly \fIone\fR \s-1JSON\s0 object. If that is successful, it will return this
 524 object, otherwise it will return \f(CW\*(C`undef\*(C'\fR. If there is a parse error,
 525 this method will croak just as \f(CW\*(C`decode\*(C'\fR would do (one can then use
 526 \&\f(CW\*(C`incr_skip\*(C'\fR to skip the errornous part). This is the most common way of
 527 using the method.
 528 .Sp
 529 And finally, in list context, it will try to extract as many objects
 530 from the stream as it can find and return them, or the empty list
 531 otherwise. For this to work, there must be no separators between the \s-1JSON\s0
 532 objects or arrays, instead they must be concatenated back\-to\-back. If
 533 an error occurs, an exception will be raised as in the scalar context
 534 case. Note that in this case, any previously-parsed \s-1JSON\s0 texts will be
 535 lost.
 536 .ie n .IP "$lvalue_string = $json\->incr_text" 4
 537 .el .IP "$lvalue_string = \f(CW$json\fR\->incr_text" 4
 538 .IX Item "$lvalue_string = $json->incr_text"
 539 This method returns the currently stored \s-1JSON\s0 fragment as an lvalue, that
 540 is, you can manipulate it. This \fIonly\fR works when a preceding call to
 541 \&\f(CW\*(C`incr_parse\*(C'\fR in \fIscalar context\fR successfully returned an object. Under
 542 all other circumstances you must not call this function (I mean it.
 543 although in simple tests it might actually work, it \fIwill\fR fail under
 544 real world conditions). As a special exception, you can also call this
 545 method before having parsed anything.
 546 .Sp
 547 This function is useful in two cases: a) finding the trailing text after a
 548 \&\s-1JSON\s0 object or b) parsing multiple \s-1JSON\s0 objects separated by non-JSON text
 549 (such as commas).
 550 .Sp
 551 In Perl 5.005, \f(CW\*(C`lvalue\*(C'\fR attribute is not available.
 552 You must write codes like the below:
 553 .Sp
 554 .Vb 3
 555 \&    $string = $json\->incr_text;
 556 \&    $string =~ s/\es*,\es*//;
 557 \&    $json\->incr_text( $string );
 558 .Ve
 559 .IP "$json\->incr_skip" 4
 560 .IX Item "$json->incr_skip"
 561 This will reset the state of the incremental parser and will remove the
 562 parsed text from the input buffer. This is useful after \f(CW\*(C`incr_parse\*(C'\fR
 563 died, in which case the input buffer and incremental parser state is left
 564 unchanged, to skip the text parsed so far and to reset the parse state.
 565 .SH "JSON::PP OWN METHODS"
 566 .IX Header "JSON::PP OWN METHODS"
 567 .Sh "allow_singlequote"
 568 .IX Subsection "allow_singlequote"
 569 .Vb 1
 570 \&    $json = $json\->allow_singlequote([$enable])
 571 .Ve
 572 .PP
 573 If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`decode\*(C'\fR will accept
 574 \&\s-1JSON\s0 strings quoted by single quotations that are invalid \s-1JSON\s0
 575 format.
 576 .PP
 577 .Vb 3
 578 \&    $json\->allow_singlequote\->decode({"foo":'bar'});
 579 \&    $json\->allow_singlequote\->decode({'foo':"bar"});
 580 \&    $json\->allow_singlequote\->decode({'foo':'bar'});
 581 .Ve
 582 .PP
 583 As same as the \f(CW\*(C`relaxed\*(C'\fR option, this option may be used to parse
 584 application-specific files written by humans.
 585 .Sh "allow_barekey"
 586 .IX Subsection "allow_barekey"
 587 .Vb 1
 588 \&    $json = $json\->allow_barekey([$enable])
 589 .Ve
 590 .PP
 591 If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`decode\*(C'\fR will accept
 592 bare keys of \s-1JSON\s0 object that are invalid \s-1JSON\s0 format.
 593 .PP
 594 As same as the \f(CW\*(C`relaxed\*(C'\fR option, this option may be used to parse
 595 application-specific files written by humans.
 596 .PP
 597 .Vb 1
 598 \&    $json\->allow_barekey\->decode('{foo:"bar"}');
 599 .Ve
 600 .Sh "allow_bignum"
 601 .IX Subsection "allow_bignum"
 602 .Vb 1
 603 \&    $json = $json\->allow_bignum([$enable])
 604 .Ve
 605 .PP
 606 If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`decode\*(C'\fR will convert
 607 the big integer Perl cannot handle as integer into a Math::BigInt
 608 object and convert a floating number (any) into a Math::BigFloat.
 609 .PP
 610 On the contary, \f(CW\*(C`encode\*(C'\fR converts \f(CW\*(C`Math::BigInt\*(C'\fR objects and \f(CW\*(C`Math::BigFloat\*(C'\fR
 611 objects into \s-1JSON\s0 numbers with \f(CW\*(C`allow_blessed\*(C'\fR enable.
 612 .PP
 613 .Vb 4
 614 \&   $json\->allow_nonref\->allow_blessed\->allow_bignum;
 615 \&   $bigfloat = $json\->decode('2.000000000000000000000000001');
 616 \&   print $json\->encode($bigfloat);
 617 \&   # => 2.000000000000000000000000001
 618 .Ve
 619 .PP
 620 See to \*(L"\s-1MAPPING\s0\*(R" in \s-1JSON::XS\s0 aboout the normal conversion of \s-1JSON\s0 number.
 621 .Sh "loose"
 622 .IX Subsection "loose"
 623 .Vb 1
 624 \&    $json = $json\->loose([$enable])
 625 .Ve
 626 .PP
 627 The unescaped [\ex00\-\ex1f\ex22\ex2f\ex5c] strings are invalid in \s-1JSON\s0 strings
 628 and the module doesn't allow to \f(CW\*(C`decode\*(C'\fR to these (except for \ex2f).
 629 If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`decode\*(C'\fR  will accept these
 630 unescaped strings.
 631 .PP
 632 .Vb 2
 633 \&    $json\->loose\->decode(qq|["abc
 634 \&                                   def"]|);
 635 .Ve
 636 .PP
 637 See \*(L"\s-1SSECURITY\s0 \s-1CONSIDERATIONS\s0\*(R" in \s-1JSON::XS\s0.
 638 .Sh "escape_slash"
 639 .IX Subsection "escape_slash"
 640 .Vb 1
 641 \&    $json = $json\->escape_slash([$enable])
 642 .Ve
 643 .PP
 644 According to \s-1JSON\s0 Grammar, \fIslash\fR (U+002F) is escaped. But default
 645 \&\s-1JSON::PP\s0 (as same as \s-1JSON::XS\s0) encodes strings without escaping slash.
 646 .PP
 647 If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`encode\*(C'\fR will escape slashes.
 648 .Sh "(\s-1OBSOLETED\s0)as_nonblessed"
 649 .IX Subsection "(OBSOLETED)as_nonblessed"
 650 .Vb 1
 651 \&    $json = $json\->as_nonblessed
 652 .Ve
 653 .PP
 654 (\s-1OBSOLETED\s0) If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`encode\*(C'\fR will convert
 655 a blessed hash reference or a blessed array reference (contains
 656 other blessed references) into \s-1JSON\s0 members and arrays.
 657 .PP
 658 This feature is effective only when \f(CW\*(C`allow_blessed\*(C'\fR is enable.
 659 .Sh "indent_length"
 660 .IX Subsection "indent_length"
 661 .Vb 1
 662 \&    $json = $json\->indent_length($length)
 663 .Ve
 664 .PP
 665 \&\s-1JSON::XS\s0 indent space length is 3 and cannot be changed.
 666 \&\s-1JSON::PP\s0 set the indent space length with the given \f(CW$length\fR.
 667 The default is 3. The acceptable range is 0 to 15.
 668 .Sh "sort_by"
 669 .IX Subsection "sort_by"
 670 .Vb 2
 671 \&    $json = $json\->sort_by($function_name)
 672 \&    $json = $json\->sort_by($subroutine_ref)
 673 .Ve
 674 .PP
 675 If \f(CW$function_name\fR or \f(CW$subroutine_ref\fR are set, its sort routine are used
 676 in encoding \s-1JSON\s0 objects.
 677 .PP
 678 .Vb 2
 679 \&   $js = $pc\->sort_by(sub { $JSON::PP::a cmp $JSON::PP::b })\->encode($obj);
 680 \&   # is($js, q|{"a":1,"b":2,"c":3,"d":4,"e":5,"f":6,"g":7,"h":8,"i":9}|);
 681 .Ve
 682 .PP
 683 .Vb 2
 684 \&   $js = $pc\->sort_by('own_sort')\->encode($obj);
 685 \&   # is($js, q|{"a":1,"b":2,"c":3,"d":4,"e":5,"f":6,"g":7,"h":8,"i":9}|);
 686 .Ve
 687 .PP
 688 .Vb 1
 689 \&   sub JSON::PP::own_sort { $JSON::PP::a cmp $JSON::PP::b }
 690 .Ve
 691 .PP
 692 As the sorting routine runs in the \s-1JSON::PP\s0 scope, the given
 693 subroutine name and the special variables \f(CW$a\fR, \f(CW$b\fR will begin
 694 \&'\s-1JSON::PP::\s0'.
 695 .PP
 696 If \f(CW$integer\fR is set, then the effect is same as \f(CW\*(C`canonical\*(C'\fR on.
 697 .SH "INTERNAL"
 698 .IX Header "INTERNAL"
 699 For developers.
 700 .IP "PP_encode_box" 4
 701 .IX Item "PP_encode_box"
 702 Returns
 703 .Sp
 704 .Vb 4
 705 \&        {
 706 \&            depth        => $depth,
 707 \&            indent_count => $indent_count,
 708 \&        }
 709 .Ve
 710 .IP "PP_decode_box" 4
 711 .IX Item "PP_decode_box"
 712 Returns
 713 .Sp
 714 .Vb 9
 715 \&        {
 716 \&            text    => $text,
 717 \&            at      => $at,
 718 \&            ch      => $ch,
 719 \&            len     => $len,
 720 \&            depth   => $depth,
 721 \&            encoding      => $encoding,
 722 \&            is_valid_utf8 => $is_valid_utf8,
 723 \&        };
 724 .Ve
 725 .SH "MAPPING"
 726 .IX Header "MAPPING"
 727 See to \*(L"\s-1MAPPING\s0\*(R" in \s-1JSON::XS\s0.
 728 .SH "UNICODE HANDLING ON PERLS"
 729 .IX Header "UNICODE HANDLING ON PERLS"
 730 If you do not know about Unicode on Perl well,
 731 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.
 732 .Sh "Perl 5.8 and later"
 733 .IX Subsection "Perl 5.8 and later"
 734 Perl can handle Unicode and the \s-1JSON::PP\s0 de/encode methods also work properly.
 735 .PP
 736 .Vb 2
 737 \&    $json\->allow_nonref\->encode(chr hex 3042);
 738 \&    $json\->allow_nonref\->encode(chr hex 12345);
 739 .Ve
 740 .PP
 741 Reuturns \f(CW"\eu3042"\fR and \f(CW"\eud808\eudf45"\fR respectively.
 742 .PP
 743 .Vb 2
 744 \&    $json\->allow_nonref\->decode('"\eu3042"');
 745 \&    $json\->allow_nonref\->decode('"\eud808\eudf45"');
 746 .Ve
 747 .PP
 748 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.
 749 .PP
 750 Note that the versions from Perl 5.8.0 to 5.8.2, Perl built-in \f(CW\*(C`join\*(C'\fR was broken,
 751 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.
 752 .Sh "Perl 5.6"
 753 .IX Subsection "Perl 5.6"
 754 Perl can handle Unicode and the \s-1JSON::PP\s0 de/encode methods also work.
 755 .Sh "Perl 5.005"
 756 .IX Subsection "Perl 5.005"
 757 Perl 5.005 is a byte sementics world \*(-- all strings are sequences of bytes.
 758 That means the unicode handling is not available.
 759 .PP
 760 In encoding,
 761 .PP
 762 .Vb 2
 763 \&    $json\->allow_nonref\->encode(chr hex 3042);  # hex 3042 is 12354.
 764 \&    $json\->allow_nonref\->encode(chr hex 12345); # hex 12345 is 74565.
 765 .Ve
 766 .PP
 767 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
 768 as \f(CW\*(C`$value % 256\*(C'\fR, so the above codes are equivalent to :
 769 .PP
 770 .Vb 2
 771 \&    $json\->allow_nonref\->encode(chr 66);
 772 \&    $json\->allow_nonref\->encode(chr 69);
 773 .Ve
 774 .PP
 775 In decoding,
 776 .PP
 777 .Vb 1
 778 \&    $json\->decode('"\eu00e3\eu0081\eu0082"');
 779 .Ve
 780 .PP
 781 The returned is a byte sequence \f(CW\*(C`0xE3 0x81 0x82\*(C'\fR for \s-1UTF\-8\s0 encoded
 782 japanese character (\f(CW\*(C`HIRAGANA LETTER A\*(C'\fR).
 783 And if it is represented in Unicode code point, \f(CW\*(C`U+3042\*(C'\fR.
 784 .PP
 785 Next,
 786 .PP
 787 .Vb 1
 788 \&    $json\->decode('"\eu3042"');
 789 .Ve
 790 .PP
 791 We ordinary expect the returned value is a Unicode character \f(CW\*(C`U+3042\*(C'\fR.
 792 But here is 5.005 world. This is \f(CW\*(C`0xE3 0x81 0x82\*(C'\fR.
 793 .PP
 794 .Vb 1
 795 \&    $json\->decode('"\eud808\eudf45"');
 796 .Ve
 797 .PP
 798 This is not a character \f(CW\*(C`U+12345\*(C'\fR but bytes \- \f(CW\*(C`0xf0 0x92 0x8d 0x85\*(C'\fR.
 799 .SH "TODO"
 800 .IX Header "TODO"
 801 .IP "speed" 4
 802 .IX Item "speed"
 803 .PD 0
 804 .IP "memory saving" 4
 805 .IX Item "memory saving"
 806 .PD
 807 .SH "SEE ALSO"
 808 .IX Header "SEE ALSO"
 809 Most of the document are copied and modified from \s-1JSON::XS\s0 doc.
 810 .PP
 811 \&\s-1JSON::XS\s0
 812 .PP
 813 \&\s-1RFC4627\s0 (<http://www.ietf.org/rfc/rfc4627.txt>)
 814 .SH "AUTHOR"
 815 .IX Header "AUTHOR"
 816 Makamaka Hannyaharamitu, <makamaka[at]cpan.org>
 817 .SH "COPYRIGHT AND LICENSE"
 818 .IX Header "COPYRIGHT AND LICENSE"
 819 Copyright 2007\-2009 by Makamaka Hannyaharamitu
 820 .PP
 821 This library is free software; you can redistribute it and/or modify
 822 it under the same terms as Perl itself.