ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/JSON-XS/README
(Generate patch)

Comparing JSON-XS/README (file contents):
Revision 1.35 by root, Thu Mar 11 19:31:37 2010 UTC vs.
Revision 1.43 by root, Thu Nov 15 23:07:55 2018 UTC

… …
29 29
30DESCRIPTION 30DESCRIPTION
31 This module converts Perl data structures to JSON and vice versa. Its 31 This module converts Perl data structures to JSON and vice versa. Its
32 primary goal is to be *correct* and its secondary goal is to be *fast*. 32 primary goal is to be *correct* and its secondary goal is to be *fast*.
33 To reach the latter goal it was written in C. 33 To reach the latter goal it was written in C.
34
35 Beginning with version 2.0 of the JSON module, when both JSON and
36 JSON::XS are installed, then JSON will fall back on JSON::XS (this can
37 be overridden) with no overhead due to emulation (by inheriting
38 constructor and methods). If JSON::XS is not available, it will fall
39 back to the compatible JSON::PP module as backend, so using JSON instead
40 of JSON::XS gives you a portable JSON API that can be fast when you need
41 and doesn't require a C compiler when that is a problem.
42
43 As this is the n-th-something JSON module on CPAN, what was the reason
44 to write yet another JSON module? While it seems there are many JSON
45 modules, none of them correctly handle all corner cases, and in most
46 cases their maintainers are unresponsive, gone missing, or not listening
47 to bug reports for other reasons.
48 34
49 See MAPPING, below, on how JSON::XS maps perl values to JSON values and 35 See MAPPING, below, on how JSON::XS maps perl values to JSON values and
50 vice versa. 36 vice versa.
51 37
52 FEATURES 38 FEATURES
… …
77 too. 63 too.
78 64
79 * simple to use 65 * simple to use
80 66
81 This module has both a simple functional interface as well as an 67 This module has both a simple functional interface as well as an
82 object oriented interface interface. 68 object oriented interface.
83 69
84 * reasonably versatile output formats 70 * reasonably versatile output formats
85 71
86 You can choose between the most compact guaranteed-single-line 72 You can choose between the most compact guaranteed-single-line
87 format possible (nice for simple line-based protocols), a pure-ASCII 73 format possible (nice for simple line-based protocols), a pure-ASCII
… …
103 $json_text = JSON::XS->new->utf8->encode ($perl_scalar) 89 $json_text = JSON::XS->new->utf8->encode ($perl_scalar)
104 90
105 Except being faster. 91 Except being faster.
106 92
107 $perl_scalar = decode_json $json_text 93 $perl_scalar = decode_json $json_text
108 The opposite of "encode_json": expects an UTF-8 (binary) string and 94 The opposite of "encode_json": expects a UTF-8 (binary) string and
109 tries to parse that as an UTF-8 encoded JSON text, returning the 95 tries to parse that as a UTF-8 encoded JSON text, returning the
110 resulting reference. Croaks on error. 96 resulting reference. Croaks on error.
111 97
112 This function call is functionally identical to: 98 This function call is functionally identical to:
113 99
114 $perl_scalar = JSON::XS->new->utf8->decode ($json_text) 100 $perl_scalar = JSON::XS->new->utf8->decode ($json_text)
115 101
116 Except being faster. 102 Except being faster.
117
118 $is_boolean = JSON::XS::is_bool $scalar
119 Returns true if the passed scalar represents either JSON::XS::true
120 or JSON::XS::false, two constants that act like 1 and 0,
121 respectively and are used to represent JSON "true" and "false"
122 values in Perl.
123
124 See MAPPING, below, for more information on how JSON values are
125 mapped to Perl.
126 103
127A FEW NOTES ON UNICODE AND PERL 104A FEW NOTES ON UNICODE AND PERL
128 Since this often leads to confusion, here are a few very clear words on 105 Since this often leads to confusion, here are a few very clear words on
129 how Unicode works in Perl, modulo bugs. 106 how Unicode works in Perl, modulo bugs.
130 107
… …
167 The object oriented interface lets you configure your own encoding or 144 The object oriented interface lets you configure your own encoding or
168 decoding style, within the limits of supported formats. 145 decoding style, within the limits of supported formats.
169 146
170 $json = new JSON::XS 147 $json = new JSON::XS
171 Creates a new JSON::XS object that can be used to de/encode JSON 148 Creates a new JSON::XS object that can be used to de/encode JSON
172 strings. All boolean flags described below are by default 149 strings. All boolean flags described below are by default *disabled*
173 *disabled*. 150 (with the exception of "allow_nonref", which defaults to *enabled*
151 since version 4.0).
174 152
175 The mutators for flags all return the JSON object again and thus 153 The mutators for flags all return the JSON object again and thus
176 calls can be chained: 154 calls can be chained:
177 155
178 my $json = JSON::XS->new->utf8->space_after->encode ({a => [1,2]}) 156 my $json = JSON::XS->new->utf8->space_after->encode ({a => [1,2]})
… …
234 212
235 $json = $json->utf8 ([$enable]) 213 $json = $json->utf8 ([$enable])
236 $enabled = $json->get_utf8 214 $enabled = $json->get_utf8
237 If $enable is true (or missing), then the "encode" method will 215 If $enable is true (or missing), then the "encode" method will
238 encode the JSON result into UTF-8, as required by many protocols, 216 encode the JSON result into UTF-8, as required by many protocols,
239 while the "decode" method expects to be handled an UTF-8-encoded 217 while the "decode" method expects to be handed a UTF-8-encoded
240 string. Please note that UTF-8-encoded strings do not contain any 218 string. Please note that UTF-8-encoded strings do not contain any
241 characters outside the range 0..255, they are thus useful for 219 characters outside the range 0..255, they are thus useful for
242 bytewise/binary I/O. In future versions, enabling this option might 220 bytewise/binary I/O. In future versions, enabling this option might
243 enable autodetection of the UTF-16 and UTF-32 encoding families, as 221 enable autodetection of the UTF-16 and UTF-32 encoding families, as
244 described in RFC4627. 222 described in RFC4627.
… …
323 301
324 $json = $json->relaxed ([$enable]) 302 $json = $json->relaxed ([$enable])
325 $enabled = $json->get_relaxed 303 $enabled = $json->get_relaxed
326 If $enable is true (or missing), then "decode" will accept some 304 If $enable is true (or missing), then "decode" will accept some
327 extensions to normal JSON syntax (see below). "encode" will not be 305 extensions to normal JSON syntax (see below). "encode" will not be
328 affected in anyway. *Be aware that this option makes you accept 306 affected in any way. *Be aware that this option makes you accept
329 invalid JSON texts as if they were valid!*. I suggest only to use 307 invalid JSON texts as if they were valid!*. I suggest only to use
330 this option to parse application-specific files written by humans 308 this option to parse application-specific files written by humans
331 (configuration files, resource files etc.) 309 (configuration files, resource files etc.)
332 310
333 If $enable is false (the default), then "decode" will only accept 311 If $enable is false (the default), then "decode" will only accept
… …
361 [ 339 [
362 1, # this comment not allowed in JSON 340 1, # this comment not allowed in JSON
363 # neither this one... 341 # neither this one...
364 ] 342 ]
365 343
344 * literal ASCII TAB characters in strings
345
346 Literal ASCII TAB characters are now allowed in strings (and
347 treated as "\t").
348
349 [
350 "Hello\tWorld",
351 "Hello<TAB>World", # literal <TAB> would not normally be allowed
352 ]
353
366 $json = $json->canonical ([$enable]) 354 $json = $json->canonical ([$enable])
367 $enabled = $json->get_canonical 355 $enabled = $json->get_canonical
368 If $enable is true (or missing), then the "encode" method will 356 If $enable is true (or missing), then the "encode" method will
369 output JSON objects by sorting their keys. This is adding a 357 output JSON objects by sorting their keys. This is adding a
370 comparatively high overhead. 358 comparatively high overhead.
371 359
372 If $enable is false, then the "encode" method will output key-value 360 If $enable is false, then the "encode" method will output key-value
373 pairs in the order Perl stores them (which will likely change 361 pairs in the order Perl stores them (which will likely change
374 between runs of the same script). 362 between runs of the same script, and can change even within the same
363 run from 5.18 onwards).
375 364
376 This option is useful if you want the same data structure to be 365 This option is useful if you want the same data structure to be
377 encoded as the same JSON text (given the same overall settings). If 366 encoded as the same JSON text (given the same overall settings). If
378 it is disabled, the same hash might be encoded differently even if 367 it is disabled, the same hash might be encoded differently even if
379 contains the same data, as key-value pairs have no inherent ordering 368 contains the same data, as key-value pairs have no inherent ordering
… …
383 372
384 This setting has currently no effect on tied hashes. 373 This setting has currently no effect on tied hashes.
385 374
386 $json = $json->allow_nonref ([$enable]) 375 $json = $json->allow_nonref ([$enable])
387 $enabled = $json->get_allow_nonref 376 $enabled = $json->get_allow_nonref
377 Unlike other boolean options, this opotion is enabled by default
378 beginning with version 4.0. See "SECURITY CONSIDERATIONS" for the
379 gory details.
380
388 If $enable is true (or missing), then the "encode" method can 381 If $enable is true (or missing), then the "encode" method can
389 convert a non-reference into its corresponding string, number or 382 convert a non-reference into its corresponding string, number or
390 null JSON value, which is an extension to RFC4627. Likewise, 383 null JSON value, which is an extension to RFC4627. Likewise,
391 "decode" will accept those JSON values instead of croaking. 384 "decode" will accept those JSON values instead of croaking.
392 385
393 If $enable is false, then the "encode" method will croak if it isn't 386 If $enable is false, then the "encode" method will croak if it isn't
394 passed an arrayref or hashref, as JSON texts must either be an 387 passed an arrayref or hashref, as JSON texts must either be an
395 object or array. Likewise, "decode" will croak if given something 388 object or array. Likewise, "decode" will croak if given something
396 that is not a JSON object or array. 389 that is not a JSON object or array.
397 390
398 Example, encode a Perl scalar as JSON value with enabled 391 Example, encode a Perl scalar as JSON value without enabled
399 "allow_nonref", resulting in an invalid JSON text: 392 "allow_nonref", resulting in an error:
400 393
401 JSON::XS->new->allow_nonref->encode ("Hello, World!") 394 JSON::XS->new->allow_nonref (0)->encode ("Hello, World!")
402 => "Hello, World!" 395 => hash- or arrayref expected...
403 396
404 $json = $json->allow_unknown ([$enable]) 397 $json = $json->allow_unknown ([$enable])
405 $enabled = $json->get_allow_unknown 398 $enabled = $json->get_allow_unknown
406 If $enable is true (or missing), then "encode" will *not* throw an 399 If $enable is true (or missing), then "encode" will *not* throw an
407 exception when it encounters values it cannot represent in JSON (for 400 exception when it encounters values it cannot represent in JSON (for
… …
416 recommended to leave it off unless you know your communications 409 recommended to leave it off unless you know your communications
417 partner. 410 partner.
418 411
419 $json = $json->allow_blessed ([$enable]) 412 $json = $json->allow_blessed ([$enable])
420 $enabled = $json->get_allow_blessed 413 $enabled = $json->get_allow_blessed
414 See "OBJECT SERIALISATION" for details.
415
421 If $enable is true (or missing), then the "encode" method will not 416 If $enable is true (or missing), then the "encode" method will not
422 barf when it encounters a blessed reference. Instead, the value of 417 barf when it encounters a blessed reference that it cannot convert
423 the convert_blessed option will decide whether "null" 418 otherwise. Instead, a JSON "null" value is encoded instead of the
424 ("convert_blessed" disabled or no "TO_JSON" method found) or a 419 object.
425 representation of the object ("convert_blessed" enabled and
426 "TO_JSON" method found) is being encoded. Has no effect on "decode".
427 420
428 If $enable is false (the default), then "encode" will throw an 421 If $enable is false (the default), then "encode" will throw an
429 exception when it encounters a blessed object. 422 exception when it encounters a blessed object that it cannot convert
423 otherwise.
424
425 This setting has no effect on "decode".
430 426
431 $json = $json->convert_blessed ([$enable]) 427 $json = $json->convert_blessed ([$enable])
432 $enabled = $json->get_convert_blessed 428 $enabled = $json->get_convert_blessed
429 See "OBJECT SERIALISATION" for details.
430
433 If $enable is true (or missing), then "encode", upon encountering a 431 If $enable is true (or missing), then "encode", upon encountering a
434 blessed object, will check for the availability of the "TO_JSON" 432 blessed object, will check for the availability of the "TO_JSON"
435 method on the object's class. If found, it will be called in scalar 433 method on the object's class. If found, it will be called in scalar
436 context and the resulting scalar will be encoded instead of the 434 context and the resulting scalar will be encoded instead of the
437 object. If no "TO_JSON" method is found, the value of 435 object.
438 "allow_blessed" will decide what to do.
439 436
440 The "TO_JSON" method may safely call die if it wants. If "TO_JSON" 437 The "TO_JSON" method may safely call die if it wants. If "TO_JSON"
441 returns other blessed objects, those will be handled in the same 438 returns other blessed objects, those will be handled in the same
442 way. "TO_JSON" must take care of not causing an endless recursion 439 way. "TO_JSON" must take care of not causing an endless recursion
443 cycle (== crash) in this case. The name of "TO_JSON" was chosen 440 cycle (== crash) in this case. The name of "TO_JSON" was chosen
444 because other methods called by the Perl core (== not by the user of 441 because other methods called by the Perl core (== not by the user of
445 the object) are usually in upper case letters and to avoid 442 the object) are usually in upper case letters and to avoid
446 collisions with any "to_json" function or method. 443 collisions with any "to_json" function or method.
447 444
448 This setting does not yet influence "decode" in any way, but in the 445 If $enable is false (the default), then "encode" will not consider
449 future, global hooks might get installed that influence "decode" and 446 this type of conversion.
450 are enabled by this setting.
451 447
452 If $enable is false, then the "allow_blessed" setting will decide 448 This setting has no effect on "decode".
453 what to do when a blessed object is found. 449
450 $json = $json->allow_tags ([$enable])
451 $enabled = $json->get_allow_tags
452 See "OBJECT SERIALISATION" for details.
453
454 If $enable is true (or missing), then "encode", upon encountering a
455 blessed object, will check for the availability of the "FREEZE"
456 method on the object's class. If found, it will be used to serialise
457 the object into a nonstandard tagged JSON value (that JSON decoders
458 cannot decode).
459
460 It also causes "decode" to parse such tagged JSON values and
461 deserialise them via a call to the "THAW" method.
462
463 If $enable is false (the default), then "encode" will not consider
464 this type of conversion, and tagged JSON values will cause a parse
465 error in "decode", as if tags were not part of the grammar.
466
467 $json->boolean_values ([$false, $true])
468 ($false, $true) = $json->get_boolean_values
469 By default, JSON booleans will be decoded as overloaded
470 $Types::Serialiser::false and $Types::Serialiser::true objects.
471
472 With this method you can specify your own boolean values for
473 decoding - on decode, JSON "false" will be decoded as a copy of
474 $false, and JSON "true" will be decoded as $true ("copy" here is the
475 same thing as assigning a value to another variable, i.e. "$copy =
476 $false").
477
478 Calling this method without any arguments will reset the booleans to
479 their default values.
480
481 "get_boolean_values" will return both $false and $true values, or
482 the empty list when they are set to the default.
454 483
455 $json = $json->filter_json_object ([$coderef->($hashref)]) 484 $json = $json->filter_json_object ([$coderef->($hashref)])
456 When $coderef is specified, it will be called from "decode" each 485 When $coderef is specified, it will be called from "decode" each
457 time it decodes a JSON object. The only argument is a reference to 486 time it decodes a JSON object. The only argument is a reference to
458 the newly-created hash. If the code references returns a single 487 the newly-created hash. If the code reference returns a single
459 scalar (which need not be a reference), this value (i.e. a copy of 488 scalar (which need not be a reference), this value (or rather a copy
460 that scalar to avoid aliasing) is inserted into the deserialised 489 of it) is inserted into the deserialised data structure. If it
461 data structure. If it returns an empty list (NOTE: *not* "undef", 490 returns an empty list (NOTE: *not* "undef", which is a valid
462 which is a valid scalar), the original deserialised hash will be 491 scalar), the original deserialised hash will be inserted. This
463 inserted. This setting can slow down decoding considerably. 492 setting can slow down decoding considerably.
464 493
465 When $coderef is omitted or undefined, any existing callback will be 494 When $coderef is omitted or undefined, any existing callback will be
466 removed and "decode" will not change the deserialised hash in any 495 removed and "decode" will not change the deserialised hash in any
467 way. 496 way.
468 497
… …
594 623
595 See SECURITY CONSIDERATIONS, below, for more info on why this is 624 See SECURITY CONSIDERATIONS, below, for more info on why this is
596 useful. 625 useful.
597 626
598 $json_text = $json->encode ($perl_scalar) 627 $json_text = $json->encode ($perl_scalar)
599 Converts the given Perl data structure (a simple scalar or a 628 Converts the given Perl value or data structure to its JSON
600 reference to a hash or array) to its JSON representation. Simple 629 representation. Croaks on error.
601 scalars will be converted into JSON string or number sequences,
602 while references to arrays become JSON arrays and references to
603 hashes become JSON objects. Undefined Perl values (e.g. "undef")
604 become JSON "null" values. Neither "true" nor "false" values will be
605 generated.
606 630
607 $perl_scalar = $json->decode ($json_text) 631 $perl_scalar = $json->decode ($json_text)
608 The opposite of "encode": expects a JSON text and tries to parse it, 632 The opposite of "encode": expects a JSON text and tries to parse it,
609 returning the resulting simple scalar or reference. Croaks on error. 633 returning the resulting simple scalar or reference. Croaks on error.
610
611 JSON numbers and strings become simple Perl scalars. JSON arrays
612 become Perl arrayrefs and JSON objects become Perl hashrefs. "true"
613 becomes 1, "false" becomes 0 and "null" becomes "undef".
614 634
615 ($perl_scalar, $characters) = $json->decode_prefix ($json_text) 635 ($perl_scalar, $characters) = $json->decode_prefix ($json_text)
616 This works like the "decode" method, but instead of raising an 636 This works like the "decode" method, but instead of raising an
617 exception when there is trailing garbage after the first JSON 637 exception when there is trailing garbage after the first JSON
618 object, it will silently stop parsing there and return the number of 638 object, it will silently stop parsing there and return the number of
619 characters consumed so far. 639 characters consumed so far.
620 640
621 This is useful if your JSON texts are not delimited by an outer 641 This is useful if your JSON texts are not delimited by an outer
622 protocol (which is not the brightest thing to do in the first place)
623 and you need to know where the JSON text ends. 642 protocol and you need to know where the JSON text ends.
624 643
625 JSON::XS->new->decode_prefix ("[1] the tail") 644 JSON::XS->new->decode_prefix ("[1] the tail")
626 => ([], 3) 645 => ([1], 3)
627 646
628INCREMENTAL PARSING 647INCREMENTAL PARSING
629 In some cases, there is the need for incremental parsing of JSON texts. 648 In some cases, there is the need for incremental parsing of JSON texts.
630 While this module always has to keep both JSON text and resulting Perl 649 While this module always has to keep both JSON text and resulting Perl
631 data structure in memory at one time, it does allow you to parse a JSON 650 data structure in memory at one time, it does allow you to parse a JSON
… …
636 calls). 655 calls).
637 656
638 JSON::XS will only attempt to parse the JSON text once it is sure it has 657 JSON::XS will only attempt to parse the JSON text once it is sure it has
639 enough text to get a decisive result, using a very simple but truly 658 enough text to get a decisive result, using a very simple but truly
640 incremental parser. This means that it sometimes won't stop as early as 659 incremental parser. This means that it sometimes won't stop as early as
641 the full parser, for example, it doesn't detect parenthese mismatches. 660 the full parser, for example, it doesn't detect mismatched parentheses.
642 The only thing it guarantees is that it starts decoding as soon as a 661 The only thing it guarantees is that it starts decoding as soon as a
643 syntactically valid JSON text has been seen. This means you need to set 662 syntactically valid JSON text has been seen. This means you need to set
644 resource limits (e.g. "max_size") to ensure the parser will stop parsing 663 resource limits (e.g. "max_size") to ensure the parser will stop parsing
645 in the presence if syntax errors. 664 in the presence if syntax errors.
646 665
… …
660 679
661 If the method is called in scalar context, then it will try to 680 If the method is called in scalar context, then it will try to
662 extract exactly *one* JSON object. If that is successful, it will 681 extract exactly *one* JSON object. If that is successful, it will
663 return this object, otherwise it will return "undef". If there is a 682 return this object, otherwise it will return "undef". If there is a
664 parse error, this method will croak just as "decode" would do (one 683 parse error, this method will croak just as "decode" would do (one
665 can then use "incr_skip" to skip the errornous part). This is the 684 can then use "incr_skip" to skip the erroneous part). This is the
666 most common way of using the method. 685 most common way of using the method.
667 686
668 And finally, in list context, it will try to extract as many objects 687 And finally, in list context, it will try to extract as many objects
669 from the stream as it can find and return them, or the empty list 688 from the stream as it can find and return them, or the empty list
670 otherwise. For this to work, there must be no separators between the 689 otherwise. For this to work, there must be no separators (other than
671 JSON objects or arrays, instead they must be concatenated 690 whitespace) between the JSON objects or arrays, instead they must be
672 back-to-back. If an error occurs, an exception will be raised as in 691 concatenated back-to-back. If an error occurs, an exception will be
673 the scalar context case. Note that in this case, any 692 raised as in the scalar context case. Note that in this case, any
674 previously-parsed JSON texts will be lost. 693 previously-parsed JSON texts will be lost.
675 694
676 Example: Parse some JSON arrays/objects in a given string and return 695 Example: Parse some JSON arrays/objects in a given string and return
677 them. 696 them.
678 697
… …
686 function (I mean it. although in simple tests it might actually 705 function (I mean it. although in simple tests it might actually
687 work, it *will* fail under real world conditions). As a special 706 work, it *will* fail under real world conditions). As a special
688 exception, you can also call this method before having parsed 707 exception, you can also call this method before having parsed
689 anything. 708 anything.
690 709
710 That means you can only use this function to look at or manipulate
711 text before or after complete JSON objects, not while the parser is
712 in the middle of parsing a JSON object.
713
691 This function is useful in two cases: a) finding the trailing text 714 This function is useful in two cases: a) finding the trailing text
692 after a JSON object or b) parsing multiple JSON objects separated by 715 after a JSON object or b) parsing multiple JSON objects separated by
693 non-JSON text (such as commas). 716 non-JSON text (such as commas).
694 717
695 $json->incr_skip 718 $json->incr_skip
… …
698 "incr_parse" died, in which case the input buffer and incremental 721 "incr_parse" died, in which case the input buffer and incremental
699 parser state is left unchanged, to skip the text parsed so far and 722 parser state is left unchanged, to skip the text parsed so far and
700 to reset the parse state. 723 to reset the parse state.
701 724
702 The difference to "incr_reset" is that only text until the parse 725 The difference to "incr_reset" is that only text until the parse
703 error occured is removed. 726 error occurred is removed.
704 727
705 $json->incr_reset 728 $json->incr_reset
706 This completely resets the incremental parser, that is, after this 729 This completely resets the incremental parser, that is, after this
707 call, it will be as if the parser had never parsed anything. 730 call, it will be as if the parser had never parsed anything.
708 731
709 This is useful if you want to repeatedly parse JSON objects and want 732 This is useful if you want to repeatedly parse JSON objects and want
710 to ignore any trailing data, which means you have to reset the 733 to ignore any trailing data, which means you have to reset the
711 parser after each successful decode. 734 parser after each successful decode.
712 735
713 LIMITATIONS 736 LIMITATIONS
714 All options that affect decoding are supported, except "allow_nonref". 737 The incremental parser is a non-exact parser: it works by gathering as
715 The reason for this is that it cannot be made to work sensibly: JSON 738 much text as possible that *could* be a valid JSON text, followed by
716 objects and arrays are self-delimited, i.e. you can concatenate them 739 trying to decode it.
717 back to back and still decode them perfectly. This does not hold true
718 for JSON numbers, however.
719 740
720 For example, is the string 1 a single JSON number, or is it simply the 741 That means it sometimes needs to read more data than strictly necessary
721 start of 12? Or is 12 a single JSON number, or the concatenation of 1 742 to diagnose an invalid JSON text. For example, after parsing the
722 and 2? In neither case you can tell, and this is why JSON::XS takes the 743 following fragment, the parser *could* stop with an error, as this
723 conservative route and disallows this case. 744 fragment *cannot* be the beginning of a valid JSON text:
745
746 [,
747
748 In reality, hopwever, the parser might continue to read data until a
749 length limit is exceeded or it finds a closing bracket.
724 750
725 EXAMPLES 751 EXAMPLES
726 Some examples will make all this clearer. First, a simple example that 752 Some examples will make all this clearer. First, a simple example that
727 works similarly to "decode_prefix": We want to decode the JSON object at 753 works similarly to "decode_prefix": We want to decode the JSON object at
728 the start of a string and identify the portion after the JSON object: 754 the start of a string and identify the portion after the JSON object:
… …
892 If the number consists of digits only, JSON::XS will try to 918 If the number consists of digits only, JSON::XS will try to
893 represent it as an integer value. If that fails, it will try to 919 represent it as an integer value. If that fails, it will try to
894 represent it as a numeric (floating point) value if that is possible 920 represent it as a numeric (floating point) value if that is possible
895 without loss of precision. Otherwise it will preserve the number as 921 without loss of precision. Otherwise it will preserve the number as
896 a string value (in which case you lose roundtripping ability, as the 922 a string value (in which case you lose roundtripping ability, as the
897 JSON number will be re-encoded toa JSON string). 923 JSON number will be re-encoded to a JSON string).
898 924
899 Numbers containing a fractional or exponential part will always be 925 Numbers containing a fractional or exponential part will always be
900 represented as numeric (floating point) values, possibly at a loss 926 represented as numeric (floating point) values, possibly at a loss
901 of precision (in which case you might lose perfect roundtripping 927 of precision (in which case you might lose perfect roundtripping
902 ability, but the JSON number will still be re-encoded as a JSON 928 ability, but the JSON number will still be re-encoded as a JSON
903 number). 929 number).
904 930
905 Note that precision is not accuracy - binary floating point values 931 Note that precision is not accuracy - binary floating point values
906 cannot represent most decimal fractions exactly, and when converting 932 cannot represent most decimal fractions exactly, and when converting
907 from and to floating point, JSON::XS only guarantees precision up to 933 from and to floating point, JSON::XS only guarantees precision up to
908 but not including the leats significant bit. 934 but not including the least significant bit.
909 935
910 true, false 936 true, false
911 These JSON atoms become "JSON::XS::true" and "JSON::XS::false", 937 These JSON atoms become "Types::Serialiser::true" and
912 respectively. They are overloaded to act almost exactly like the 938 "Types::Serialiser::false", respectively. They are overloaded to act
913 numbers 1 and 0. You can check whether a scalar is a JSON boolean by 939 almost exactly like the numbers 1 and 0. You can check whether a
914 using the "JSON::XS::is_bool" function. 940 scalar is a JSON boolean by using the "Types::Serialiser::is_bool"
941 function (after "use Types::Serialier", of course).
915 942
916 null 943 null
917 A JSON null atom becomes "undef" in Perl. 944 A JSON null atom becomes "undef" in Perl.
945
946 shell-style comments ("# *text*")
947 As a nonstandard extension to the JSON syntax that is enabled by the
948 "relaxed" setting, shell-style comments are allowed. They can start
949 anywhere outside strings and go till the end of the line.
950
951 tagged values ("(*tag*)*value*").
952 Another nonstandard extension to the JSON syntax, enabled with the
953 "allow_tags" setting, are tagged values. In this implementation, the
954 *tag* must be a perl package/class name encoded as a JSON string,
955 and the *value* must be a JSON array encoding optional constructor
956 arguments.
957
958 See "OBJECT SERIALISATION", below, for details.
918 959
919 PERL -> JSON 960 PERL -> JSON
920 The mapping from Perl to JSON is slightly more difficult, as Perl is a 961 The mapping from Perl to JSON is slightly more difficult, as Perl is a
921 truly typeless language, so we can only guess which JSON type is meant 962 truly typeless language, so we can only guess which JSON type is meant
922 by a Perl value. 963 by a Perl value.
923 964
924 hash references 965 hash references
925 Perl hash references become JSON objects. As there is no inherent 966 Perl hash references become JSON objects. As there is no inherent
926 ordering in hash keys (or JSON objects), they will usually be 967 ordering in hash keys (or JSON objects), they will usually be
927 encoded in a pseudo-random order that can change between runs of the 968 encoded in a pseudo-random order. JSON::XS can optionally sort the
928 same program but stays generally the same within a single run of a 969 hash keys (determined by the *canonical* flag), so the same
929 program. JSON::XS can optionally sort the hash keys (determined by 970 datastructure will serialise to the same JSON text (given same
930 the *canonical* flag), so the same datastructure will serialise to 971 settings and version of JSON::XS), but this incurs a runtime
931 the same JSON text (given same settings and version of JSON::XS), 972 overhead and is only rarely useful, e.g. when you want to compare
932 but this incurs a runtime overhead and is only rarely useful, e.g. 973 some JSON text against another for equality.
933 when you want to compare some JSON text against another for
934 equality.
935 974
936 array references 975 array references
937 Perl array references become JSON arrays. 976 Perl array references become JSON arrays.
938 977
939 other references 978 other references
940 Other unblessed references are generally not allowed and will cause 979 Other unblessed references are generally not allowed and will cause
941 an exception to be thrown, except for references to the integers 0 980 an exception to be thrown, except for references to the integers 0
942 and 1, which get turned into "false" and "true" atoms in JSON. You 981 and 1, which get turned into "false" and "true" atoms in JSON.
943 can also use "JSON::XS::false" and "JSON::XS::true" to improve 982
983 Since "JSON::XS" uses the boolean model from Types::Serialiser, you
984 can also "use Types::Serialiser" and then use
985 "Types::Serialiser::false" and "Types::Serialiser::true" to improve
944 readability. 986 readability.
945 987
988 use Types::Serialiser;
946 encode_json [\0, JSON::XS::true] # yields [false,true] 989 encode_json [\0, Types::Serialiser::true] # yields [false,true]
947 990
948 JSON::XS::true, JSON::XS::false 991 Types::Serialiser::true, Types::Serialiser::false
949 These special values become JSON true and JSON false values, 992 These special values from the Types::Serialiser module become JSON
950 respectively. You can also use "\1" and "\0" directly if you want. 993 true and JSON false values, respectively. You can also use "\1" and
994 "\0" directly if you want.
951 995
952 blessed objects 996 blessed objects
953 Blessed objects are not directly representable in JSON. See the 997 Blessed objects are not directly representable in JSON, but
954 "allow_blessed" and "convert_blessed" methods on various options on 998 "JSON::XS" allows various ways of handling objects. See "OBJECT
955 how to deal with this: basically, you can choose between throwing an 999 SERIALISATION", below, for details.
956 exception, encoding the reference as if it weren't blessed, or
957 provide your own serialiser method.
958 1000
959 simple scalars 1001 simple scalars
960 Simple Perl scalars (any scalar that is not a reference) are the 1002 Simple Perl scalars (any scalar that is not a reference) are the
961 most difficult objects to encode: JSON::XS will encode undefined 1003 most difficult objects to encode: JSON::XS will encode undefined
962 scalars as JSON "null" values, scalars that have last been used in a 1004 scalars as JSON "null" values, scalars that have last been used in a
… …
997 which can differ to other languages). Also, your perl interpreter 1039 which can differ to other languages). Also, your perl interpreter
998 might expose extensions to the floating point numbers of your 1040 might expose extensions to the floating point numbers of your
999 platform, such as infinities or NaN's - these cannot be represented 1041 platform, such as infinities or NaN's - these cannot be represented
1000 in JSON, and it is an error to pass those in. 1042 in JSON, and it is an error to pass those in.
1001 1043
1044 OBJECT SERIALISATION
1045 As JSON cannot directly represent Perl objects, you have to choose
1046 between a pure JSON representation (without the ability to deserialise
1047 the object automatically again), and a nonstandard extension to the JSON
1048 syntax, tagged values.
1049
1050 SERIALISATION
1051 What happens when "JSON::XS" encounters a Perl object depends on the
1052 "allow_blessed", "convert_blessed" and "allow_tags" settings, which are
1053 used in this order:
1054
1055 1. "allow_tags" is enabled and the object has a "FREEZE" method.
1056 In this case, "JSON::XS" uses the Types::Serialiser object
1057 serialisation protocol to create a tagged JSON value, using a
1058 nonstandard extension to the JSON syntax.
1059
1060 This works by invoking the "FREEZE" method on the object, with the
1061 first argument being the object to serialise, and the second
1062 argument being the constant string "JSON" to distinguish it from
1063 other serialisers.
1064
1065 The "FREEZE" method can return any number of values (i.e. zero or
1066 more). These values and the paclkage/classname of the object will
1067 then be encoded as a tagged JSON value in the following format:
1068
1069 ("classname")[FREEZE return values...]
1070
1071 e.g.:
1072
1073 ("URI")["http://www.google.com/"]
1074 ("MyDate")[2013,10,29]
1075 ("ImageData::JPEG")["Z3...VlCg=="]
1076
1077 For example, the hypothetical "My::Object" "FREEZE" method might use
1078 the objects "type" and "id" members to encode the object:
1079
1080 sub My::Object::FREEZE {
1081 my ($self, $serialiser) = @_;
1082
1083 ($self->{type}, $self->{id})
1084 }
1085
1086 2. "convert_blessed" is enabled and the object has a "TO_JSON" method.
1087 In this case, the "TO_JSON" method of the object is invoked in
1088 scalar context. It must return a single scalar that can be directly
1089 encoded into JSON. This scalar replaces the object in the JSON text.
1090
1091 For example, the following "TO_JSON" method will convert all URI
1092 objects to JSON strings when serialised. The fatc that these values
1093 originally were URI objects is lost.
1094
1095 sub URI::TO_JSON {
1096 my ($uri) = @_;
1097 $uri->as_string
1098 }
1099
1100 3. "allow_blessed" is enabled.
1101 The object will be serialised as a JSON null value.
1102
1103 4. none of the above
1104 If none of the settings are enabled or the respective methods are
1105 missing, "JSON::XS" throws an exception.
1106
1107 DESERIALISATION
1108 For deserialisation there are only two cases to consider: either
1109 nonstandard tagging was used, in which case "allow_tags" decides, or
1110 objects cannot be automatically be deserialised, in which case you can
1111 use postprocessing or the "filter_json_object" or
1112 "filter_json_single_key_object" callbacks to get some real objects our
1113 of your JSON.
1114
1115 This section only considers the tagged value case: I a tagged JSON
1116 object is encountered during decoding and "allow_tags" is disabled, a
1117 parse error will result (as if tagged values were not part of the
1118 grammar).
1119
1120 If "allow_tags" is enabled, "JSON::XS" will look up the "THAW" method of
1121 the package/classname used during serialisation (it will not attempt to
1122 load the package as a Perl module). If there is no such method, the
1123 decoding will fail with an error.
1124
1125 Otherwise, the "THAW" method is invoked with the classname as first
1126 argument, the constant string "JSON" as second argument, and all the
1127 values from the JSON array (the values originally returned by the
1128 "FREEZE" method) as remaining arguments.
1129
1130 The method must then return the object. While technically you can return
1131 any Perl scalar, you might have to enable the "enable_nonref" setting to
1132 make that work in all cases, so better return an actual blessed
1133 reference.
1134
1135 As an example, let's implement a "THAW" function that regenerates the
1136 "My::Object" from the "FREEZE" example earlier:
1137
1138 sub My::Object::THAW {
1139 my ($class, $serialiser, $type, $id) = @_;
1140
1141 $class->new (type => $type, id => $id)
1142 }
1143
1002ENCODING/CODESET FLAG NOTES 1144ENCODING/CODESET FLAG NOTES
1003 The interested reader might have seen a number of flags that signify 1145 The interested reader might have seen a number of flags that signify
1004 encodings or codesets - "utf8", "latin1" and "ascii". There seems to be 1146 encodings or codesets - "utf8", "latin1" and "ascii". There seems to be
1005 some confusion on what these do, so here is a short comparison: 1147 some confusion on what these do, so here is a short comparison:
1006 1148
… …
1025 1167
1026 "utf8" flag disabled 1168 "utf8" flag disabled
1027 When "utf8" is disabled (the default), then "encode"/"decode" 1169 When "utf8" is disabled (the default), then "encode"/"decode"
1028 generate and expect Unicode strings, that is, characters with high 1170 generate and expect Unicode strings, that is, characters with high
1029 ordinal Unicode values (> 255) will be encoded as such characters, 1171 ordinal Unicode values (> 255) will be encoded as such characters,
1030 and likewise such characters are decoded as-is, no canges to them 1172 and likewise such characters are decoded as-is, no changes to them
1031 will be done, except "(re-)interpreting" them as Unicode codepoints 1173 will be done, except "(re-)interpreting" them as Unicode codepoints
1032 or Unicode characters, respectively (to Perl, these are the same 1174 or Unicode characters, respectively (to Perl, these are the same
1033 thing in strings unless you do funny/weird/dumb stuff). 1175 thing in strings unless you do funny/weird/dumb stuff).
1034 1176
1035 This is useful when you want to do the encoding yourself (e.g. when 1177 This is useful when you want to do the encoding yourself (e.g. when
… …
1045 will expect your input strings to be encoded as UTF-8, that is, no 1187 will expect your input strings to be encoded as UTF-8, that is, no
1046 "character" of the input string must have any value > 255, as UTF-8 1188 "character" of the input string must have any value > 255, as UTF-8
1047 does not allow that. 1189 does not allow that.
1048 1190
1049 The "utf8" flag therefore switches between two modes: disabled means 1191 The "utf8" flag therefore switches between two modes: disabled means
1050 you will get a Unicode string in Perl, enabled means you get an 1192 you will get a Unicode string in Perl, enabled means you get a UTF-8
1051 UTF-8 encoded octet/binary string in Perl. 1193 encoded octet/binary string in Perl.
1052 1194
1053 "latin1" or "ascii" flags enabled 1195 "latin1" or "ascii" flags enabled
1054 With "latin1" (or "ascii") enabled, "encode" will escape characters 1196 With "latin1" (or "ascii") enabled, "encode" will escape characters
1055 with ordinal values > 255 (> 127 with "ascii") and encode the 1197 with ordinal values > 255 (> 127 with "ascii") and encode the
1056 remaining characters as specified by the "utf8" flag. 1198 remaining characters as specified by the "utf8" flag.
… …
1143 characters as well - using "eval" naively simply *will* cause problems. 1285 characters as well - using "eval" naively simply *will* cause problems.
1144 1286
1145 Another problem is that some javascript implementations reserve some 1287 Another problem is that some javascript implementations reserve some
1146 property names for their own purposes (which probably makes them 1288 property names for their own purposes (which probably makes them
1147 non-ECMAscript-compliant). For example, Iceweasel reserves the 1289 non-ECMAscript-compliant). For example, Iceweasel reserves the
1148 "__proto__" property name for it's own purposes. 1290 "__proto__" property name for its own purposes.
1149 1291
1150 If that is a problem, you could parse try to filter the resulting JSON 1292 If that is a problem, you could parse try to filter the resulting JSON
1151 output for these property strings, e.g.: 1293 output for these property strings, e.g.:
1152 1294
1153 $json =~ s/"__proto__"\s*:/"__proto__renamed":/g; 1295 $json =~ s/"__proto__"\s*:/"__proto__renamed":/g;
1154 1296
1155 This works because "__proto__" is not valid outside of strings, so every 1297 This works because "__proto__" is not valid outside of strings, so every
1156 occurence of ""__proto__"\s*:" must be a string used as property name. 1298 occurrence of ""__proto__"\s*:" must be a string used as property name.
1157 1299
1158 If you know of other incompatibilities, please let me know. 1300 If you know of other incompatibilities, please let me know.
1159 1301
1160 JSON and YAML 1302 JSON and YAML
1161 You often hear that JSON is a subset of YAML. This is, however, a mass 1303 You often hear that JSON is a subset of YAML. This is, however, a mass
… …
1201 (which is not that difficult or long) and finally make YAML 1343 (which is not that difficult or long) and finally make YAML
1202 compatible to it, and educating users about the changes, instead of 1344 compatible to it, and educating users about the changes, instead of
1203 spreading lies about the real compatibility for many *years* and 1345 spreading lies about the real compatibility for many *years* and
1204 trying to silence people who point out that it isn't true. 1346 trying to silence people who point out that it isn't true.
1205 1347
1206 Addendum/2009: the YAML 1.2 spec is still incomaptible with JSON, 1348 Addendum/2009: the YAML 1.2 spec is still incompatible with JSON,
1207 even though the incompatibilities have been documented (and are 1349 even though the incompatibilities have been documented (and are
1208 known to Brian) for many years and the spec makes explicit claims 1350 known to Brian) for many years and the spec makes explicit claims
1209 that YAML is a superset of JSON. It would be so easy to fix, but 1351 that YAML is a superset of JSON. It would be so easy to fix, but
1210 apparently, bullying and corrupting userdata is so much easier. 1352 apparently, bullying people and corrupting userdata is so much
1353 easier.
1211 1354
1212 SPEED 1355 SPEED
1213 It seems that JSON::XS is surprisingly fast, as shown in the following 1356 It seems that JSON::XS is surprisingly fast, as shown in the following
1214 tables. They have been generated with the help of the "eg/bench" program 1357 tables. They have been generated with the help of the "eg/bench" program
1215 in the JSON::XS distribution, to make it easy to compare on your own 1358 in the JSON::XS distribution, to make it easy to compare on your own
… …
1311 to see whether you are vulnerable to some common attack vectors (which 1454 to see whether you are vulnerable to some common attack vectors (which
1312 really are browser design bugs, but it is still you who will have to 1455 really are browser design bugs, but it is still you who will have to
1313 deal with it, as major browser developers care only for features, not 1456 deal with it, as major browser developers care only for features, not
1314 about getting security right). 1457 about getting security right).
1315 1458
1459 "OLD" VS. "NEW" JSON (RFC4627 VS. RFC7159)
1460 JSON originally required JSON texts to represent an array or object -
1461 scalar values were explicitly not allowed. This has changed, and
1462 versions of JSON::XS beginning with 4.0 reflect this by allowing scalar
1463 values by default.
1464
1465 One reason why one might not want this is that this removes a
1466 fundamental property of JSON texts, namely that they are self-delimited
1467 and self-contained, or in other words, you could take any number of
1468 "old" JSON texts and paste them together, and the result would be
1469 unambiguously parseable:
1470
1471 [1,3]{"k":5}[][null] # four JSON texts, without doubt
1472
1473 By allowing scalars, this property is lost: in the following example, is
1474 this one JSON text (the number 12) or two JSON texts (the numbers 1 and
1475 2):
1476
1477 12 # could be 12, or 1 and 2
1478
1479 Another lost property of "old" JSON is that no lookahead is required to
1480 know the end of a JSON text, i.e. the JSON text definitely ended at the
1481 last "]" or "}" character, there was no need to read extra characters.
1482
1483 For example, a viable network protocol with "old" JSON was to simply
1484 exchange JSON texts without delimiter. For "new" JSON, you have to use a
1485 suitable delimiter (such as a newline) after every JSON text or ensure
1486 you never encode/decode scalar values.
1487
1488 Most protocols do work by only transferring arrays or objects, and the
1489 easiest way to avoid problems with the "new" JSON definition is to
1490 explicitly disallow scalar values in your encoder and decoder:
1491
1492 $json_coder = JSON::XS->new->allow_nonref (0)
1493
1494 This is a somewhat unhappy situation, and the blame can fully be put on
1495 JSON's inmventor, Douglas Crockford, who unilaterally changed the format
1496 in 2006 without consulting the IETF, forcing the IETF to either fork the
1497 format or go with it (as I was told, the IETF wasn't amused).
1498
1499RELATIONSHIP WITH I-JSON
1500 JSON is a somewhat sloppily-defined format - it carries around obvious
1501 Javascript baggage, such as not really defining number range, probably
1502 because Javascript only has one type of numbers: IEEE 64 bit floats
1503 ("binary64").
1504
1505 For this reaosn, RFC7493 defines "Internet JSON", which is a restricted
1506 subset of JSON that is supposedly more interoperable on the internet.
1507
1508 While "JSON::XS" does not offer specific support for I-JSON, it of
1509 course accepts valid I-JSON and by default implements some of the
1510 limitations of I-JSON, such as parsing numbers as perl numbers, which
1511 are usually a superset of binary64 numbers.
1512
1513 To generate I-JSON, follow these rules:
1514
1515 * always generate UTF-8
1516
1517 I-JSON must be encoded in UTF-8, the default for "encode_json".
1518
1519 * numbers should be within IEEE 754 binary64 range
1520
1521 Basically all existing perl installations use binary64 to represent
1522 floating point numbers, so all you need to do is to avoid large
1523 integers.
1524
1525 * objects must not have duplicate keys
1526
1527 This is trivially done, as "JSON::XS" does not allow duplicate keys.
1528
1529 * do not generate scalar JSON texts, use "->allow_nonref (0)"
1530
1531 I-JSON strongly requests you to only encode arrays and objects into
1532 JSON.
1533
1534 * times should be strings in ISO 8601 format
1535
1536 There are a myriad of modules on CPAN dealing with ISO 8601 - search
1537 for "ISO8601" on CPAN and use one.
1538
1539 * encode binary data as base64
1540
1541 While it's tempting to just dump binary data as a string (and let
1542 "JSON::XS" do the escaping), for I-JSON, it's *recommended* to
1543 encode binary data as base64.
1544
1545 There are some other considerations - read RFC7493 for the details if
1546 interested.
1547
1548INTEROPERABILITY WITH OTHER MODULES
1549 "JSON::XS" uses the Types::Serialiser module to provide boolean
1550 constants. That means that the JSON true and false values will be
1551 comaptible to true and false values of other modules that do the same,
1552 such as JSON::PP and CBOR::XS.
1553
1554INTEROPERABILITY WITH OTHER JSON DECODERS
1555 As long as you only serialise data that can be directly expressed in
1556 JSON, "JSON::XS" is incapable of generating invalid JSON output (modulo
1557 bugs, but "JSON::XS" has found more bugs in the official JSON testsuite
1558 (1) than the official JSON testsuite has found in "JSON::XS" (0)).
1559
1560 When you have trouble decoding JSON generated by this module using other
1561 decoders, then it is very likely that you have an encoding mismatch or
1562 the other decoder is broken.
1563
1564 When decoding, "JSON::XS" is strict by default and will likely catch all
1565 errors. There are currently two settings that change this: "relaxed"
1566 makes "JSON::XS" accept (but not generate) some non-standard extensions,
1567 and "allow_tags" will allow you to encode and decode Perl objects, at
1568 the cost of not outputting valid JSON anymore.
1569
1570 TAGGED VALUE SYNTAX AND STANDARD JSON EN/DECODERS
1571 When you use "allow_tags" to use the extended (and also nonstandard and
1572 invalid) JSON syntax for serialised objects, and you still want to
1573 decode the generated When you want to serialise objects, you can run a
1574 regex to replace the tagged syntax by standard JSON arrays (it only
1575 works for "normal" package names without comma, newlines or single
1576 colons). First, the readable Perl version:
1577
1578 # if your FREEZE methods return no values, you need this replace first:
1579 $json =~ s/\( \s* (" (?: [^\\":,]+|\\.|::)* ") \s* \) \s* \[\s*\]/[$1]/gx;
1580
1581 # this works for non-empty constructor arg lists:
1582 $json =~ s/\( \s* (" (?: [^\\":,]+|\\.|::)* ") \s* \) \s* \[/[$1,/gx;
1583
1584 And here is a less readable version that is easy to adapt to other
1585 languages:
1586
1587 $json =~ s/\(\s*("([^\\":,]+|\\.|::)*")\s*\)\s*\[/[$1,/g;
1588
1589 Here is an ECMAScript version (same regex):
1590
1591 json = json.replace (/\(\s*("([^\\":,]+|\\.|::)*")\s*\)\s*\[/g, "[$1,");
1592
1593 Since this syntax converts to standard JSON arrays, it might be hard to
1594 distinguish serialised objects from normal arrays. You can prepend a
1595 "magic number" as first array element to reduce chances of a collision:
1596
1597 $json =~ s/\(\s*("([^\\":,]+|\\.|::)*")\s*\)\s*\[/["XU1peReLzT4ggEllLanBYq4G9VzliwKF",$1,/g;
1598
1599 And after decoding the JSON text, you could walk the data structure
1600 looking for arrays with a first element of
1601 "XU1peReLzT4ggEllLanBYq4G9VzliwKF".
1602
1603 The same approach can be used to create the tagged format with another
1604 encoder. First, you create an array with the magic string as first
1605 member, the classname as second, and constructor arguments last, encode
1606 it as part of your JSON structure, and then:
1607
1608 $json =~ s/\[\s*"XU1peReLzT4ggEllLanBYq4G9VzliwKF"\s*,\s*("([^\\":,]+|\\.|::)*")\s*,/($1)[/g;
1609
1610 Again, this has some limitations - the magic string must not be encoded
1611 with character escapes, and the constructor arguments must be non-empty.
1612
1316THREADS 1613(I-)THREADS
1317 This module is *not* guaranteed to be thread safe and there are no plans 1614 This module is *not* guaranteed to be ithread (or MULTIPLICITY-) safe
1318 to change this until Perl gets thread support (as opposed to the 1615 and there are no plans to change this. Note that perl's builtin
1319 horribly slow so-called "threads" which are simply slow and bloated 1616 so-called threads/ithreads are officially deprecated and should not be
1320 process simulations - use fork, it's *much* faster, cheaper, better). 1617 used.
1321 1618
1322 (It might actually work, but you have been warned). 1619THE PERILS OF SETLOCALE
1620 Sometimes people avoid the Perl locale support and directly call the
1621 system's setlocale function with "LC_ALL".
1622
1623 This breaks both perl and modules such as JSON::XS, as stringification
1624 of numbers no longer works correctly (e.g. "$x = 0.1; print "$x"+1"
1625 might print 1, and JSON::XS might output illegal JSON as JSON::XS relies
1626 on perl to stringify numbers).
1627
1628 The solution is simple: don't call "setlocale", or use it for only those
1629 categories you need, such as "LC_MESSAGES" or "LC_CTYPE".
1630
1631 If you need "LC_NUMERIC", you should enable it only around the code that
1632 actually needs it (avoiding stringification of numbers), and restore it
1633 afterwards.
1634
1635SOME HISTORY
1636 At the time this module was created there already were a number of JSON
1637 modules available on CPAN, so what was the reason to write yet another
1638 JSON module? While it seems there are many JSON modules, none of them
1639 correctly handled all corner cases, and in most cases their maintainers
1640 are unresponsive, gone missing, or not listening to bug reports for
1641 other reasons.
1642
1643 Beginning with version 2.0 of the JSON module, when both JSON and
1644 JSON::XS are installed, then JSON will fall back on JSON::XS (this can
1645 be overridden) with no overhead due to emulation (by inheriting
1646 constructor and methods). If JSON::XS is not available, it will fall
1647 back to the compatible JSON::PP module as backend, so using JSON instead
1648 of JSON::XS gives you a portable JSON API that can be fast when you need
1649 it and doesn't require a C compiler when that is a problem.
1650
1651 Somewhere around version 3, this module was forked into
1652 "Cpanel::JSON::XS", because its maintainer had serious trouble
1653 understanding JSON and insisted on a fork with many bugs "fixed" that
1654 weren't actually bugs, while spreading FUD about this module without
1655 actually giving any details on his accusations. You be the judge, but in
1656 my personal opinion, if you want quality, you will stay away from
1657 dangerous forks like that.
1323 1658
1324BUGS 1659BUGS
1325 While the goal of this module is to be correct, that unfortunately does 1660 While the goal of this module is to be correct, that unfortunately does
1326 not mean it's bug-free, only that I think its design is bug-free. If you 1661 not mean it's bug-free, only that I think its design is bug-free. If you
1327 keep reporting bugs they will be fixed swiftly, though. 1662 keep reporting bugs they will be fixed swiftly, though.

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines