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