local-lib5/man/man3/JSON.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 3"
 132 .TH JSON 3 "2009-10-16" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 JSON \- JSON (JavaScript Object Notation) encoder/decoder
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 1
 138 \& use JSON; # imports encode_json, decode_json, to_json and from_json.
 139 .Ve
 140 .PP
 141 .Vb 2
 142 \& $json_text   = to_json($perl_scalar);
 143 \& $perl_scalar = from_json($json_text);
 144 .Ve
 145 .PP
 146 .Vb 3
 147 \& # option\-acceptable
 148 \& $json_text   = to_json($perl_scalar, {ascii => 1});
 149 \& $perl_scalar = from_json($json_text, {utf8 => 1});
 150 .Ve
 151 .PP
 152 .Vb 2
 153 \& # OOP
 154 \& $json = new JSON;
 155 .Ve
 156 .PP
 157 .Vb 2
 158 \& $json_text   = $json\->encode($perl_scalar);
 159 \& $perl_scalar = $json\->decode($json_text);
 160 .Ve
 161 .PP
 162 .Vb 2
 163 \& # pretty\-printing
 164 \& $json_text = $json\->pretty\->encode($perl_scalar);
 165 .Ve
 166 .PP
 167 .Vb 3
 168 \& # simple interface
 169 \& $utf8_encoded_json_text = encode_json $perl_hash_or_arrayref;
 170 \& $perl_hash_or_arrayref  = decode_json $utf8_encoded_json_text;
 171 .Ve
 172 .PP
 173 .Vb 2
 174 \& # If you want to use PP only support features, call with '\-support_by_pp'
 175 \& # When XS unsupported feature is enable, using PP de/encode.
 176 .Ve
 177 .PP
 178 .Vb 1
 179 \& use JSON \-support_by_pp;
 180 .Ve
 181 .SH "VERSION"
 182 .IX Header "VERSION"
 183 .Vb 1
 184 \&    2.16
 185 .Ve
 186 .PP
 187 This version is compatible with \s-1JSON::XS\s0 \fB2.26\fR and later.
 188 .SH "DESCRIPTION"
 189 .IX Header "DESCRIPTION"
 190 .Vb 6
 191 \& ************************** CAUTION ********************************
 192 \& * This is 'JSON module version 2' and there are many differences  *
 193 \& * to version 1.xx                                                 *
 194 \& * Please check your applications useing old version.              *
 195 \& *   See to 'INCOMPATIBLE CHANGES TO OLD VERSION'                  *
 196 \& *******************************************************************
 197 .Ve
 198 .PP
 199 \&\s-1JSON\s0 (JavaScript Object Notation) is a simple data format.
 200 See to <http://www.json.org/> and \f(CW\*(C`RFC4627\*(C'\fR(<http://www.ietf.org/rfc/rfc4627.txt>).
 201 .PP
 202 This module converts Perl data structures to \s-1JSON\s0 and vice versa using either
 203 \&\s-1JSON::XS\s0 or \s-1JSON::PP\s0.
 204 .PP
 205 \&\s-1JSON::XS\s0 is the fastest and most proper \s-1JSON\s0 module on \s-1CPAN\s0 which must be
 206 compiled and installed in your environment.
 207 \&\s-1JSON::PP\s0 is a pure-Perl module which is bundled in this distribution and
 208 has a strong compatibility to \s-1JSON::XS\s0.
 209 .PP
 210 This module try to use \s-1JSON::XS\s0 by default and fail to it, use \s-1JSON::PP\s0 instead.
 211 So its features completely depend on \s-1JSON::XS\s0 or \s-1JSON::PP\s0.
 212 .PP
 213 See to \*(L"\s-1BACKEND\s0 \s-1MODULE\s0 \s-1DECISION\s0\*(R".
 214 .PP
 215 To distinguish the module name '\s-1JSON\s0' and the format type \s-1JSON\s0,
 216 the former is quoted by C<> (its results vary with your using media),
 217 and the latter is left just as it is.
 218 .PP
 219 Module name : \f(CW\*(C`JSON\*(C'\fR
 220 .PP
 221 Format type : \s-1JSON\s0
 222 .Sh "\s-1FEATURES\s0"
 223 .IX Subsection "FEATURES"
 224 .IP "* correct unicode handling" 4
 225 .IX Item "correct unicode handling"
 226 This module (i.e. backend modules) knows how to handle Unicode, documents
 227 how and when it does so, and even documents what \*(L"correct\*(R" means.
 228 .Sp
 229 Even though there are limitations, this feature is available since Perl version 5.6.
 230 .Sp
 231 \&\s-1JSON::XS\s0 requires Perl 5.8.2 (but works correctly in 5.8.8 or later), so in older versions
 232 \&\f(CW\*(C`JSON\*(C'\fR sholud call \s-1JSON::PP\s0 as the backend which can be used since Perl 5.005.
 233 .Sp
 234 With Perl 5.8.x \s-1JSON::PP\s0 works, but from 5.8.0 to 5.8.2, because of a Perl side problem,
 235 \&\s-1JSON::PP\s0 works slower in the versions. And in 5.005, the Unicode handling is not available.
 236 See to \*(L"\s-1UNICODE\s0 \s-1HANDLING\s0 \s-1ON\s0 \s-1PERLS\s0\*(R" in \s-1JSON::PP\s0 for more information.
 237 .Sp
 238 See also 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
 239 and \*(L"\s-1ENCODING/CODESET_FLAG_NOTES\s0\*(R" in \s-1JSON::XS\s0.
 240 .IP "* round-trip integrity" 4
 241 .IX Item "round-trip integrity"
 242 When you serialise a perl data structure using only data types supported by \s-1JSON\s0,
 243 the deserialised data structure is identical on the Perl level.
 244 (e.g. the string \*(L"2.0\*(R" doesn't suddenly become \*(L"2\*(R" just because it looks
 245 like a number). There minor \fIare\fR exceptions to this, read the \s-1MAPPING\s0
 246 section below to learn about those.
 247 .IP "* strict checking of \s-1JSON\s0 correctness" 4
 248 .IX Item "strict checking of JSON correctness"
 249 There is no guessing, no generating of illegal \s-1JSON\s0 texts by default,
 250 and only \s-1JSON\s0 is accepted as input by default (the latter is a security
 251 feature).
 252 .Sp
 253 See to \*(L"\s-1FEATURES\s0\*(R" in \s-1JSON::XS\s0 and \*(L"\s-1FEATURES\s0\*(R" in \s-1JSON::PP\s0.
 254 .IP "* fast" 4
 255 .IX Item "fast"
 256 This module returns a \s-1JSON::XS\s0 object itself if avaliable.
 257 Compared to other \s-1JSON\s0 modules and other serialisers such as Storable,
 258 \&\s-1JSON::XS\s0 usually compares favourably in terms of speed, too.
 259 .Sp
 260 If not avaliable, \f(CW\*(C`JSON\*(C'\fR returns a \s-1JSON::PP\s0 object instead of \s-1JSON::XS\s0 and
 261 it is very slow as pure\-Perl.
 262 .IP "* simple to use" 4
 263 .IX Item "simple to use"
 264 This module has both a simple functional interface as well as an
 265 object oriented interface interface.
 266 .IP "* reasonably versatile output formats" 4
 267 .IX Item "reasonably versatile output formats"
 268 You can choose between the most compact guaranteed-single-line format possible
 269 (nice for simple line-based protocols), a pure-ASCII format (for when your transport
 270 is not 8\-bit clean, still supports the whole Unicode range), or a pretty-printed
 271 format (for when you want to read that stuff). Or you can combine those features
 272 in whatever way you like.
 273 .SH "FUNCTIONAL INTERFACE"
 274 .IX Header "FUNCTIONAL INTERFACE"
 275 Some documents are copied and modified from \*(L"\s-1FUNCTIONAL\s0 \s-1INTERFACE\s0\*(R" in \s-1JSON::XS\s0.
 276 \&\f(CW\*(C`to_json\*(C'\fR and \f(CW\*(C`from_json\*(C'\fR are additional functions.
 277 .Sh "to_json"
 278 .IX Subsection "to_json"
 279 .Vb 1
 280 \&   $json_text = to_json($perl_scalar)
 281 .Ve
 282 .PP
 283 Converts the given Perl data structure to a json string.
 284 .PP
 285 This function call is functionally identical to:
 286 .PP
 287 .Vb 1
 288 \&   $json_text = JSON\->new\->encode($perl_scalar)
 289 .Ve
 290 .PP
 291 Takes a hash reference as the second.
 292 .PP
 293 .Vb 1
 294 \&   $json_text = to_json($perl_scalar, $flag_hashref)
 295 .Ve
 296 .PP
 297 So,
 298 .PP
 299 .Vb 1
 300 \&   $json_text = encode_json($perl_scalar, {utf8 => 1, pretty => 1})
 301 .Ve
 302 .PP
 303 equivalent to:
 304 .PP
 305 .Vb 1
 306 \&   $json_text = JSON\->new\->utf8(1)\->pretty(1)\->encode($perl_scalar)
 307 .Ve
 308 .Sh "from_json"
 309 .IX Subsection "from_json"
 310 .Vb 1
 311 \&   $perl_scalar = from_json($json_text)
 312 .Ve
 313 .PP
 314 The opposite of \f(CW\*(C`to_json\*(C'\fR: expects a json string and tries
 315 to parse it, returning the resulting reference.
 316 .PP
 317 This function call is functionally identical to:
 318 .PP
 319 .Vb 1
 320 \&    $perl_scalar = JSON\->decode($json_text)
 321 .Ve
 322 .PP
 323 Takes a hash reference as the second.
 324 .PP
 325 .Vb 1
 326 \&    $perl_scalar = from_json($json_text, $flag_hashref)
 327 .Ve
 328 .PP
 329 So,
 330 .PP
 331 .Vb 1
 332 \&    $perl_scalar = from_json($json_text, {utf8 => 1})
 333 .Ve
 334 .PP
 335 equivalent to:
 336 .PP
 337 .Vb 1
 338 \&    $perl_scalar = JSON\->new\->utf8(1)\->decode($json_text)
 339 .Ve
 340 .Sh "encode_json"
 341 .IX Subsection "encode_json"
 342 .Vb 1
 343 \&    $json_text = encode_json $perl_scalar
 344 .Ve
 345 .PP
 346 Converts the given Perl data structure to a \s-1UTF\-8\s0 encoded, binary string.
 347 .PP
 348 This function call is functionally identical to:
 349 .PP
 350 .Vb 1
 351 \&    $json_text = JSON\->new\->utf8\->encode($perl_scalar)
 352 .Ve
 353 .Sh "decode_json"
 354 .IX Subsection "decode_json"
 355 .Vb 1
 356 \&    $perl_scalar = decode_json $json_text
 357 .Ve
 358 .PP
 359 The opposite of \f(CW\*(C`encode_json\*(C'\fR: expects an \s-1UTF\-8\s0 (binary) string and tries
 360 to parse that as an \s-1UTF\-8\s0 encoded \s-1JSON\s0 text, returning the resulting
 361 reference.
 362 .PP
 363 This function call is functionally identical to:
 364 .PP
 365 .Vb 1
 366 \&    $perl_scalar = JSON\->new\->utf8\->decode($json_text)
 367 .Ve
 368 .Sh "JSON::is_bool"
 369 .IX Subsection "JSON::is_bool"
 370 .Vb 1
 371 \&    $is_boolean = JSON::is_bool($scalar)
 372 .Ve
 373 .PP
 374 Returns true if the passed scalar represents either JSON::true or
 375 JSON::false, two constants that act like \f(CW1\fR and \f(CW0\fR respectively
 376 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.
 377 .Sh "JSON::true"
 378 .IX Subsection "JSON::true"
 379 Returns \s-1JSON\s0 true value which is blessed object.
 380 It \f(CW\*(C`isa\*(C'\fR JSON::Boolean object.
 381 .Sh "JSON::false"
 382 .IX Subsection "JSON::false"
 383 Returns \s-1JSON\s0 false value which is blessed object.
 384 It \f(CW\*(C`isa\*(C'\fR JSON::Boolean object.
 385 .Sh "JSON::null"
 386 .IX Subsection "JSON::null"
 387 Returns \f(CW\*(C`undef\*(C'\fR.
 388 .PP
 389 See \s-1MAPPING\s0, below, for more information on how \s-1JSON\s0 values are mapped to
 390 Perl.
 391 .SH "COMMON OBJECT-ORIENTED INTERFACE"
 392 .IX Header "COMMON OBJECT-ORIENTED INTERFACE"
 393 .Sh "new"
 394 .IX Subsection "new"
 395 .Vb 1
 396 \&    $json = new JSON
 397 .Ve
 398 .PP
 399 Returns a new \f(CW\*(C`JSON\*(C'\fR object inherited from either \s-1JSON::XS\s0 or \s-1JSON::PP\s0
 400 that can be used to de/encode \s-1JSON\s0 strings.
 401 .PP
 402 All boolean flags described below are by default \fIdisabled\fR.
 403 .PP
 404 The mutators for flags all return the \s-1JSON\s0 object again and thus calls can
 405 be chained:
 406 .PP
 407 .Vb 2
 408 \&   my $json = JSON\->new\->utf8\->space_after\->encode({a => [1,2]})
 409 \&   => {"a": [1, 2]}
 410 .Ve
 411 .Sh "ascii"
 412 .IX Subsection "ascii"
 413 .Vb 1
 414 \&    $json = $json\->ascii([$enable])
 415 .Ve
 416 .PP
 417 .Vb 1
 418 \&    $enabled = $json\->get_ascii
 419 .Ve
 420 .PP
 421 If \f(CW$enable\fR is true (or missing), then the encode method will not generate characters outside
 422 the code range 0..127. Any Unicode characters outside that range will be escaped using either
 423 a single \euXXXX or a double \euHHHH\euLLLLL escape sequence, as per \s-1RFC4627\s0.
 424 .PP
 425 If \f(CW$enable\fR is false, then the encode method will not escape Unicode characters unless
 426 required by the \s-1JSON\s0 syntax or other flags. This results in a faster and more compact format.
 427 .PP
 428 This feature depends on the used Perl version and environment.
 429 .PP
 430 See to \*(L"\s-1UNICODE\s0 \s-1HANDLING\s0 \s-1ON\s0 \s-1PERLS\s0\*(R" in \s-1JSON::PP\s0 if the backend is \s-1PP\s0.
 431 .PP
 432 .Vb 2
 433 \&  JSON\->new\->ascii(1)\->encode([chr 0x10401])
 434 \&  => ["\eud801\eudc01"]
 435 .Ve
 436 .Sh "latin1"
 437 .IX Subsection "latin1"
 438 .Vb 1
 439 \&    $json = $json\->latin1([$enable])
 440 .Ve
 441 .PP
 442 .Vb 1
 443 \&    $enabled = $json\->get_latin1
 444 .Ve
 445 .PP
 446 If \f(CW$enable\fR is true (or missing), then the encode method will encode the resulting \s-1JSON\s0
 447 text as latin1 (or iso\-8859\-1), escaping any characters outside the code range 0..255.
 448 .PP
 449 If \f(CW$enable\fR is false, then the encode method will not escape Unicode characters
 450 unless required by the \s-1JSON\s0 syntax or other flags.
 451 .PP
 452 .Vb 2
 453 \&  JSON\->new\->latin1\->encode (["\ex{89}\ex{abc}"]
 454 \&  => ["\ex{89}\e\eu0abc"]    # (perl syntax, U+abc escaped, U+89 not)
 455 .Ve
 456 .Sh "utf8"
 457 .IX Subsection "utf8"
 458 .Vb 1
 459 \&    $json = $json\->utf8([$enable])
 460 .Ve
 461 .PP
 462 .Vb 1
 463 \&    $enabled = $json\->get_utf8
 464 .Ve
 465 .PP
 466 If \f(CW$enable\fR is true (or missing), then the encode method will encode the \s-1JSON\s0 result
 467 into \s-1UTF\-8\s0, as required by many protocols, while the decode method expects to be handled
 468 an UTF\-8\-encoded string. Please note that UTF\-8\-encoded strings do not contain any
 469 characters outside the range 0..255, they are thus useful for bytewise/binary I/O.
 470 .PP
 471 In future versions, enabling this option might enable autodetection of the \s-1UTF\-16\s0 and \s-1UTF\-32\s0
 472 encoding families, as described in \s-1RFC4627\s0.
 473 .PP
 474 If \f(CW$enable\fR is false, then the encode method will return the \s-1JSON\s0 string as a (non\-encoded)
 475 Unicode string, while decode expects thus a Unicode string. Any decoding or encoding
 476 (e.g. to \s-1UTF\-8\s0 or \s-1UTF\-16\s0) needs to be done yourself, e.g. using the Encode module.
 477 .PP
 478 Example, output UTF\-16BE\-encoded \s-1JSON:\s0
 479 .PP
 480 .Vb 2
 481 \&  use Encode;
 482 \&  $jsontext = encode "UTF\-16BE", JSON::XS\->new\->encode ($object);
 483 .Ve
 484 .PP
 485 Example, decode UTF\-32LE\-encoded \s-1JSON:\s0
 486 .PP
 487 .Vb 2
 488 \&  use Encode;
 489 \&  $object = JSON::XS\->new\->decode (decode "UTF\-32LE", $jsontext);
 490 .Ve
 491 .PP
 492 See to \*(L"\s-1UNICODE\s0 \s-1HANDLING\s0 \s-1ON\s0 \s-1PERLS\s0\*(R" in \s-1JSON::PP\s0 if the backend is \s-1PP\s0.
 493 .Sh "pretty"
 494 .IX Subsection "pretty"
 495 .Vb 1
 496 \&    $json = $json\->pretty([$enable])
 497 .Ve
 498 .PP
 499 This enables (or disables) all of the \f(CW\*(C`indent\*(C'\fR, \f(CW\*(C`space_before\*(C'\fR and
 500 \&\f(CW\*(C`space_after\*(C'\fR (and in the future possibly more) flags in one call to
 501 generate the most readable (or most compact) form possible.
 502 .PP
 503 Equivalent to:
 504 .PP
 505 .Vb 1
 506 \&   $json\->indent\->space_before\->space_after
 507 .Ve
 508 .PP
 509 The indent space length is three and \s-1JSON::XS\s0 cannot change the indent
 510 space length.
 511 .Sh "indent"
 512 .IX Subsection "indent"
 513 .Vb 1
 514 \&    $json = $json\->indent([$enable])
 515 .Ve
 516 .PP
 517 .Vb 1
 518 \&    $enabled = $json\->get_indent
 519 .Ve
 520 .PP
 521 If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will use a multiline
 522 format as output, putting every array member or object/hash key-value pair
 523 into its own line, identing them properly.
 524 .PP
 525 If \f(CW$enable\fR is false, no newlines or indenting will be produced, and the
 526 resulting \s-1JSON\s0 text is guarenteed not to contain any \f(CW\*(C`newlines\*(C'\fR.
 527 .PP
 528 This setting has no effect when decoding \s-1JSON\s0 texts.
 529 .PP
 530 The indent space length is three.
 531 With \s-1JSON::PP\s0, you can also access \f(CW\*(C`indent_length\*(C'\fR to change indent space length.
 532 .Sh "space_before"
 533 .IX Subsection "space_before"
 534 .Vb 1
 535 \&    $json = $json\->space_before([$enable])
 536 .Ve
 537 .PP
 538 .Vb 1
 539 \&    $enabled = $json\->get_space_before
 540 .Ve
 541 .PP
 542 If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will add an extra
 543 optional space before the \f(CW\*(C`:\*(C'\fR separating keys from values in \s-1JSON\s0 objects.
 544 .PP
 545 If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will not add any extra
 546 space at those places.
 547 .PP
 548 This setting has no effect when decoding \s-1JSON\s0 texts.
 549 .PP
 550 Example, space_before enabled, space_after and indent disabled:
 551 .PP
 552 .Vb 1
 553 \&   {"key" :"value"}
 554 .Ve
 555 .Sh "space_after"
 556 .IX Subsection "space_after"
 557 .Vb 1
 558 \&    $json = $json\->space_after([$enable])
 559 .Ve
 560 .PP
 561 .Vb 1
 562 \&    $enabled = $json\->get_space_after
 563 .Ve
 564 .PP
 565 If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will add an extra
 566 optional space after the \f(CW\*(C`:\*(C'\fR separating keys from values in \s-1JSON\s0 objects
 567 and extra whitespace after the \f(CW\*(C`,\*(C'\fR separating key-value pairs and array
 568 members.
 569 .PP
 570 If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will not add any extra
 571 space at those places.
 572 .PP
 573 This setting has no effect when decoding \s-1JSON\s0 texts.
 574 .PP
 575 Example, space_before and indent disabled, space_after enabled:
 576 .PP
 577 .Vb 1
 578 \&   {"key": "value"}
 579 .Ve
 580 .Sh "relaxed"
 581 .IX Subsection "relaxed"
 582 .Vb 1
 583 \&    $json = $json\->relaxed([$enable])
 584 .Ve
 585 .PP
 586 .Vb 1
 587 \&    $enabled = $json\->get_relaxed
 588 .Ve
 589 .PP
 590 If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`decode\*(C'\fR will accept some
 591 extensions to normal \s-1JSON\s0 syntax (see below). \f(CW\*(C`encode\*(C'\fR will not be
 592 affected in anyway. \fIBe aware that this option makes you accept invalid
 593 \&\s-1JSON\s0 texts as if they were valid!\fR. I suggest only to use this option to
 594 parse application-specific files written by humans (configuration files,
 595 resource files etc.)
 596 .PP
 597 If \f(CW$enable\fR is false (the default), then \f(CW\*(C`decode\*(C'\fR will only accept
 598 valid \s-1JSON\s0 texts.
 599 .PP
 600 Currently accepted extensions are:
 601 .IP "* list items can have an end-comma" 4
 602 .IX Item "list items can have an end-comma"
 603 \&\s-1JSON\s0 \fIseparates\fR array elements and key-value pairs with commas. This
 604 can be annoying if you write \s-1JSON\s0 texts manually and want to be able to
 605 quickly append elements, so this extension accepts comma at the end of
 606 such items not just between them:
 607 .Sp
 608 .Vb 8
 609 \&   [
 610 \&      1,
 611 \&      2, <\- this comma not normally allowed
 612 \&   ]
 613 \&   {
 614 \&      "k1": "v1",
 615 \&      "k2": "v2", <\- this comma not normally allowed
 616 \&   }
 617 .Ve
 618 .IP "* shell-style '#'\-comments" 4
 619 .IX Item "shell-style '#'-comments"
 620 Whenever \s-1JSON\s0 allows whitespace, shell-style comments are additionally
 621 allowed. They are terminated by the first carriage-return or line-feed
 622 character, after which more white-space and comments are allowed.
 623 .Sp
 624 .Vb 4
 625 \&  [
 626 \&     1, # this comment not allowed in JSON
 627 \&        # neither this one...
 628 \&  ]
 629 .Ve
 630 .Sh "canonical"
 631 .IX Subsection "canonical"
 632 .Vb 1
 633 \&    $json = $json\->canonical([$enable])
 634 .Ve
 635 .PP
 636 .Vb 1
 637 \&    $enabled = $json\->get_canonical
 638 .Ve
 639 .PP
 640 If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will output \s-1JSON\s0 objects
 641 by sorting their keys. This is adding a comparatively high overhead.
 642 .PP
 643 If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will output key-value
 644 pairs in the order Perl stores them (which will likely change between runs
 645 of the same script).
 646 .PP
 647 This option is useful if you want the same data structure to be encoded as
 648 the same \s-1JSON\s0 text (given the same overall settings). If it is disabled,
 649 the same hash might be encoded differently even if contains the same data,
 650 as key-value pairs have no inherent ordering in Perl.
 651 .PP
 652 This setting has no effect when decoding \s-1JSON\s0 texts.
 653 .Sh "allow_nonref"
 654 .IX Subsection "allow_nonref"
 655 .Vb 1
 656 \&    $json = $json\->allow_nonref([$enable])
 657 .Ve
 658 .PP
 659 .Vb 1
 660 \&    $enabled = $json\->get_allow_nonref
 661 .Ve
 662 .PP
 663 If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method can convert a
 664 non-reference into its corresponding string, number or null \s-1JSON\s0 value,
 665 which is an extension to \s-1RFC4627\s0. Likewise, \f(CW\*(C`decode\*(C'\fR will accept those \s-1JSON\s0
 666 values instead of croaking.
 667 .PP
 668 If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will croak if it isn't
 669 passed an arrayref or hashref, as \s-1JSON\s0 texts must either be an object
 670 or array. Likewise, \f(CW\*(C`decode\*(C'\fR will croak if given something that is not a
 671 \&\s-1JSON\s0 object or array.
 672 .PP
 673 .Vb 2
 674 \&   JSON\->new\->allow_nonref\->encode ("Hello, World!")
 675 \&   => "Hello, World!"
 676 .Ve
 677 .Sh "allow_unknown"
 678 .IX Subsection "allow_unknown"
 679 .Vb 1
 680 \&    $json = $json\->allow_unknown ([$enable])
 681 .Ve
 682 .PP
 683 .Vb 1
 684 \&    $enabled = $json\->get_allow_unknown
 685 .Ve
 686 .PP
 687 If \f(CW$enable\fR is true (or missing), then \*(L"encode\*(R" will *not* throw an
 688 exception when it encounters values it cannot represent in \s-1JSON\s0 (for
 689 example, filehandles) but instead will encode a \s-1JSON\s0 \*(L"null\*(R" value.
 690 Note that blessed objects are not included here and are handled
 691 separately by c<allow_nonref>.
 692 .PP
 693 If \f(CW$enable\fR is false (the default), then \*(L"encode\*(R" will throw an
 694 exception when it encounters anything it cannot encode as \s-1JSON\s0.
 695 .PP
 696 This option does not affect \*(L"decode\*(R" in any way, and it is
 697 recommended to leave it off unless you know your communications
 698 partner.
 699 .Sh "allow_blessed"
 700 .IX Subsection "allow_blessed"
 701 .Vb 1
 702 \&    $json = $json\->allow_blessed([$enable])
 703 .Ve
 704 .PP
 705 .Vb 1
 706 \&    $enabled = $json\->get_allow_blessed
 707 .Ve
 708 .PP
 709 If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will not
 710 barf when it encounters a blessed reference. Instead, the value of the
 711 \&\fBconvert_blessed\fR option will decide whether \f(CW\*(C`null\*(C'\fR (\f(CW\*(C`convert_blessed\*(C'\fR
 712 disabled or no \f(CW\*(C`TO_JSON\*(C'\fR method found) or a representation of the
 713 object (\f(CW\*(C`convert_blessed\*(C'\fR enabled and \f(CW\*(C`TO_JSON\*(C'\fR method found) is being
 714 encoded. Has no effect on \f(CW\*(C`decode\*(C'\fR.
 715 .PP
 716 If \f(CW$enable\fR is false (the default), then \f(CW\*(C`encode\*(C'\fR will throw an
 717 exception when it encounters a blessed object.
 718 .Sh "convert_blessed"
 719 .IX Subsection "convert_blessed"
 720 .Vb 1
 721 \&    $json = $json\->convert_blessed([$enable])
 722 .Ve
 723 .PP
 724 .Vb 1
 725 \&    $enabled = $json\->get_convert_blessed
 726 .Ve
 727 .PP
 728 If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`encode\*(C'\fR, upon encountering a
 729 blessed object, will check for the availability of the \f(CW\*(C`TO_JSON\*(C'\fR method
 730 on the object's class. If found, it will be called in scalar context
 731 and the resulting scalar will be encoded instead of the object. If no
 732 \&\f(CW\*(C`TO_JSON\*(C'\fR method is found, the value of \f(CW\*(C`allow_blessed\*(C'\fR will decide what
 733 to do.
 734 .PP
 735 The \f(CW\*(C`TO_JSON\*(C'\fR method may safely call die if it wants. If \f(CW\*(C`TO_JSON\*(C'\fR
 736 returns other blessed objects, those will be handled in the same
 737 way. \f(CW\*(C`TO_JSON\*(C'\fR must take care of not causing an endless recursion cycle
 738 (== crash) in this case. The name of \f(CW\*(C`TO_JSON\*(C'\fR was chosen because other
 739 methods called by the Perl core (== not by the user of the object) are
 740 usually in upper case letters and to avoid collisions with the \f(CW\*(C`to_json\*(C'\fR
 741 function or method.
 742 .PP
 743 This setting does not yet influence \f(CW\*(C`decode\*(C'\fR in any way.
 744 .PP
 745 If \f(CW$enable\fR is false, then the \f(CW\*(C`allow_blessed\*(C'\fR setting will decide what
 746 to do when a blessed object is found.
 747 .IP "convert_blessed_universally mode" 4
 748 .IX Item "convert_blessed_universally mode"
 749 If use \f(CW\*(C`JSON\*(C'\fR with \f(CW\*(C`\-convert_blessed_universally\*(C'\fR, the \f(CW\*(C`UNIVERSAL::TO_JSON\*(C'\fR
 750 subroutine is defined as the below code:
 751 .Sp
 752 .Vb 7
 753 \&   *UNIVERSAL::TO_JSON = sub {
 754 \&       my $b_obj = B::svref_2object( $_[0] );
 755 \&       return    $b_obj\->isa('B::HV') ? { %{ $_[0] } }
 756 \&               : $b_obj\->isa('B::AV') ? [ @{ $_[0] } ]
 757 \&               : undef
 758 \&               ;
 759 \&   }
 760 .Ve
 761 .Sp
 762 This will cause that \f(CW\*(C`encode\*(C'\fR method converts simple blessed objects into
 763 \&\s-1JSON\s0 objects as non-blessed object.
 764 .Sp
 765 .Vb 2
 766 \&   JSON \-convert_blessed_universally;
 767 \&   $json\->allow_blessed\->convert_blessed\->encode( $blessed_object )
 768 .Ve
 769 .Sp
 770 This feature is experimental and may be removed in the future.
 771 .Sh "filter_json_object"
 772 .IX Subsection "filter_json_object"
 773 .Vb 1
 774 \&    $json = $json\->filter_json_object([$coderef])
 775 .Ve
 776 .PP
 777 When \f(CW$coderef\fR is specified, it will be called from \f(CW\*(C`decode\*(C'\fR each
 778 time it decodes a \s-1JSON\s0 object. The only argument passed to the coderef
 779 is a reference to the newly-created hash. If the code references returns
 780 a single scalar (which need not be a reference), this value
 781 (i.e. a copy of that scalar to avoid aliasing) is inserted into the
 782 deserialised data structure. If it returns an empty list
 783 (\s-1NOTE:\s0 \fInot\fR \f(CW\*(C`undef\*(C'\fR, which is a valid scalar), the original deserialised
 784 hash will be inserted. This setting can slow down decoding considerably.
 785 .PP
 786 When \f(CW$coderef\fR is omitted or undefined, any existing callback will
 787 be removed and \f(CW\*(C`decode\*(C'\fR will not change the deserialised hash in any
 788 way.
 789 .PP
 790 Example, convert all \s-1JSON\s0 objects into the integer 5:
 791 .PP
 792 .Vb 6
 793 \&   my $js = JSON\->new\->filter_json_object (sub { 5 });
 794 \&   # returns [5]
 795 \&   $js\->decode ('[{}]'); # the given subroutine takes a hash reference.
 796 \&   # throw an exception because allow_nonref is not enabled
 797 \&   # so a lone 5 is not allowed.
 798 \&   $js\->decode ('{"a":1, "b":2}');
 799 .Ve
 800 .Sh "filter_json_single_key_object"
 801 .IX Subsection "filter_json_single_key_object"
 802 .Vb 1
 803 \&    $json = $json\->filter_json_single_key_object($key [=> $coderef])
 804 .Ve
 805 .PP
 806 Works remotely similar to \f(CW\*(C`filter_json_object\*(C'\fR, but is only called for
 807 \&\s-1JSON\s0 objects having a single key named \f(CW$key\fR.
 808 .PP
 809 This \f(CW$coderef\fR is called before the one specified via
 810 \&\f(CW\*(C`filter_json_object\*(C'\fR, if any. It gets passed the single value in the \s-1JSON\s0
 811 object. If it returns a single value, it will be inserted into the data
 812 structure. If it returns nothing (not even \f(CW\*(C`undef\*(C'\fR but the empty list),
 813 the callback from \f(CW\*(C`filter_json_object\*(C'\fR will be called next, as if no
 814 single-key callback were specified.
 815 .PP
 816 If \f(CW$coderef\fR is omitted or undefined, the corresponding callback will be
 817 disabled. There can only ever be one callback for a given key.
 818 .PP
 819 As this callback gets called less often then the \f(CW\*(C`filter_json_object\*(C'\fR
 820 one, decoding speed will not usually suffer as much. Therefore, single-key
 821 objects make excellent targets to serialise Perl objects into, especially
 822 as single-key \s-1JSON\s0 objects are as close to the type-tagged value concept
 823 as \s-1JSON\s0 gets (it's basically an \s-1ID/VALUE\s0 tuple). Of course, \s-1JSON\s0 does not
 824 support this in any way, so you need to make sure your data never looks
 825 like a serialised Perl hash.
 826 .PP
 827 Typical names for the single object key are \f(CW\*(C`_\|_class_whatever_\|_\*(C'\fR, or
 828 \&\f(CW\*(C`$_\|_dollars_are_rarely_used_\|_$\*(C'\fR or \f(CW\*(C`}ugly_brace_placement\*(C'\fR, or even
 829 things like \f(CW\*(C`_\|_class_md5sum(classname)_\|_\*(C'\fR, to reduce the risk of clashing
 830 with real hashes.
 831 .PP
 832 Example, decode \s-1JSON\s0 objects of the form \f(CW\*(C`{ "_\|_widget_\|_" => <id> }\*(C'\fR
 833 into the corresponding \f(CW$WIDGET{<id>}\fR object:
 834 .PP
 835 .Vb 7
 836 \&   # return whatever is in $WIDGET{5}:
 837 \&   JSON
 838 \&      \->new
 839 \&      \->filter_json_single_key_object (__widget__ => sub {
 840 \&            $WIDGET{ $_[0] }
 841 \&         })
 842 \&      \->decode ('{"__widget__": 5')
 843 .Ve
 844 .PP
 845 .Vb 4
 846 \&   # this can be used with a TO_JSON method in some "widget" class
 847 \&   # for serialisation to json:
 848 \&   sub WidgetBase::TO_JSON {
 849 \&      my ($self) = @_;
 850 .Ve
 851 .PP
 852 .Vb 4
 853 \&      unless ($self\->{id}) {
 854 \&         $self\->{id} = ..get..some..id..;
 855 \&         $WIDGET{$self\->{id}} = $self;
 856 \&      }
 857 .Ve
 858 .PP
 859 .Vb 2
 860 \&      { __widget__ => $self\->{id} }
 861 \&   }
 862 .Ve
 863 .Sh "shrink"
 864 .IX Subsection "shrink"
 865 .Vb 1
 866 \&    $json = $json\->shrink([$enable])
 867 .Ve
 868 .PP
 869 .Vb 1
 870 \&    $enabled = $json\->get_shrink
 871 .Ve
 872 .PP
 873 With \s-1JSON::XS\s0, this flag resizes strings generated by either
 874 \&\f(CW\*(C`encode\*(C'\fR or \f(CW\*(C`decode\*(C'\fR to their minimum size possible. This can save
 875 memory when your \s-1JSON\s0 texts are either very very long or you have many
 876 short strings. It will also try to downgrade any strings to octet-form
 877 if possible: perl stores strings internally either in an encoding called
 878 UTF-X or in octet\-form. The latter cannot store everything but uses less
 879 space in general (and some buggy Perl or C code might even rely on that
 880 internal representation being used).
 881 .PP
 882 With \s-1JSON::PP\s0, it is noop about resizing strings but tries
 883 \&\f(CW\*(C`utf8::downgrade\*(C'\fR to the returned string by \f(CW\*(C`encode\*(C'\fR. See to utf8.
 884 .PP
 885 See to \*(L"\s-1OBJECT\-ORIENTED\s0 \s-1INTERFACE\s0\*(R" in \s-1JSON::XS\s0 and \*(L"\s-1METHODS\s0\*(R" in \s-1JSON::PP\s0.
 886 .Sh "max_depth"
 887 .IX Subsection "max_depth"
 888 .Vb 1
 889 \&    $json = $json\->max_depth([$maximum_nesting_depth])
 890 .Ve
 891 .PP
 892 .Vb 1
 893 \&    $max_depth = $json\->get_max_depth
 894 .Ve
 895 .PP
 896 Sets the maximum nesting level (default \f(CW512\fR) accepted while encoding
 897 or decoding. If a higher nesting level is detected in \s-1JSON\s0 text or a Perl
 898 data structure, then the encoder and decoder will stop and croak at that
 899 point.
 900 .PP
 901 Nesting level is defined by number of hash\- or arrayrefs that the encoder
 902 needs to traverse to reach a given point or the number of \f(CW\*(C`{\*(C'\fR or \f(CW\*(C`[\*(C'\fR
 903 characters without their matching closing parenthesis crossed to reach a
 904 given character in a string.
 905 .PP
 906 If no argument is given, the highest possible setting will be used, which
 907 is rarely useful.
 908 .PP
 909 Note that nesting is implemented by recursion in C. The default value has
 910 been chosen to be as large as typical operating systems allow without
 911 crashing. (\s-1JSON::XS\s0)
 912 .PP
 913 With \s-1JSON::PP\s0 as the backend, when a large value (100 or more) was set and
 914 it de/encodes a deep nested object/text, it may raise a warning
 915 \&'Deep recursion on subroutin' at the perl runtime phase.
 916 .PP
 917 See \*(L"\s-1SECURITY\s0 \s-1CONSIDERATIONS\s0\*(R" in \s-1JSON::XS\s0 for more info on why this is useful.
 918 .Sh "max_size"
 919 .IX Subsection "max_size"
 920 .Vb 1
 921 \&    $json = $json\->max_size([$maximum_string_size])
 922 .Ve
 923 .PP
 924 .Vb 1
 925 \&    $max_size = $json\->get_max_size
 926 .Ve
 927 .PP
 928 Set the maximum length a \s-1JSON\s0 text may have (in bytes) where decoding is
 929 being attempted. The default is \f(CW0\fR, meaning no limit. When \f(CW\*(C`decode\*(C'\fR
 930 is called on a string that is longer then this many bytes, it will not
 931 attempt to decode the string but throw an exception. This setting has no
 932 effect on \f(CW\*(C`encode\*(C'\fR (yet).
 933 .PP
 934 If no argument is given, the limit check will be deactivated (same as when
 935 \&\f(CW0\fR is specified).
 936 .PP
 937 See \*(L"\s-1SECURITY\s0 \s-1CONSIDERATIONS\s0\*(R" in \s-1JSON::XS\s0, below, for more info on why this is useful.
 938 .Sh "encode"
 939 .IX Subsection "encode"
 940 .Vb 1
 941 \&    $json_text = $json\->encode($perl_scalar)
 942 .Ve
 943 .PP
 944 Converts the given Perl data structure (a simple scalar or a reference
 945 to a hash or array) to its \s-1JSON\s0 representation. Simple scalars will be
 946 converted into \s-1JSON\s0 string or number sequences, while references to arrays
 947 become \s-1JSON\s0 arrays and references to hashes become \s-1JSON\s0 objects. Undefined
 948 Perl values (e.g. \f(CW\*(C`undef\*(C'\fR) become \s-1JSON\s0 \f(CW\*(C`null\*(C'\fR values.
 949 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.
 950 .Sh "decode"
 951 .IX Subsection "decode"
 952 .Vb 1
 953 \&    $perl_scalar = $json\->decode($json_text)
 954 .Ve
 955 .PP
 956 The opposite of \f(CW\*(C`encode\*(C'\fR: expects a \s-1JSON\s0 text and tries to parse it,
 957 returning the resulting simple scalar or reference. Croaks on error.
 958 .PP
 959 \&\s-1JSON\s0 numbers and strings become simple Perl scalars. \s-1JSON\s0 arrays become
 960 Perl arrayrefs and \s-1JSON\s0 objects become Perl hashrefs. \f(CW\*(C`true\*(C'\fR becomes
 961 \&\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
 962 \&\f(CW\*(C`null\*(C'\fR becomes \f(CW\*(C`undef\*(C'\fR.
 963 .Sh "decode_prefix"
 964 .IX Subsection "decode_prefix"
 965 .Vb 1
 966 \&    ($perl_scalar, $characters) = $json\->decode_prefix($json_text)
 967 .Ve
 968 .PP
 969 This works like the \f(CW\*(C`decode\*(C'\fR method, but instead of raising an exception
 970 when there is trailing garbage after the first \s-1JSON\s0 object, it will
 971 silently stop parsing there and return the number of characters consumed
 972 so far.
 973 .PP
 974 .Vb 2
 975 \&   JSON\->new\->decode_prefix ("[1] the tail")
 976 \&   => ([], 3)
 977 .Ve
 978 .PP
 979 See to \*(L"\s-1OBJECT\-ORIENTED\s0 \s-1INTERFACE\s0\*(R" in \s-1JSON::XS\s0
 980 .Sh "property"
 981 .IX Subsection "property"
 982 .Vb 1
 983 \&    $boolean = $json\->property($property_name)
 984 .Ve
 985 .PP
 986 Returns a boolean value about above some properties.
 987 .PP
 988 The available properties are \f(CW\*(C`ascii\*(C'\fR, \f(CW\*(C`latin1\*(C'\fR, \f(CW\*(C`utf8\*(C'\fR,
 989 \&\f(CW\*(C`indent\*(C'\fR,\f(CW\*(C`space_before\*(C'\fR, \f(CW\*(C`space_after\*(C'\fR, \f(CW\*(C`relaxed\*(C'\fR, \f(CW\*(C`canonical\*(C'\fR,
 990 \&\f(CW\*(C`allow_nonref\*(C'\fR, \f(CW\*(C`allow_unknown\*(C'\fR, \f(CW\*(C`allow_blessed\*(C'\fR, \f(CW\*(C`convert_blessed\*(C'\fR,
 991 \&\f(CW\*(C`shrink\*(C'\fR, \f(CW\*(C`max_depth\*(C'\fR and \f(CW\*(C`max_size\*(C'\fR.
 992 .PP
 993 .Vb 5
 994 \&   $boolean = $json\->property('utf8');
 995 \&    => 0
 996 \&   $json\->utf8;
 997 \&   $boolean = $json\->property('utf8');
 998 \&    => 1
 999 .Ve
1000 .PP
1001 Sets the propery with a given boolean value.
1002 .PP
1003 .Vb 1
1004 \&    $json = $json\->property($property_name => $boolean);
1005 .Ve
1006 .PP
1007 With no argumnt, it returns all the above properties as a hash reference.
1008 .PP
1009 .Vb 1
1010 \&    $flag_hashref = $json\->property();
1011 .Ve
1012 .SH "INCREMENTAL PARSING"
1013 .IX Header "INCREMENTAL PARSING"
1014 In \s-1JSON::XS\s0 2.2, incremental parsing feature of \s-1JSON\s0 texts was implemented.
1015 Please check to \*(L"\s-1INCREMENTAL\s0 \s-1PARSING\s0\*(R" in \s-1JSON::XS\s0.
1016 .ie n .IP "[void, scalar or list context] = $json\->incr_parse ([$string])" 4
1017 .el .IP "[void, scalar or list context] = \f(CW$json\fR\->incr_parse ([$string])" 4
1018 .IX Item "[void, scalar or list context] = $json->incr_parse ([$string])"
1019 This is the central parsing function. It can both append new text and
1020 extract objects from the stream accumulated so far (both of these
1021 functions are optional).
1022 .Sp
1023 If \f(CW$string\fR is given, then this string is appended to the already
1024 existing \s-1JSON\s0 fragment stored in the \f(CW$json\fR object.
1025 .Sp
1026 After that, if the function is called in void context, it will simply
1027 return without doing anything further. This can be used to add more text
1028 in as many chunks as you want.
1029 .Sp
1030 If the method is called in scalar context, then it will try to extract
1031 exactly \fIone\fR \s-1JSON\s0 object. If that is successful, it will return this
1032 object, otherwise it will return \f(CW\*(C`undef\*(C'\fR. If there is a parse error,
1033 this method will croak just as \f(CW\*(C`decode\*(C'\fR would do (one can then use
1034 \&\f(CW\*(C`incr_skip\*(C'\fR to skip the errornous part). This is the most common way of
1035 using the method.
1036 .Sp
1037 And finally, in list context, it will try to extract as many objects
1038 from the stream as it can find and return them, or the empty list
1039 otherwise. For this to work, there must be no separators between the \s-1JSON\s0
1040 objects or arrays, instead they must be concatenated back\-to\-back. If
1041 an error occurs, an exception will be raised as in the scalar context
1042 case. Note that in this case, any previously-parsed \s-1JSON\s0 texts will be
1043 lost.
1044 .ie n .IP "$lvalue_string = $json\->incr_text" 4
1045 .el .IP "$lvalue_string = \f(CW$json\fR\->incr_text" 4
1046 .IX Item "$lvalue_string = $json->incr_text"
1047 This method returns the currently stored \s-1JSON\s0 fragment as an lvalue, that
1048 is, you can manipulate it. This \fIonly\fR works when a preceding call to
1049 \&\f(CW\*(C`incr_parse\*(C'\fR in \fIscalar context\fR successfully returned an object. Under
1050 all other circumstances you must not call this function (I mean it.
1051 although in simple tests it might actually work, it \fIwill\fR fail under
1052 real world conditions). As a special exception, you can also call this
1053 method before having parsed anything.
1054 .Sp
1055 This function is useful in two cases: a) finding the trailing text after a
1056 \&\s-1JSON\s0 object or b) parsing multiple \s-1JSON\s0 objects separated by non-JSON text
1057 (such as commas).
1058 .Sp
1059 In Perl 5.005, \f(CW\*(C`lvalue\*(C'\fR attribute is not available.
1060 You must write codes like the below:
1061 .Sp
1062 .Vb 3
1063 \&    $string = $json\->incr_text;
1064 \&    $string =~ s/\es*,\es*//;
1065 \&    $json\->incr_text( $string );
1066 .Ve
1067 .IP "$json\->incr_skip" 4
1068 .IX Item "$json->incr_skip"
1069 This will reset the state of the incremental parser and will remove the
1070 parsed text from the input buffer. This is useful after \f(CW\*(C`incr_parse\*(C'\fR
1071 died, in which case the input buffer and incremental parser state is left
1072 unchanged, to skip the text parsed so far and to reset the parse state.
1073 .IP "$json\->incr_reset" 4
1074 .IX Item "$json->incr_reset"
1075 This completely resets the incremental parser, that is, after this call,
1076 it will be as if the parser had never parsed anything.
1077 .Sp
1078 This is useful if you want ot repeatedly parse \s-1JSON\s0 objects and want to
1079 ignore any trailing data, which means you have to reset the parser after
1080 each successful decode.
1081 .SH "JSON::PP SUPPORT METHODS"
1082 .IX Header "JSON::PP SUPPORT METHODS"
1083 The below methods are \s-1JSON::PP\s0 own methods, so when \f(CW\*(C`JSON\*(C'\fR works
1084 with \s-1JSON::PP\s0 (i.e. the created object is a \s-1JSON::PP\s0 object), available.
1085 See to \*(L"\s-1JSON::PP\s0 \s-1OWN\s0 \s-1METHODS\s0\*(R" in \s-1JSON::PP\s0 in detail.
1086 .PP
1087 If you use \f(CW\*(C`JSON\*(C'\fR with additonal \f(CW\*(C`\-support_by_pp\*(C'\fR, some methods
1088 are available even with \s-1JSON::XS\s0. See to \*(L"\s-1USE\s0 \s-1PP\s0 \s-1FEATURES\s0 \s-1EVEN\s0 \s-1THOUGH\s0 \s-1XS\s0 \s-1BACKEND\s0\*(R".
1089 .PP
1090 .Vb 1
1091 \&   BEING { $ENV{PERL_JSON_BACKEND} = 'JSON::XS' }
1092 .Ve
1093 .PP
1094 .Vb 1
1095 \&   use JSON \-support_by_pp;
1096 .Ve
1097 .PP
1098 .Vb 2
1099 \&   my $json = new JSON;
1100 \&   $json\->allow_nonref\->escape_slash\->encode("/");
1101 .Ve
1102 .PP
1103 .Vb 3
1104 \&   # functional interfaces too.
1105 \&   print to_json(["/"], {escape_slash => 1});
1106 \&   print from_json('["foo"]', {utf8 => 1});
1107 .Ve
1108 .PP
1109 If you do not want to all functions but \f(CW\*(C`\-support_by_pp\*(C'\fR,
1110 use \f(CW\*(C`\-no_export\*(C'\fR.
1111 .PP
1112 .Vb 2
1113 \&   use JSON \-support_by_pp, \-no_export;
1114 \&   # functional interfaces are not exported.
1115 .Ve
1116 .Sh "allow_singlequote"
1117 .IX Subsection "allow_singlequote"
1118 .Vb 1
1119 \&    $json = $json\->allow_singlequote([$enable])
1120 .Ve
1121 .PP
1122 If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`decode\*(C'\fR will accept
1123 any \s-1JSON\s0 strings quoted by single quotations that are invalid \s-1JSON\s0
1124 format.
1125 .PP
1126 .Vb 3
1127 \&    $json\->allow_singlequote\->decode({"foo":'bar'});
1128 \&    $json\->allow_singlequote\->decode({'foo':"bar"});
1129 \&    $json\->allow_singlequote\->decode({'foo':'bar'});
1130 .Ve
1131 .PP
1132 As same as the \f(CW\*(C`relaxed\*(C'\fR option, this option may be used to parse
1133 application-specific files written by humans.
1134 .Sh "allow_barekey"
1135 .IX Subsection "allow_barekey"
1136 .Vb 1
1137 \&    $json = $json\->allow_barekey([$enable])
1138 .Ve
1139 .PP
1140 If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`decode\*(C'\fR will accept
1141 bare keys of \s-1JSON\s0 object that are invalid \s-1JSON\s0 format.
1142 .PP
1143 As same as the \f(CW\*(C`relaxed\*(C'\fR option, this option may be used to parse
1144 application-specific files written by humans.
1145 .PP
1146 .Vb 1
1147 \&    $json\->allow_barekey\->decode('{foo:"bar"}');
1148 .Ve
1149 .Sh "allow_bignum"
1150 .IX Subsection "allow_bignum"
1151 .Vb 1
1152 \&    $json = $json\->allow_bignum([$enable])
1153 .Ve
1154 .PP
1155 If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`decode\*(C'\fR will convert
1156 the big integer Perl cannot handle as integer into a Math::BigInt
1157 object and convert a floating number (any) into a Math::BigFloat.
1158 .PP
1159 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
1160 objects into \s-1JSON\s0 numbers with \f(CW\*(C`allow_blessed\*(C'\fR enable.
1161 .PP
1162 .Vb 4
1163 \&   $json\->allow_nonref\->allow_blessed\->allow_bignum;
1164 \&   $bigfloat = $json\->decode('2.000000000000000000000000001');
1165 \&   print $json\->encode($bigfloat);
1166 \&   # => 2.000000000000000000000000001
1167 .Ve
1168 .PP
1169 See to \s-1MAPPING\s0 aboout the conversion of \s-1JSON\s0 number.
1170 .Sh "loose"
1171 .IX Subsection "loose"
1172 .Vb 1
1173 \&    $json = $json\->loose([$enable])
1174 .Ve
1175 .PP
1176 The unescaped [\ex00\-\ex1f\ex22\ex2f\ex5c] strings are invalid in \s-1JSON\s0 strings
1177 and the module doesn't allow to \f(CW\*(C`decode\*(C'\fR to these (except for \ex2f).
1178 If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`decode\*(C'\fR  will accept these
1179 unescaped strings.
1180 .PP
1181 .Vb 2
1182 \&    $json\->loose\->decode(qq|["abc
1183 \&                                   def"]|);
1184 .Ve
1185 .PP
1186 See to \*(L"\s-1JSON::PP\s0 \s-1OWN\s0 \s-1METHODS\s0\*(R" in \s-1JSON::PP\s0.
1187 .Sh "escape_slash"
1188 .IX Subsection "escape_slash"
1189 .Vb 1
1190 \&    $json = $json\->escape_slash([$enable])
1191 .Ve
1192 .PP
1193 According to \s-1JSON\s0 Grammar, \fIslash\fR (U+002F) is escaped. But by default
1194 \&\s-1JSON\s0 backend modules encode strings without escaping slash.
1195 .PP
1196 If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`encode\*(C'\fR will escape slashes.
1197 .Sh "indent_length"
1198 .IX Subsection "indent_length"
1199 .Vb 1
1200 \&    $json = $json\->indent_length($length)
1201 .Ve
1202 .PP
1203 With \s-1JSON::XS\s0, The indent space length is 3 and cannot be changed.
1204 With \s-1JSON::PP\s0, it sets the indent space length with the given \f(CW$length\fR.
1205 The default is 3. The acceptable range is 0 to 15.
1206 .Sh "sort_by"
1207 .IX Subsection "sort_by"
1208 .Vb 2
1209 \&    $json = $json\->sort_by($function_name)
1210 \&    $json = $json\->sort_by($subroutine_ref)
1211 .Ve
1212 .PP
1213 If \f(CW$function_name\fR or \f(CW$subroutine_ref\fR are set, its sort routine are used.
1214 .PP
1215 .Vb 2
1216 \&   $js = $pc\->sort_by(sub { $JSON::PP::a cmp $JSON::PP::b })\->encode($obj);
1217 \&   # is($js, q|{"a":1,"b":2,"c":3,"d":4,"e":5,"f":6,"g":7,"h":8,"i":9}|);
1218 .Ve
1219 .PP
1220 .Vb 2
1221 \&   $js = $pc\->sort_by('own_sort')\->encode($obj);
1222 \&   # is($js, q|{"a":1,"b":2,"c":3,"d":4,"e":5,"f":6,"g":7,"h":8,"i":9}|);
1223 .Ve
1224 .PP
1225 .Vb 1
1226 \&   sub JSON::PP::own_sort { $JSON::PP::a cmp $JSON::PP::b }
1227 .Ve
1228 .PP
1229 As the sorting routine runs in the \s-1JSON::PP\s0 scope, the given
1230 subroutine name and the special variables \f(CW$a\fR, \f(CW$b\fR will begin
1231 with '\s-1JSON::PP::\s0'.
1232 .PP
1233 If \f(CW$integer\fR is set, then the effect is same as \f(CW\*(C`canonical\*(C'\fR on.
1234 .PP
1235 See to \*(L"\s-1JSON::PP\s0 \s-1OWN\s0 \s-1METHODS\s0\*(R" in \s-1JSON::PP\s0.
1236 .SH "MAPPING"
1237 .IX Header "MAPPING"
1238 This section is copied from \s-1JSON::XS\s0 and modified to \f(CW\*(C`JSON\*(C'\fR.
1239 \&\s-1JSON::XS\s0 and \s-1JSON::PP\s0 mapping mechanisms are almost equivalent.
1240 .PP
1241 See to \*(L"\s-1MAPPING\s0\*(R" in \s-1JSON::XS\s0.
1242 .Sh "\s-1JSON\s0 \-> \s-1PERL\s0"
1243 .IX Subsection "JSON -> PERL"
1244 .IP "object" 4
1245 .IX Item "object"
1246 A \s-1JSON\s0 object becomes a reference to a hash in Perl. No ordering of object
1247 keys is preserved (\s-1JSON\s0 does not preserver object key ordering itself).
1248 .IP "array" 4
1249 .IX Item "array"
1250 A \s-1JSON\s0 array becomes a reference to an array in Perl.
1251 .IP "string" 4
1252 .IX Item "string"
1253 A \s-1JSON\s0 string becomes a string scalar in Perl \- Unicode codepoints in \s-1JSON\s0
1254 are represented by the same codepoints in the Perl string, so no manual
1255 decoding is necessary.
1256 .IP "number" 4
1257 .IX Item "number"
1258 A \s-1JSON\s0 number becomes either an integer, numeric (floating point) or
1259 string scalar in perl, depending on its range and any fractional parts. On
1260 the Perl level, there is no difference between those as Perl handles all
1261 the conversion details, but an integer may take slightly less memory and
1262 might represent more values exactly than floating point numbers.
1263 .Sp
1264 If the number consists of digits only, \f(CW\*(C`JSON\*(C'\fR will try to represent
1265 it as an integer value. If that fails, it will try to represent it as
1266 a numeric (floating point) value if that is possible without loss of
1267 precision. Otherwise it will preserve the number as a string value (in
1268 which case you lose roundtripping ability, as the \s-1JSON\s0 number will be
1269 re-encoded toa \s-1JSON\s0 string).
1270 .Sp
1271 Numbers containing a fractional or exponential part will always be
1272 represented as numeric (floating point) values, possibly at a loss of
1273 precision (in which case you might lose perfect roundtripping ability, but
1274 the \s-1JSON\s0 number will still be re-encoded as a \s-1JSON\s0 number).
1275 .Sp
1276 If the backend is \s-1JSON::PP\s0 and \f(CW\*(C`allow_bignum\*(C'\fR is enable, the big integers
1277 and the numeric can be optionally converted into Math::BigInt and
1278 Math::BigFloat objects.
1279 .IP "true, false" 4
1280 .IX Item "true, false"
1281 These \s-1JSON\s0 atoms become \f(CW\*(C`JSON::true\*(C'\fR and \f(CW\*(C`JSON::false\*(C'\fR,
1282 respectively. They are overloaded to act almost exactly like the numbers
1283 \&\f(CW1\fR and \f(CW0\fR. You can check wether a scalar is a \s-1JSON\s0 boolean by using
1284 the \f(CW\*(C`JSON::is_bool\*(C'\fR function.
1285 .Sp
1286 If \f(CW\*(C`JSON::true\*(C'\fR and \f(CW\*(C`JSON::false\*(C'\fR are used as strings or compared as strings,
1287 they represent as \f(CW\*(C`true\*(C'\fR and \f(CW\*(C`false\*(C'\fR respectively.
1288 .Sp
1289 .Vb 4
1290 \&   print JSON::true . "\en";
1291 \&    => true
1292 \&   print JSON::true + 1;
1293 \&    => 1
1294 .Ve
1295 .Sp
1296 .Vb 3
1297 \&   ok(JSON::true eq 'true');
1298 \&   ok(JSON::true eq  '1');
1299 \&   ok(JSON::true == 1);
1300 .Ve
1301 .Sp
1302 \&\f(CW\*(C`JSON\*(C'\fR will install these missing overloading features to the backend modules.
1303 .IP "null" 4
1304 .IX Item "null"
1305 A \s-1JSON\s0 null atom becomes \f(CW\*(C`undef\*(C'\fR in Perl.
1306 .Sp
1307 \&\f(CW\*(C`JSON::null\*(C'\fR returns \f(CW\*(C`unddef\*(C'\fR.
1308 .Sh "\s-1PERL\s0 \-> \s-1JSON\s0"
1309 .IX Subsection "PERL -> JSON"
1310 The mapping from Perl to \s-1JSON\s0 is slightly more difficult, as Perl is a
1311 truly typeless language, so we can only guess which \s-1JSON\s0 type is meant by
1312 a Perl value.
1313 .IP "hash references" 4
1314 .IX Item "hash references"
1315 Perl hash references become \s-1JSON\s0 objects. As there is no inherent ordering
1316 in hash keys (or \s-1JSON\s0 objects), they will usually be encoded in a
1317 pseudo-random order that can change between runs of the same program but
1318 stays generally the same within a single run of a program. \f(CW\*(C`JSON\*(C'\fR
1319 optionally sort the hash keys (determined by the \fIcanonical\fR flag), so
1320 the same datastructure will serialise to the same \s-1JSON\s0 text (given same
1321 settings and version of \s-1JSON::XS\s0), but this incurs a runtime overhead
1322 and is only rarely useful, e.g. when you want to compare some \s-1JSON\s0 text
1323 against another for equality.
1324 .Sp
1325 In future, the ordered object feature will be added to \s-1JSON::PP\s0 using \f(CW\*(C`tie\*(C'\fR mechanism.
1326 .IP "array references" 4
1327 .IX Item "array references"
1328 Perl array references become \s-1JSON\s0 arrays.
1329 .IP "other references" 4
1330 .IX Item "other references"
1331 Other unblessed references are generally not allowed and will cause an
1332 exception to be thrown, except for references to the integers \f(CW0\fR and
1333 \&\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
1334 also use \f(CW\*(C`JSON::false\*(C'\fR and \f(CW\*(C`JSON::true\*(C'\fR to improve readability.
1335 .Sp
1336 .Vb 1
1337 \&   to_json [\e0,JSON::true]      # yields [false,true]
1338 .Ve
1339 .IP "JSON::true, JSON::false, JSON::null" 4
1340 .IX Item "JSON::true, JSON::false, JSON::null"
1341 These special values become \s-1JSON\s0 true and \s-1JSON\s0 false values,
1342 respectively. You can also use \f(CW\*(C`\e1\*(C'\fR and \f(CW\*(C`\e0\*(C'\fR directly if you want.
1343 .Sp
1344 JSON::null returns \f(CW\*(C`undef\*(C'\fR.
1345 .IP "blessed objects" 4
1346 .IX Item "blessed objects"
1347 Blessed objects are not directly representable in \s-1JSON\s0. See the
1348 \&\f(CW\*(C`allow_blessed\*(C'\fR and \f(CW\*(C`convert_blessed\*(C'\fR methods on various options on
1349 how to deal with this: basically, you can choose between throwing an
1350 exception, encoding the reference as if it weren't blessed, or provide
1351 your own serialiser method.
1352 .Sp
1353 With \f(CW\*(C`convert_blessed_universally\*(C'\fR mode,  \f(CW\*(C`encode\*(C'\fR converts blessed
1354 hash references or blessed array references (contains other blessed references)
1355 into \s-1JSON\s0 members and arrays.
1356 .Sp
1357 .Vb 2
1358 \&   use JSON \-convert_blessed_universally;
1359 \&   JSON\->new\->allow_blessed\->convert_blessed\->encode( $blessed_object );
1360 .Ve
1361 .Sp
1362 See to convert_blessed.
1363 .IP "simple scalars" 4
1364 .IX Item "simple scalars"
1365 Simple Perl scalars (any scalar that is not a reference) are the most
1366 difficult objects to encode: \s-1JSON::XS\s0 and \s-1JSON::PP\s0 will encode undefined scalars as
1367 \&\s-1JSON\s0 \f(CW\*(C`null\*(C'\fR values, scalars that have last been used in a string context
1368 before encoding as \s-1JSON\s0 strings, and anything else as number value:
1369 .Sp
1370 .Vb 4
1371 \&   # dump as number
1372 \&   encode_json [2]                      # yields [2]
1373 \&   encode_json [\-3.0e17]                # yields [\-3e+17]
1374 \&   my $value = 5; encode_json [$value]  # yields [5]
1375 .Ve
1376 .Sp
1377 .Vb 3
1378 \&   # used as string, so dump as string
1379 \&   print $value;
1380 \&   encode_json [$value]                 # yields ["5"]
1381 .Ve
1382 .Sp
1383 .Vb 2
1384 \&   # undef becomes null
1385 \&   encode_json [undef]                  # yields [null]
1386 .Ve
1387 .Sp
1388 You can force the type to be a string by stringifying it:
1389 .Sp
1390 .Vb 4
1391 \&   my $x = 3.1; # some variable containing a number
1392 \&   "$x";        # stringified
1393 \&   $x .= "";    # another, more awkward way to stringify
1394 \&   print $x;    # perl does it for you, too, quite often
1395 .Ve
1396 .Sp
1397 You can force the type to be a number by numifying it:
1398 .Sp
1399 .Vb 3
1400 \&   my $x = "3"; # some variable containing a string
1401 \&   $x += 0;     # numify it, ensuring it will be dumped as a number
1402 \&   $x *= 1;     # same thing, the choise is yours.
1403 .Ve
1404 .Sp
1405 You can not currently force the type in other, less obscure, ways.
1406 .IP "Big Number" 4
1407 .IX Item "Big Number"
1408 If the backend is \s-1JSON::PP\s0 and \f(CW\*(C`allow_bignum\*(C'\fR is enable,
1409 \&\f(CW\*(C`encode\*(C'\fR converts \f(CW\*(C`Math::BigInt\*(C'\fR objects and \f(CW\*(C`Math::BigFloat\*(C'\fR
1410 objects into \s-1JSON\s0 numbers.
1411 .SH "JSON and ECMAscript"
1412 .IX Header "JSON and ECMAscript"
1413 See to \*(L"\s-1JSON\s0 and ECMAscript\*(R" in \s-1JSON::XS\s0.
1414 .SH "JSON and YAML"
1415 .IX Header "JSON and YAML"
1416 \&\s-1JSON\s0 is not a subset of \s-1YAML\s0.
1417 See to \*(L"\s-1JSON\s0 and \s-1YAML\s0\*(R" in \s-1JSON::XS\s0.
1418 .SH "BACKEND MODULE DECISION"
1419 .IX Header "BACKEND MODULE DECISION"
1420 When you use \f(CW\*(C`JSON\*(C'\fR, \f(CW\*(C`JSON\*(C'\fR tries to \f(CW\*(C`use\*(C'\fR \s-1JSON::XS\s0. If this call failed, it will
1421 \&\f(CW\*(C`uses\*(C'\fR \s-1JSON::PP\s0. The required \s-1JSON::XS\s0 version is \fI2.2\fR or later.
1422 .PP
1423 The \f(CW\*(C`JSON\*(C'\fR constructor method returns an object inherited from the backend module,
1424 and \s-1JSON::XS\s0 object is a blessed scaler reference while \s-1JSON::PP\s0 is a blessed hash
1425 reference.
1426 .PP
1427 So, your program should not depend on the backend module, especially
1428 returned objects should not be modified.
1429 .PP
1430 .Vb 2
1431 \& my $json = JSON\->new; # XS or PP?
1432 \& $json\->{stash} = 'this is xs object'; # this code may raise an error!
1433 .Ve
1434 .PP
1435 To check the backend module, there are some methods \- \f(CW\*(C`backend\*(C'\fR, \f(CW\*(C`is_pp\*(C'\fR and \f(CW\*(C`is_xs\*(C'\fR.
1436 .PP
1437 .Vb 1
1438 \&  JSON\->backend; # 'JSON::XS' or 'JSON::PP'
1439 .Ve
1440 .PP
1441 .Vb 1
1442 \&  JSON\->backend\->is_pp: # 0 or 1
1443 .Ve
1444 .PP
1445 .Vb 1
1446 \&  JSON\->backend\->is_xs: # 1 or 0
1447 .Ve
1448 .PP
1449 .Vb 1
1450 \&  $json\->is_xs; # 1 or 0
1451 .Ve
1452 .PP
1453 .Vb 1
1454 \&  $json\->is_pp; # 0 or 1
1455 .Ve
1456 .PP
1457 If you set an enviornment variable \f(CW\*(C`PERL_JSON_BACKEND\*(C'\fR, The calling action will be changed.
1458 .IP "\s-1PERL_JSON_BACKEND\s0 = 0 or \s-1PERL_JSON_BACKEND\s0 = '\s-1JSON::PP\s0'" 4
1459 .IX Item "PERL_JSON_BACKEND = 0 or PERL_JSON_BACKEND = 'JSON::PP'"
1460 Always use \s-1JSON::PP\s0
1461 .IP "\s-1PERL_JSON_BACKEND\s0 == 1 or \s-1PERL_JSON_BACKEND\s0 = '\s-1JSON::XS\s0,JSON::PP'" 4
1462 .IX Item "PERL_JSON_BACKEND == 1 or PERL_JSON_BACKEND = 'JSON::XS,JSON::PP'"
1463 (The default) Use compiled \s-1JSON::XS\s0 if it is properly compiled & installed,
1464 otherwise use \s-1JSON::PP\s0.
1465 .IP "\s-1PERL_JSON_BACKEND\s0 == 2 or \s-1PERL_JSON_BACKEND\s0 = '\s-1JSON::XS\s0'" 4
1466 .IX Item "PERL_JSON_BACKEND == 2 or PERL_JSON_BACKEND = 'JSON::XS'"
1467 Always use compiled \s-1JSON::XS\s0, die if it isn't properly compiled & installed.
1468 .PP
1469 These ideas come from DBI::PurePerl mechanism.
1470 .PP
1471 example:
1472 .PP
1473 .Vb 2
1474 \& BEGIN { $ENV{PERL_JSON_BACKEND} = 'JSON::PP' }
1475 \& use JSON; # always uses JSON::PP
1476 .Ve
1477 .PP
1478 In future, it may be able to specify another module.
1479 .SH "USE PP FEATURES EVEN THOUGH XS BACKEND"
1480 .IX Header "USE PP FEATURES EVEN THOUGH XS BACKEND"
1481 Many methods are available with either \s-1JSON::XS\s0 or \s-1JSON::PP\s0 and
1482 when the backend module is \s-1JSON::XS\s0, if any \s-1JSON::PP\s0 specific (i.e. \s-1JSON::XS\s0 unspported)
1483 method is called, it will \f(CW\*(C`warn\*(C'\fR and be noop.
1484 .PP
1485 But If you \f(CW\*(C`use\*(C'\fR \f(CW\*(C`JSON\*(C'\fR passing the optional string \f(CW\*(C`\-support_by_pp\*(C'\fR,
1486 it makes a part of those unupported methods available.
1487 This feature is achieved by using \s-1JSON::PP\s0 in \f(CW\*(C`de/encode\*(C'\fR.
1488 .PP
1489 .Vb 4
1490 \&   BEGIN { $ENV{PERL_JSON_BACKEND} = 2 } # with JSON::XS
1491 \&   use JSON \-support_by_pp;
1492 \&   my $json = new JSON;
1493 \&   $json\->allow_nonref\->escape_slash\->encode("/");
1494 .Ve
1495 .PP
1496 At this time, the returned object is a \f(CW\*(C`JSON::Backend::XS::Supportable\*(C'\fR
1497 object (re\-blessed \s-1XS\s0 object), and  by checking \s-1JSON::XS\s0 unsupported flags
1498 in de/encoding, can support some unsupported methods \- \f(CW\*(C`loose\*(C'\fR, \f(CW\*(C`allow_bignum\*(C'\fR,
1499 \&\f(CW\*(C`allow_barekey\*(C'\fR, \f(CW\*(C`allow_singlequote\*(C'\fR, \f(CW\*(C`escape_slash\*(C'\fR, \f(CW\*(C`as_nonblessed\*(C'\fR
1500 and \f(CW\*(C`indent_length\*(C'\fR.
1501 .PP
1502 When any unsupported methods are not enable, \f(CW\*(C`XS de/encode\*(C'\fR will be
1503 used as is. The switch is achieved by changing the symbolic tables.
1504 .PP
1505 \&\f(CW\*(C`\-support_by_pp\*(C'\fR is effective only when the backend module is \s-1JSON::XS\s0
1506 and it makes the de/encoding speed down a bit.
1507 .PP
1508 See to \*(L"\s-1JSON::PP\s0 \s-1SUPPORT\s0 \s-1METHODS\s0\*(R".
1509 .SH "INCOMPATIBLE CHANGES TO OLD VERSION"
1510 .IX Header "INCOMPATIBLE CHANGES TO OLD VERSION"
1511 There are big incompatibility between new version (2.00) and old (1.xx).
1512 If you use old \f(CW\*(C`JSON\*(C'\fR 1.xx in your code, please check it.
1513 .PP
1514 See to \*(L"Transition ways from 1.xx to 2.xx.\*(R"
1515 .IP "jsonToObj and objToJson are obsoleted." 4
1516 .IX Item "jsonToObj and objToJson are obsoleted."
1517 Non Perl-style name \f(CW\*(C`jsonToObj\*(C'\fR and \f(CW\*(C`objToJson\*(C'\fR are obsoleted
1518 (but not yet deleted from the source).
1519 If you use these functions in your code, please replace them
1520 with \f(CW\*(C`from_json\*(C'\fR and \f(CW\*(C`to_json\*(C'\fR.
1521 .IP "Global variables are no longer available." 4
1522 .IX Item "Global variables are no longer available."
1523 \&\f(CW\*(C`JSON\*(C'\fR class variables \- \f(CW$JSON::AUTOCONVERT\fR, \f(CW$JSON::BareKey\fR, etc...
1524 \&\- are not avaliable any longer.
1525 Instead, various features can be used through object methods.
1526 .IP "Package JSON::Converter and JSON::Parser are deleted." 4
1527 .IX Item "Package JSON::Converter and JSON::Parser are deleted."
1528 Now \f(CW\*(C`JSON\*(C'\fR bundles with \s-1JSON::PP\s0 which can handle \s-1JSON\s0 more properly than them.
1529 .IP "Package JSON::NotString is deleted." 4
1530 .IX Item "Package JSON::NotString is deleted."
1531 There was \f(CW\*(C`JSON::NotString\*(C'\fR class which represents \s-1JSON\s0 value \f(CW\*(C`true\*(C'\fR, \f(CW\*(C`false\*(C'\fR, \f(CW\*(C`null\*(C'\fR
1532 and numbers. It was deleted and replaced by \f(CW\*(C`JSON::Boolean\*(C'\fR.
1533 .Sp
1534 \&\f(CW\*(C`JSON::Boolean\*(C'\fR represents \f(CW\*(C`true\*(C'\fR and \f(CW\*(C`false\*(C'\fR.
1535 .Sp
1536 \&\f(CW\*(C`JSON::Boolean\*(C'\fR does not represent \f(CW\*(C`null\*(C'\fR.
1537 .Sp
1538 \&\f(CW\*(C`JSON::null\*(C'\fR returns \f(CW\*(C`undef\*(C'\fR.
1539 .Sp
1540 \&\f(CW\*(C`JSON\*(C'\fR makes JSON::XS::Boolean and JSON::PP::Boolean is-a relation
1541 to JSON::Boolean.
1542 .IP "function JSON::Number is obsoleted." 4
1543 .IX Item "function JSON::Number is obsoleted."
1544 \&\f(CW\*(C`JSON::Number\*(C'\fR is now needless because \s-1JSON::XS\s0 and \s-1JSON::PP\s0 have
1545 round-trip integrity.
1546 .IP "\s-1JSONRPC\s0 modules are deleted." 4
1547 .IX Item "JSONRPC modules are deleted."
1548 Perl implementation of JSON-RPC protocol \- \f(CW\*(C`JSONRPC \*(C'\fR, \f(CW\*(C`JSONRPC::Transport::HTTP\*(C'\fR
1549 and \f(CW\*(C`Apache::JSONRPC \*(C'\fR are deleted in this distribution.
1550 Instead of them, there is \s-1JSON::RPC\s0 which supports JSON-RPC protocol version 1.1.
1551 .Sh "Transition ways from 1.xx to 2.xx."
1552 .IX Subsection "Transition ways from 1.xx to 2.xx."
1553 You should set \f(CW\*(C`suport_by_pp\*(C'\fR mode firstly, because
1554 it is always successful for the below codes even with \s-1JSON::XS\s0.
1555 .PP
1556 .Vb 1
1557 \&    use JSON \-support_by_pp;
1558 .Ve
1559 .IP "Exported jsonToObj (simple)" 4
1560 .IX Item "Exported jsonToObj (simple)"
1561 .Vb 1
1562 \&  from_json($json_text);
1563 .Ve
1564 .IP "Exported objToJson (simple)" 4
1565 .IX Item "Exported objToJson (simple)"
1566 .Vb 1
1567 \&  to_json($perl_scalar);
1568 .Ve
1569 .IP "Exported jsonToObj (advanced)" 4
1570 .IX Item "Exported jsonToObj (advanced)"
1571 .Vb 2
1572 \&  $flags = {allow_barekey => 1, allow_singlequote => 1};
1573 \&  from_json($json_text, $flags);
1574 .Ve
1575 .Sp
1576 equivalent to:
1577 .Sp
1578 .Vb 3
1579 \&  $JSON::BareKey = 1;
1580 \&  $JSON::QuotApos = 1;
1581 \&  jsonToObj($json_text);
1582 .Ve
1583 .IP "Exported objToJson (advanced)" 4
1584 .IX Item "Exported objToJson (advanced)"
1585 .Vb 2
1586 \&  $flags = {allow_blessed => 1, allow_barekey => 1};
1587 \&  to_json($perl_scalar, $flags);
1588 .Ve
1589 .Sp
1590 equivalent to:
1591 .Sp
1592 .Vb 2
1593 \&  $JSON::BareKey = 1;
1594 \&  objToJson($perl_scalar);
1595 .Ve
1596 .IP "jsonToObj as object method" 4
1597 .IX Item "jsonToObj as object method"
1598 .Vb 1
1599 \&  $json\->decode($json_text);
1600 .Ve
1601 .IP "objToJson as object method" 4
1602 .IX Item "objToJson as object method"
1603 .Vb 1
1604 \&  $json\->encode($perl_scalar);
1605 .Ve
1606 .IP "new method with parameters" 4
1607 .IX Item "new method with parameters"
1608 The \f(CW\*(C`new\*(C'\fR method in 2.x takes any parameters no longer.
1609 You can set parameters instead;
1610 .Sp
1611 .Vb 1
1612 \&   $json = JSON\->new\->pretty;
1613 .Ve
1614 .ie n .IP "$JSON::Pretty, $JSON::Indent\fR, \f(CW$JSON::Delimiter" 4
1615 .el .IP "$JSON::Pretty, \f(CW$JSON::Indent\fR, \f(CW$JSON::Delimiter\fR" 4
1616 .IX Item "$JSON::Pretty, $JSON::Indent, $JSON::Delimiter"
1617 If \f(CW\*(C`indent\*(C'\fR is enable, that menas \f(CW$JSON::Pretty\fR flag set. And
1618 \&\f(CW$JSON::Delimiter\fR was substituted by \f(CW\*(C`space_before\*(C'\fR and \f(CW\*(C`space_after\*(C'\fR.
1619 In conclusion:
1620 .Sp
1621 .Vb 1
1622 \&   $json\->indent\->space_before\->space_after;
1623 .Ve
1624 .Sp
1625 Equivalent to:
1626 .Sp
1627 .Vb 1
1628 \&  $json\->pretty;
1629 .Ve
1630 .Sp
1631 To change indent length, use \f(CW\*(C`indent_length\*(C'\fR.
1632 .Sp
1633 (Only with \s-1JSON::PP\s0, if \f(CW\*(C`\-support_by_pp\*(C'\fR is not used.)
1634 .Sp
1635 .Vb 1
1636 \&  $json\->pretty\->indent_length(2)\->encode($perl_scalar);
1637 .Ve
1638 .IP "$JSON::BareKey" 4
1639 .IX Item "$JSON::BareKey"
1640 (Only with \s-1JSON::PP\s0, if \f(CW\*(C`\-support_by_pp\*(C'\fR is not used.)
1641 .Sp
1642 .Vb 1
1643 \&  $json\->allow_barekey\->decode($json_text)
1644 .Ve
1645 .IP "$JSON::ConvBlessed" 4
1646 .IX Item "$JSON::ConvBlessed"
1647 use \f(CW\*(C`\-convert_blessed_universally\*(C'\fR. See to convert_blessed.
1648 .IP "$JSON::QuotApos" 4
1649 .IX Item "$JSON::QuotApos"
1650 (Only with \s-1JSON::PP\s0, if \f(CW\*(C`\-support_by_pp\*(C'\fR is not used.)
1651 .Sp
1652 .Vb 1
1653 \&  $json\->allow_singlequote\->decode($json_text)
1654 .Ve
1655 .IP "$JSON::SingleQuote" 4
1656 .IX Item "$JSON::SingleQuote"
1657 Disable. \f(CW\*(C`JSON\*(C'\fR does not make such a invalid \s-1JSON\s0 string any longer.
1658 .IP "$JSON::KeySort" 4
1659 .IX Item "$JSON::KeySort"
1660 .Vb 1
1661 \&  $json\->canonical\->encode($perl_scalar)
1662 .Ve
1663 .Sp
1664 This is the ascii sort.
1665 .Sp
1666 If you want to use with your own sort routine, check the \f(CW\*(C`sort_by\*(C'\fR method.
1667 .Sp
1668 (Only with \s-1JSON::PP\s0, even if \f(CW\*(C`\-support_by_pp\*(C'\fR is used currently.)
1669 .Sp
1670 .Vb 1
1671 \&  $json\->sort_by($sort_routine_ref)\->encode($perl_scalar)
1672 .Ve
1673 .Sp
1674 .Vb 1
1675 \&  $json\->sort_by(sub { $JSON::PP::a <=> $JSON::PP::b })\->encode($perl_scalar)
1676 .Ve
1677 .Sp
1678 Can't access \f(CW$a\fR and \f(CW$b\fR but \f(CW$JSON::PP::a\fR and \f(CW$JSON::PP::b\fR.
1679 .IP "$JSON::SkipInvalid" 4
1680 .IX Item "$JSON::SkipInvalid"
1681 .Vb 1
1682 \&  $json\->allow_unknown
1683 .Ve
1684 .IP "$JSON::AUTOCONVERT" 4
1685 .IX Item "$JSON::AUTOCONVERT"
1686 Needless. \f(CW\*(C`JSON\*(C'\fR backend modules have the round-trip integrity.
1687 .IP "$JSON::UTF8" 4
1688 .IX Item "$JSON::UTF8"
1689 Needless because \f(CW\*(C`JSON\*(C'\fR (\s-1JSON::XS/JSON::PP\s0) sets
1690 the \s-1UTF8\s0 flag on properly.
1691 .Sp
1692 .Vb 1
1693 \&    # With UTF8\-flagged strings
1694 .Ve
1695 .Sp
1696 .Vb 2
1697 \&    $json\->allow_nonref;
1698 \&    $str = chr(1000); # UTF8\-flagged
1699 .Ve
1700 .Sp
1701 .Vb 6
1702 \&    $json_text  = $json\->utf8(0)\->encode($str);
1703 \&    utf8::is_utf8($json_text);
1704 \&    # true
1705 \&    $json_text  = $json\->utf8(1)\->encode($str);
1706 \&    utf8::is_utf8($json_text);
1707 \&    # false
1708 .Ve
1709 .Sp
1710 .Vb 1
1711 \&    $str = '"' . chr(1000) . '"'; # UTF8\-flagged
1712 .Ve
1713 .Sp
1714 .Vb 5
1715 \&    $perl_scalar  = $json\->utf8(0)\->decode($str);
1716 \&    utf8::is_utf8($perl_scalar);
1717 \&    # true
1718 \&    $perl_scalar  = $json\->utf8(1)\->decode($str);
1719 \&    # died because of 'Wide character in subroutine'
1720 .Ve
1721 .Sp
1722 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.
1723 .IP "$JSON::UnMapping" 4
1724 .IX Item "$JSON::UnMapping"
1725 Disable. See to \s-1MAPPING\s0.
1726 .IP "$JSON::SelfConvert" 4
1727 .IX Item "$JSON::SelfConvert"
1728 This option was deleted.
1729 Instead of it, if a givien blessed object has the \f(CW\*(C`TO_JSON\*(C'\fR method,
1730 \&\f(CW\*(C`TO_JSON\*(C'\fR will be executed with \f(CW\*(C`convert_blessed\*(C'\fR.
1731 .Sp
1732 .Vb 2
1733 \&  $json\->convert_blessed\->encode($bleesed_hashref_or_arrayref)
1734 \&  # if need, call allow_blessed
1735 .Ve
1736 .Sp
1737 Note that it was \f(CW\*(C`toJson\*(C'\fR in old version, but now not \f(CW\*(C`toJson\*(C'\fR but \f(CW\*(C`TO_JSON\*(C'\fR.
1738 .SH "TODO"
1739 .IX Header "TODO"
1740 .IP "example programs" 4
1741 .IX Item "example programs"
1742 .SH "THREADS"
1743 .IX Header "THREADS"
1744 No test with \s-1JSON::PP\s0. If with \s-1JSON::XS\s0, See to \*(L"\s-1THREADS\s0\*(R" in \s-1JSON::XS\s0.
1745 .SH "BUGS"
1746 .IX Header "BUGS"
1747 Please report bugs relevant to \f(CW\*(C`JSON\*(C'\fR to <makamaka[at]cpan.org>.
1748 .SH "SEE ALSO"
1749 .IX Header "SEE ALSO"
1750 Most of the document is copied and modified from \s-1JSON::XS\s0 doc.
1751 .PP
1752 \&\s-1JSON::XS\s0, \s-1JSON::PP\s0
1753 .PP
1754 \&\f(CW\*(C`RFC4627\*(C'\fR(<http://www.ietf.org/rfc/rfc4627.txt>)
1755 .SH "AUTHOR"
1756 .IX Header "AUTHOR"
1757 Makamaka Hannyaharamitu, <makamaka[at]cpan.org>
1758 .PP
1759 \&\s-1JSON::XS\s0 was written by  Marc Lehmann <schmorp[at]schmorp.de>
1760 .PP
1761 The relese of this new version owes to the courtesy of Marc Lehmann.
1762 .SH "COPYRIGHT AND LICENSE"
1763 .IX Header "COPYRIGHT AND LICENSE"
1764 Copyright 2005\-2009 by Makamaka Hannyaharamitu
1765 .PP
1766 This library is free software; you can redistribute it and/or modify
1767 it under the same terms as Perl itself.