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.42 by root, Thu Aug 17 03:47:54 2017 UTC

… …
36 JSON::XS are installed, then JSON will fall back on JSON::XS (this can 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 37 be overridden) with no overhead due to emulation (by inheriting
38 constructor and methods). If JSON::XS is not available, it will fall 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 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 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. 41 it and doesn't require a C compiler when that is a problem.
42 42
43 As this is the n-th-something JSON module on CPAN, what was the reason 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 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 45 modules, none of them correctly handle all corner cases, and in most
46 cases their maintainers are unresponsive, gone missing, or not listening 46 cases their maintainers are unresponsive, gone missing, or not listening
… …
77 too. 77 too.
78 78
79 * simple to use 79 * simple to use
80 80
81 This module has both a simple functional interface as well as an 81 This module has both a simple functional interface as well as an
82 object oriented interface interface. 82 object oriented interface.
83 83
84 * reasonably versatile output formats 84 * reasonably versatile output formats
85 85
86 You can choose between the most compact guaranteed-single-line 86 You can choose between the most compact guaranteed-single-line
87 format possible (nice for simple line-based protocols), a pure-ASCII 87 format possible (nice for simple line-based protocols), a pure-ASCII
… …
112 This function call is functionally identical to: 112 This function call is functionally identical to:
113 113
114 $perl_scalar = JSON::XS->new->utf8->decode ($json_text) 114 $perl_scalar = JSON::XS->new->utf8->decode ($json_text)
115 115
116 Except being faster. 116 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 117
127A FEW NOTES ON UNICODE AND PERL 118A FEW NOTES ON UNICODE AND PERL
128 Since this often leads to confusion, here are a few very clear words on 119 Since this often leads to confusion, here are a few very clear words on
129 how Unicode works in Perl, modulo bugs. 120 how Unicode works in Perl, modulo bugs.
130 121
… …
361 [ 352 [
362 1, # this comment not allowed in JSON 353 1, # this comment not allowed in JSON
363 # neither this one... 354 # neither this one...
364 ] 355 ]
365 356
357 * literal ASCII TAB characters in strings
358
359 Literal ASCII TAB characters are now allowed in strings (and
360 treated as "\t").
361
362 [
363 "Hello\tWorld",
364 "Hello<TAB>World", # literal <TAB> would not normally be allowed
365 ]
366
366 $json = $json->canonical ([$enable]) 367 $json = $json->canonical ([$enable])
367 $enabled = $json->get_canonical 368 $enabled = $json->get_canonical
368 If $enable is true (or missing), then the "encode" method will 369 If $enable is true (or missing), then the "encode" method will
369 output JSON objects by sorting their keys. This is adding a 370 output JSON objects by sorting their keys. This is adding a
370 comparatively high overhead. 371 comparatively high overhead.
371 372
372 If $enable is false, then the "encode" method will output key-value 373 If $enable is false, then the "encode" method will output key-value
373 pairs in the order Perl stores them (which will likely change 374 pairs in the order Perl stores them (which will likely change
374 between runs of the same script). 375 between runs of the same script, and can change even within the same
376 run from 5.18 onwards).
375 377
376 This option is useful if you want the same data structure to be 378 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 379 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 380 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 381 contains the same data, as key-value pairs have no inherent ordering
… …
416 recommended to leave it off unless you know your communications 418 recommended to leave it off unless you know your communications
417 partner. 419 partner.
418 420
419 $json = $json->allow_blessed ([$enable]) 421 $json = $json->allow_blessed ([$enable])
420 $enabled = $json->get_allow_blessed 422 $enabled = $json->get_allow_blessed
423 See "OBJECT SERIALISATION" for details.
424
421 If $enable is true (or missing), then the "encode" method will not 425 If $enable is true (or missing), then the "encode" method will not
422 barf when it encounters a blessed reference. Instead, the value of 426 barf when it encounters a blessed reference that it cannot convert
423 the convert_blessed option will decide whether "null" 427 otherwise. Instead, a JSON "null" value is encoded instead of the
424 ("convert_blessed" disabled or no "TO_JSON" method found) or a 428 object.
425 representation of the object ("convert_blessed" enabled and
426 "TO_JSON" method found) is being encoded. Has no effect on "decode".
427 429
428 If $enable is false (the default), then "encode" will throw an 430 If $enable is false (the default), then "encode" will throw an
429 exception when it encounters a blessed object. 431 exception when it encounters a blessed object that it cannot convert
432 otherwise.
433
434 This setting has no effect on "decode".
430 435
431 $json = $json->convert_blessed ([$enable]) 436 $json = $json->convert_blessed ([$enable])
432 $enabled = $json->get_convert_blessed 437 $enabled = $json->get_convert_blessed
438 See "OBJECT SERIALISATION" for details.
439
433 If $enable is true (or missing), then "encode", upon encountering a 440 If $enable is true (or missing), then "encode", upon encountering a
434 blessed object, will check for the availability of the "TO_JSON" 441 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 442 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 443 context and the resulting scalar will be encoded instead of the
437 object. If no "TO_JSON" method is found, the value of 444 object.
438 "allow_blessed" will decide what to do.
439 445
440 The "TO_JSON" method may safely call die if it wants. If "TO_JSON" 446 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 447 returns other blessed objects, those will be handled in the same
442 way. "TO_JSON" must take care of not causing an endless recursion 448 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 449 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 450 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 451 the object) are usually in upper case letters and to avoid
446 collisions with any "to_json" function or method. 452 collisions with any "to_json" function or method.
447 453
448 This setting does not yet influence "decode" in any way, but in the 454 If $enable is false (the default), then "encode" will not consider
449 future, global hooks might get installed that influence "decode" and 455 this type of conversion.
450 are enabled by this setting.
451 456
452 If $enable is false, then the "allow_blessed" setting will decide 457 This setting has no effect on "decode".
453 what to do when a blessed object is found. 458
459 $json = $json->allow_tags ([$enable])
460 $enabled = $json->allow_tags
461 See "OBJECT SERIALISATION" for details.
462
463 If $enable is true (or missing), then "encode", upon encountering a
464 blessed object, will check for the availability of the "FREEZE"
465 method on the object's class. If found, it will be used to serialise
466 the object into a nonstandard tagged JSON value (that JSON decoders
467 cannot decode).
468
469 It also causes "decode" to parse such tagged JSON values and
470 deserialise them via a call to the "THAW" method.
471
472 If $enable is false (the default), then "encode" will not consider
473 this type of conversion, and tagged JSON values will cause a parse
474 error in "decode", as if tags were not part of the grammar.
454 475
455 $json = $json->filter_json_object ([$coderef->($hashref)]) 476 $json = $json->filter_json_object ([$coderef->($hashref)])
456 When $coderef is specified, it will be called from "decode" each 477 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 478 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 479 the newly-created hash. If the code references returns a single
… …
594 615
595 See SECURITY CONSIDERATIONS, below, for more info on why this is 616 See SECURITY CONSIDERATIONS, below, for more info on why this is
596 useful. 617 useful.
597 618
598 $json_text = $json->encode ($perl_scalar) 619 $json_text = $json->encode ($perl_scalar)
599 Converts the given Perl data structure (a simple scalar or a 620 Converts the given Perl value or data structure to its JSON
600 reference to a hash or array) to its JSON representation. Simple 621 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 622
607 $perl_scalar = $json->decode ($json_text) 623 $perl_scalar = $json->decode ($json_text)
608 The opposite of "encode": expects a JSON text and tries to parse it, 624 The opposite of "encode": expects a JSON text and tries to parse it,
609 returning the resulting simple scalar or reference. Croaks on error. 625 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 626
615 ($perl_scalar, $characters) = $json->decode_prefix ($json_text) 627 ($perl_scalar, $characters) = $json->decode_prefix ($json_text)
616 This works like the "decode" method, but instead of raising an 628 This works like the "decode" method, but instead of raising an
617 exception when there is trailing garbage after the first JSON 629 exception when there is trailing garbage after the first JSON
618 object, it will silently stop parsing there and return the number of 630 object, it will silently stop parsing there and return the number of
619 characters consumed so far. 631 characters consumed so far.
620 632
621 This is useful if your JSON texts are not delimited by an outer 633 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. 634 protocol and you need to know where the JSON text ends.
624 635
625 JSON::XS->new->decode_prefix ("[1] the tail") 636 JSON::XS->new->decode_prefix ("[1] the tail")
626 => ([], 3) 637 => ([1], 3)
627 638
628INCREMENTAL PARSING 639INCREMENTAL PARSING
629 In some cases, there is the need for incremental parsing of JSON texts. 640 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 641 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 642 data structure in memory at one time, it does allow you to parse a JSON
… …
636 calls). 647 calls).
637 648
638 JSON::XS will only attempt to parse the JSON text once it is sure it has 649 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 650 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 651 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. 652 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 653 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 654 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 655 resource limits (e.g. "max_size") to ensure the parser will stop parsing
645 in the presence if syntax errors. 656 in the presence if syntax errors.
646 657
… …
660 671
661 If the method is called in scalar context, then it will try to 672 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 673 extract exactly *one* JSON object. If that is successful, it will
663 return this object, otherwise it will return "undef". If there is a 674 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 675 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 676 can then use "incr_skip" to skip the erroneous part). This is the
666 most common way of using the method. 677 most common way of using the method.
667 678
668 And finally, in list context, it will try to extract as many objects 679 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 680 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 681 otherwise. For this to work, there must be no separators (other than
671 JSON objects or arrays, instead they must be concatenated 682 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 683 concatenated back-to-back. If an error occurs, an exception will be
673 the scalar context case. Note that in this case, any 684 raised as in the scalar context case. Note that in this case, any
674 previously-parsed JSON texts will be lost. 685 previously-parsed JSON texts will be lost.
675 686
676 Example: Parse some JSON arrays/objects in a given string and return 687 Example: Parse some JSON arrays/objects in a given string and return
677 them. 688 them.
678 689
… …
686 function (I mean it. although in simple tests it might actually 697 function (I mean it. although in simple tests it might actually
687 work, it *will* fail under real world conditions). As a special 698 work, it *will* fail under real world conditions). As a special
688 exception, you can also call this method before having parsed 699 exception, you can also call this method before having parsed
689 anything. 700 anything.
690 701
702 That means you can only use this function to look at or manipulate
703 text before or after complete JSON objects, not while the parser is
704 in the middle of parsing a JSON object.
705
691 This function is useful in two cases: a) finding the trailing text 706 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 707 after a JSON object or b) parsing multiple JSON objects separated by
693 non-JSON text (such as commas). 708 non-JSON text (such as commas).
694 709
695 $json->incr_skip 710 $json->incr_skip
… …
698 "incr_parse" died, in which case the input buffer and incremental 713 "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 714 parser state is left unchanged, to skip the text parsed so far and
700 to reset the parse state. 715 to reset the parse state.
701 716
702 The difference to "incr_reset" is that only text until the parse 717 The difference to "incr_reset" is that only text until the parse
703 error occured is removed. 718 error occurred is removed.
704 719
705 $json->incr_reset 720 $json->incr_reset
706 This completely resets the incremental parser, that is, after this 721 This completely resets the incremental parser, that is, after this
707 call, it will be as if the parser had never parsed anything. 722 call, it will be as if the parser had never parsed anything.
708 723
… …
892 If the number consists of digits only, JSON::XS will try to 907 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 908 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 909 represent it as a numeric (floating point) value if that is possible
895 without loss of precision. Otherwise it will preserve the number as 910 without loss of precision. Otherwise it will preserve the number as
896 a string value (in which case you lose roundtripping ability, as the 911 a string value (in which case you lose roundtripping ability, as the
897 JSON number will be re-encoded toa JSON string). 912 JSON number will be re-encoded to a JSON string).
898 913
899 Numbers containing a fractional or exponential part will always be 914 Numbers containing a fractional or exponential part will always be
900 represented as numeric (floating point) values, possibly at a loss 915 represented as numeric (floating point) values, possibly at a loss
901 of precision (in which case you might lose perfect roundtripping 916 of precision (in which case you might lose perfect roundtripping
902 ability, but the JSON number will still be re-encoded as a JSON 917 ability, but the JSON number will still be re-encoded as a JSON
903 number). 918 number).
904 919
905 Note that precision is not accuracy - binary floating point values 920 Note that precision is not accuracy - binary floating point values
906 cannot represent most decimal fractions exactly, and when converting 921 cannot represent most decimal fractions exactly, and when converting
907 from and to floating point, JSON::XS only guarantees precision up to 922 from and to floating point, JSON::XS only guarantees precision up to
908 but not including the leats significant bit. 923 but not including the least significant bit.
909 924
910 true, false 925 true, false
911 These JSON atoms become "JSON::XS::true" and "JSON::XS::false", 926 These JSON atoms become "Types::Serialiser::true" and
912 respectively. They are overloaded to act almost exactly like the 927 "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 928 almost exactly like the numbers 1 and 0. You can check whether a
914 using the "JSON::XS::is_bool" function. 929 scalar is a JSON boolean by using the "Types::Serialiser::is_bool"
930 function (after "use Types::Serialier", of course).
915 931
916 null 932 null
917 A JSON null atom becomes "undef" in Perl. 933 A JSON null atom becomes "undef" in Perl.
934
935 shell-style comments ("# *text*")
936 As a nonstandard extension to the JSON syntax that is enabled by the
937 "relaxed" setting, shell-style comments are allowed. They can start
938 anywhere outside strings and go till the end of the line.
939
940 tagged values ("(*tag*)*value*").
941 Another nonstandard extension to the JSON syntax, enabled with the
942 "allow_tags" setting, are tagged values. In this implementation, the
943 *tag* must be a perl package/class name encoded as a JSON string,
944 and the *value* must be a JSON array encoding optional constructor
945 arguments.
946
947 See "OBJECT SERIALISATION", below, for details.
918 948
919 PERL -> JSON 949 PERL -> JSON
920 The mapping from Perl to JSON is slightly more difficult, as Perl is a 950 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 951 truly typeless language, so we can only guess which JSON type is meant
922 by a Perl value. 952 by a Perl value.
923 953
924 hash references 954 hash references
925 Perl hash references become JSON objects. As there is no inherent 955 Perl hash references become JSON objects. As there is no inherent
926 ordering in hash keys (or JSON objects), they will usually be 956 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 957 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 958 hash keys (determined by the *canonical* flag), so the same
929 program. JSON::XS can optionally sort the hash keys (determined by 959 datastructure will serialise to the same JSON text (given same
930 the *canonical* flag), so the same datastructure will serialise to 960 settings and version of JSON::XS), but this incurs a runtime
931 the same JSON text (given same settings and version of JSON::XS), 961 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. 962 some JSON text against another for equality.
933 when you want to compare some JSON text against another for
934 equality.
935 963
936 array references 964 array references
937 Perl array references become JSON arrays. 965 Perl array references become JSON arrays.
938 966
939 other references 967 other references
940 Other unblessed references are generally not allowed and will cause 968 Other unblessed references are generally not allowed and will cause
941 an exception to be thrown, except for references to the integers 0 969 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 970 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 971
972 Since "JSON::XS" uses the boolean model from Types::Serialiser, you
973 can also "use Types::Serialiser" and then use
974 "Types::Serialiser::false" and "Types::Serialiser::true" to improve
944 readability. 975 readability.
945 976
977 use Types::Serialiser;
946 encode_json [\0, JSON::XS::true] # yields [false,true] 978 encode_json [\0, Types::Serialiser::true] # yields [false,true]
947 979
948 JSON::XS::true, JSON::XS::false 980 Types::Serialiser::true, Types::Serialiser::false
949 These special values become JSON true and JSON false values, 981 These special values from the Types::Serialiser module become JSON
950 respectively. You can also use "\1" and "\0" directly if you want. 982 true and JSON false values, respectively. You can also use "\1" and
983 "\0" directly if you want.
951 984
952 blessed objects 985 blessed objects
953 Blessed objects are not directly representable in JSON. See the 986 Blessed objects are not directly representable in JSON, but
954 "allow_blessed" and "convert_blessed" methods on various options on 987 "JSON::XS" allows various ways of handling objects. See "OBJECT
955 how to deal with this: basically, you can choose between throwing an 988 SERIALISATION", below, for details.
956 exception, encoding the reference as if it weren't blessed, or
957 provide your own serialiser method.
958 989
959 simple scalars 990 simple scalars
960 Simple Perl scalars (any scalar that is not a reference) are the 991 Simple Perl scalars (any scalar that is not a reference) are the
961 most difficult objects to encode: JSON::XS will encode undefined 992 most difficult objects to encode: JSON::XS will encode undefined
962 scalars as JSON "null" values, scalars that have last been used in a 993 scalars as JSON "null" values, scalars that have last been used in a
… …
997 which can differ to other languages). Also, your perl interpreter 1028 which can differ to other languages). Also, your perl interpreter
998 might expose extensions to the floating point numbers of your 1029 might expose extensions to the floating point numbers of your
999 platform, such as infinities or NaN's - these cannot be represented 1030 platform, such as infinities or NaN's - these cannot be represented
1000 in JSON, and it is an error to pass those in. 1031 in JSON, and it is an error to pass those in.
1001 1032
1033 OBJECT SERIALISATION
1034 As JSON cannot directly represent Perl objects, you have to choose
1035 between a pure JSON representation (without the ability to deserialise
1036 the object automatically again), and a nonstandard extension to the JSON
1037 syntax, tagged values.
1038
1039 SERIALISATION
1040 What happens when "JSON::XS" encounters a Perl object depends on the
1041 "allow_blessed", "convert_blessed" and "allow_tags" settings, which are
1042 used in this order:
1043
1044 1. "allow_tags" is enabled and the object has a "FREEZE" method.
1045 In this case, "JSON::XS" uses the Types::Serialiser object
1046 serialisation protocol to create a tagged JSON value, using a
1047 nonstandard extension to the JSON syntax.
1048
1049 This works by invoking the "FREEZE" method on the object, with the
1050 first argument being the object to serialise, and the second
1051 argument being the constant string "JSON" to distinguish it from
1052 other serialisers.
1053
1054 The "FREEZE" method can return any number of values (i.e. zero or
1055 more). These values and the paclkage/classname of the object will
1056 then be encoded as a tagged JSON value in the following format:
1057
1058 ("classname")[FREEZE return values...]
1059
1060 e.g.:
1061
1062 ("URI")["http://www.google.com/"]
1063 ("MyDate")[2013,10,29]
1064 ("ImageData::JPEG")["Z3...VlCg=="]
1065
1066 For example, the hypothetical "My::Object" "FREEZE" method might use
1067 the objects "type" and "id" members to encode the object:
1068
1069 sub My::Object::FREEZE {
1070 my ($self, $serialiser) = @_;
1071
1072 ($self->{type}, $self->{id})
1073 }
1074
1075 2. "convert_blessed" is enabled and the object has a "TO_JSON" method.
1076 In this case, the "TO_JSON" method of the object is invoked in
1077 scalar context. It must return a single scalar that can be directly
1078 encoded into JSON. This scalar replaces the object in the JSON text.
1079
1080 For example, the following "TO_JSON" method will convert all URI
1081 objects to JSON strings when serialised. The fatc that these values
1082 originally were URI objects is lost.
1083
1084 sub URI::TO_JSON {
1085 my ($uri) = @_;
1086 $uri->as_string
1087 }
1088
1089 3. "allow_blessed" is enabled.
1090 The object will be serialised as a JSON null value.
1091
1092 4. none of the above
1093 If none of the settings are enabled or the respective methods are
1094 missing, "JSON::XS" throws an exception.
1095
1096 DESERIALISATION
1097 For deserialisation there are only two cases to consider: either
1098 nonstandard tagging was used, in which case "allow_tags" decides, or
1099 objects cannot be automatically be deserialised, in which case you can
1100 use postprocessing or the "filter_json_object" or
1101 "filter_json_single_key_object" callbacks to get some real objects our
1102 of your JSON.
1103
1104 This section only considers the tagged value case: I a tagged JSON
1105 object is encountered during decoding and "allow_tags" is disabled, a
1106 parse error will result (as if tagged values were not part of the
1107 grammar).
1108
1109 If "allow_tags" is enabled, "JSON::XS" will look up the "THAW" method of
1110 the package/classname used during serialisation (it will not attempt to
1111 load the package as a Perl module). If there is no such method, the
1112 decoding will fail with an error.
1113
1114 Otherwise, the "THAW" method is invoked with the classname as first
1115 argument, the constant string "JSON" as second argument, and all the
1116 values from the JSON array (the values originally returned by the
1117 "FREEZE" method) as remaining arguments.
1118
1119 The method must then return the object. While technically you can return
1120 any Perl scalar, you might have to enable the "enable_nonref" setting to
1121 make that work in all cases, so better return an actual blessed
1122 reference.
1123
1124 As an example, let's implement a "THAW" function that regenerates the
1125 "My::Object" from the "FREEZE" example earlier:
1126
1127 sub My::Object::THAW {
1128 my ($class, $serialiser, $type, $id) = @_;
1129
1130 $class->new (type => $type, id => $id)
1131 }
1132
1002ENCODING/CODESET FLAG NOTES 1133ENCODING/CODESET FLAG NOTES
1003 The interested reader might have seen a number of flags that signify 1134 The interested reader might have seen a number of flags that signify
1004 encodings or codesets - "utf8", "latin1" and "ascii". There seems to be 1135 encodings or codesets - "utf8", "latin1" and "ascii". There seems to be
1005 some confusion on what these do, so here is a short comparison: 1136 some confusion on what these do, so here is a short comparison:
1006 1137
… …
1025 1156
1026 "utf8" flag disabled 1157 "utf8" flag disabled
1027 When "utf8" is disabled (the default), then "encode"/"decode" 1158 When "utf8" is disabled (the default), then "encode"/"decode"
1028 generate and expect Unicode strings, that is, characters with high 1159 generate and expect Unicode strings, that is, characters with high
1029 ordinal Unicode values (> 255) will be encoded as such characters, 1160 ordinal Unicode values (> 255) will be encoded as such characters,
1030 and likewise such characters are decoded as-is, no canges to them 1161 and likewise such characters are decoded as-is, no changes to them
1031 will be done, except "(re-)interpreting" them as Unicode codepoints 1162 will be done, except "(re-)interpreting" them as Unicode codepoints
1032 or Unicode characters, respectively (to Perl, these are the same 1163 or Unicode characters, respectively (to Perl, these are the same
1033 thing in strings unless you do funny/weird/dumb stuff). 1164 thing in strings unless you do funny/weird/dumb stuff).
1034 1165
1035 This is useful when you want to do the encoding yourself (e.g. when 1166 This is useful when you want to do the encoding yourself (e.g. when
… …
1143 characters as well - using "eval" naively simply *will* cause problems. 1274 characters as well - using "eval" naively simply *will* cause problems.
1144 1275
1145 Another problem is that some javascript implementations reserve some 1276 Another problem is that some javascript implementations reserve some
1146 property names for their own purposes (which probably makes them 1277 property names for their own purposes (which probably makes them
1147 non-ECMAscript-compliant). For example, Iceweasel reserves the 1278 non-ECMAscript-compliant). For example, Iceweasel reserves the
1148 "__proto__" property name for it's own purposes. 1279 "__proto__" property name for its own purposes.
1149 1280
1150 If that is a problem, you could parse try to filter the resulting JSON 1281 If that is a problem, you could parse try to filter the resulting JSON
1151 output for these property strings, e.g.: 1282 output for these property strings, e.g.:
1152 1283
1153 $json =~ s/"__proto__"\s*:/"__proto__renamed":/g; 1284 $json =~ s/"__proto__"\s*:/"__proto__renamed":/g;
1154 1285
1155 This works because "__proto__" is not valid outside of strings, so every 1286 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. 1287 occurrence of ""__proto__"\s*:" must be a string used as property name.
1157 1288
1158 If you know of other incompatibilities, please let me know. 1289 If you know of other incompatibilities, please let me know.
1159 1290
1160 JSON and YAML 1291 JSON and YAML
1161 You often hear that JSON is a subset of YAML. This is, however, a mass 1292 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 1332 (which is not that difficult or long) and finally make YAML
1202 compatible to it, and educating users about the changes, instead of 1333 compatible to it, and educating users about the changes, instead of
1203 spreading lies about the real compatibility for many *years* and 1334 spreading lies about the real compatibility for many *years* and
1204 trying to silence people who point out that it isn't true. 1335 trying to silence people who point out that it isn't true.
1205 1336
1206 Addendum/2009: the YAML 1.2 spec is still incomaptible with JSON, 1337 Addendum/2009: the YAML 1.2 spec is still incompatible with JSON,
1207 even though the incompatibilities have been documented (and are 1338 even though the incompatibilities have been documented (and are
1208 known to Brian) for many years and the spec makes explicit claims 1339 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 1340 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. 1341 apparently, bullying people and corrupting userdata is so much
1342 easier.
1211 1343
1212 SPEED 1344 SPEED
1213 It seems that JSON::XS is surprisingly fast, as shown in the following 1345 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 1346 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 1347 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 1443 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 1444 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 1445 deal with it, as major browser developers care only for features, not
1314 about getting security right). 1446 about getting security right).
1315 1447
1448"OLD" VS. "NEW" JSON (RFC 4627 VS. RFC 7159)
1449 TL;DR: Due to security concerns, JSON::XS will not allow scalar data in
1450 JSON texts by default - you need to create your own JSON::XS object and
1451 enable "allow_nonref":
1452
1453 my $json = JSON::XS->new->allow_nonref;
1454
1455 $text = $json->encode ($data);
1456 $data = $json->decode ($text);
1457
1458 The long version: JSON being an important and supposedly stable format,
1459 the IETF standardised it as RFC 4627 in 2006. Unfortunately, the
1460 inventor of JSON, Dougles Crockford, unilaterally changed the definition
1461 of JSON in javascript. Rather than create a fork, the IETF decided to
1462 standardise the new syntax (apparently, so Iw as told, without finding
1463 it very amusing).
1464
1465 The biggest difference between thed original JSON and the new JSON is
1466 that the new JSON supports scalars (anything other than arrays and
1467 objects) at the toplevel of a JSON text. While this is strictly
1468 backwards compatible to older versions, it breaks a number of protocols
1469 that relied on sending JSON back-to-back, and is a minor security
1470 concern.
1471
1472 For example, imagine you have two banks communicating, and on one side,
1473 trhe JSON coder gets upgraded. Two messages, such as 10 and 1000 might
1474 then be confused to mean 101000, something that couldn't happen in the
1475 original JSON, because niether of these messages would be valid JSON.
1476
1477 If one side accepts these messages, then an upgrade in the coder on
1478 either side could result in this becoming exploitable.
1479
1480 This module has always allowed these messages as an optional extension,
1481 by default disabled. The security concerns are the reason why the
1482 default is still disabled, but future versions might/will likely upgrade
1483 to the newer RFC as default format, so you are advised to check your
1484 implementation and/or override the default with "->allow_nonref (0)" to
1485 ensure that future versions are safe.
1486
1487INTEROPERABILITY WITH OTHER MODULES
1488 "JSON::XS" uses the Types::Serialiser module to provide boolean
1489 constants. That means that the JSON true and false values will be
1490 comaptible to true and false values of other modules that do the same,
1491 such as JSON::PP and CBOR::XS.
1492
1493INTEROPERABILITY WITH OTHER JSON DECODERS
1494 As long as you only serialise data that can be directly expressed in
1495 JSON, "JSON::XS" is incapable of generating invalid JSON output (modulo
1496 bugs, but "JSON::XS" has found more bugs in the official JSON testsuite
1497 (1) than the official JSON testsuite has found in "JSON::XS" (0)).
1498
1499 When you have trouble decoding JSON generated by this module using other
1500 decoders, then it is very likely that you have an encoding mismatch or
1501 the other decoder is broken.
1502
1503 When decoding, "JSON::XS" is strict by default and will likely catch all
1504 errors. There are currently two settings that change this: "relaxed"
1505 makes "JSON::XS" accept (but not generate) some non-standard extensions,
1506 and "allow_tags" will allow you to encode and decode Perl objects, at
1507 the cost of not outputting valid JSON anymore.
1508
1509 TAGGED VALUE SYNTAX AND STANDARD JSON EN/DECODERS
1510 When you use "allow_tags" to use the extended (and also nonstandard and
1511 invalid) JSON syntax for serialised objects, and you still want to
1512 decode the generated When you want to serialise objects, you can run a
1513 regex to replace the tagged syntax by standard JSON arrays (it only
1514 works for "normal" package names without comma, newlines or single
1515 colons). First, the readable Perl version:
1516
1517 # if your FREEZE methods return no values, you need this replace first:
1518 $json =~ s/\( \s* (" (?: [^\\":,]+|\\.|::)* ") \s* \) \s* \[\s*\]/[$1]/gx;
1519
1520 # this works for non-empty constructor arg lists:
1521 $json =~ s/\( \s* (" (?: [^\\":,]+|\\.|::)* ") \s* \) \s* \[/[$1,/gx;
1522
1523 And here is a less readable version that is easy to adapt to other
1524 languages:
1525
1526 $json =~ s/\(\s*("([^\\":,]+|\\.|::)*")\s*\)\s*\[/[$1,/g;
1527
1528 Here is an ECMAScript version (same regex):
1529
1530 json = json.replace (/\(\s*("([^\\":,]+|\\.|::)*")\s*\)\s*\[/g, "[$1,");
1531
1532 Since this syntax converts to standard JSON arrays, it might be hard to
1533 distinguish serialised objects from normal arrays. You can prepend a
1534 "magic number" as first array element to reduce chances of a collision:
1535
1536 $json =~ s/\(\s*("([^\\":,]+|\\.|::)*")\s*\)\s*\[/["XU1peReLzT4ggEllLanBYq4G9VzliwKF",$1,/g;
1537
1538 And after decoding the JSON text, you could walk the data structure
1539 looking for arrays with a first element of
1540 "XU1peReLzT4ggEllLanBYq4G9VzliwKF".
1541
1542 The same approach can be used to create the tagged format with another
1543 encoder. First, you create an array with the magic string as first
1544 member, the classname as second, and constructor arguments last, encode
1545 it as part of your JSON structure, and then:
1546
1547 $json =~ s/\[\s*"XU1peReLzT4ggEllLanBYq4G9VzliwKF"\s*,\s*("([^\\":,]+|\\.|::)*")\s*,/($1)[/g;
1548
1549 Again, this has some limitations - the magic string must not be encoded
1550 with character escapes, and the constructor arguments must be non-empty.
1551
1552RFC7159
1553 Since this module was written, Google has written a new JSON RFC, RFC
1554 7159 (and RFC7158). Unfortunately, this RFC breaks compatibility with
1555 both the original JSON specification on www.json.org and RFC4627.
1556
1557 As far as I can see, you can get partial compatibility when parsing by
1558 using "->allow_nonref". However, consider the security implications of
1559 doing so.
1560
1561 I haven't decided yet when to break compatibility with RFC4627 by
1562 default (and potentially leave applications insecure) and change the
1563 default to follow RFC7159, but application authors are well advised to
1564 call "->allow_nonref(0)" even if this is the current default, if they
1565 cannot handle non-reference values, in preparation for the day when the
1566 default will change.
1567
1316THREADS 1568(I-)THREADS
1317 This module is *not* guaranteed to be thread safe and there are no plans 1569 This module is *not* guaranteed to be ithread (or MULTIPLICITY-) safe
1318 to change this until Perl gets thread support (as opposed to the 1570 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 1571 so-called theeads/ithreads are officially deprecated and should not be
1320 process simulations - use fork, it's *much* faster, cheaper, better). 1572 used.
1321 1573
1322 (It might actually work, but you have been warned). 1574THE PERILS OF SETLOCALE
1575 Sometimes people avoid the Perl locale support and directly call the
1576 system's setlocale function with "LC_ALL".
1577
1578 This breaks both perl and modules such as JSON::XS, as stringification
1579 of numbers no longer works correctly (e.g. "$x = 0.1; print "$x"+1"
1580 might print 1, and JSON::XS might output illegal JSON as JSON::XS relies
1581 on perl to stringify numbers).
1582
1583 The solution is simple: don't call "setlocale", or use it for only those
1584 categories you need, such as "LC_MESSAGES" or "LC_CTYPE".
1585
1586 If you need "LC_NUMERIC", you should enable it only around the code that
1587 actually needs it (avoiding stringification of numbers), and restore it
1588 afterwards.
1323 1589
1324BUGS 1590BUGS
1325 While the goal of this module is to be correct, that unfortunately does 1591 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 1592 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. 1593 keep reporting bugs they will be fixed swiftly, though.

Diff Legend

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