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

Comparing JSON-XS/README (file contents):
Revision 1.37 by root, Thu May 23 09:32:02 2013 UTC vs.
Revision 1.40 by root, Fri Feb 26 21:46:45 2016 UTC

… …
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.
… …
417 recommended to leave it off unless you know your communications 418 recommended to leave it off unless you know your communications
418 partner. 419 partner.
419 420
420 $json = $json->allow_blessed ([$enable]) 421 $json = $json->allow_blessed ([$enable])
421 $enabled = $json->get_allow_blessed 422 $enabled = $json->get_allow_blessed
423 See "OBJECT SERIALISATION" for details.
424
422 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
423 barf when it encounters a blessed reference. Instead, the value of 426 barf when it encounters a blessed reference that it cannot convert
424 the convert_blessed option will decide whether "null" 427 otherwise. Instead, a JSON "null" value is encoded instead of the
425 ("convert_blessed" disabled or no "TO_JSON" method found) or a 428 object.
426 representation of the object ("convert_blessed" enabled and
427 "TO_JSON" method found) is being encoded. Has no effect on "decode".
428 429
429 If $enable is false (the default), then "encode" will throw an 430 If $enable is false (the default), then "encode" will throw an
430 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".
431 435
432 $json = $json->convert_blessed ([$enable]) 436 $json = $json->convert_blessed ([$enable])
433 $enabled = $json->get_convert_blessed 437 $enabled = $json->get_convert_blessed
438 See "OBJECT SERIALISATION" for details.
439
434 If $enable is true (or missing), then "encode", upon encountering a 440 If $enable is true (or missing), then "encode", upon encountering a
435 blessed object, will check for the availability of the "TO_JSON" 441 blessed object, will check for the availability of the "TO_JSON"
436 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
437 context and the resulting scalar will be encoded instead of the 443 context and the resulting scalar will be encoded instead of the
438 object. If no "TO_JSON" method is found, the value of 444 object.
439 "allow_blessed" will decide what to do.
440 445
441 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"
442 returns other blessed objects, those will be handled in the same 447 returns other blessed objects, those will be handled in the same
443 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
444 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
445 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
446 the object) are usually in upper case letters and to avoid 451 the object) are usually in upper case letters and to avoid
447 collisions with any "to_json" function or method. 452 collisions with any "to_json" function or method.
448 453
449 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
450 future, global hooks might get installed that influence "decode" and 455 this type of conversion.
451 are enabled by this setting.
452 456
453 If $enable is false, then the "allow_blessed" setting will decide 457 This setting has no effect on "decode".
454 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.
455 475
456 $json = $json->filter_json_object ([$coderef->($hashref)]) 476 $json = $json->filter_json_object ([$coderef->($hashref)])
457 When $coderef is specified, it will be called from "decode" each 477 When $coderef is specified, it will be called from "decode" each
458 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
459 the newly-created hash. If the code references returns a single 479 the newly-created hash. If the code references returns a single
… …
595 615
596 See SECURITY CONSIDERATIONS, below, for more info on why this is 616 See SECURITY CONSIDERATIONS, below, for more info on why this is
597 useful. 617 useful.
598 618
599 $json_text = $json->encode ($perl_scalar) 619 $json_text = $json->encode ($perl_scalar)
600 Converts the given Perl data structure (a simple scalar or a 620 Converts the given Perl value or data structure to its JSON
601 reference to a hash or array) to its JSON representation. Simple 621 representation. Croaks on error.
602 scalars will be converted into JSON string or number sequences,
603 while references to arrays become JSON arrays and references to
604 hashes become JSON objects. Undefined Perl values (e.g. "undef")
605 become JSON "null" values. Neither "true" nor "false" values will be
606 generated.
607 622
608 $perl_scalar = $json->decode ($json_text) 623 $perl_scalar = $json->decode ($json_text)
609 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,
610 returning the resulting simple scalar or reference. Croaks on error. 625 returning the resulting simple scalar or reference. Croaks on error.
611
612 JSON numbers and strings become simple Perl scalars. JSON arrays
613 become Perl arrayrefs and JSON objects become Perl hashrefs. "true"
614 becomes 1, "false" becomes 0 and "null" becomes "undef".
615 626
616 ($perl_scalar, $characters) = $json->decode_prefix ($json_text) 627 ($perl_scalar, $characters) = $json->decode_prefix ($json_text)
617 This works like the "decode" method, but instead of raising an 628 This works like the "decode" method, but instead of raising an
618 exception when there is trailing garbage after the first JSON 629 exception when there is trailing garbage after the first JSON
619 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
620 characters consumed so far. 631 characters consumed so far.
621 632
622 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
623 protocol (which is not the brightest thing to do in the first place)
624 and you need to know where the JSON text ends. 634 protocol and you need to know where the JSON text ends.
625 635
626 JSON::XS->new->decode_prefix ("[1] the tail") 636 JSON::XS->new->decode_prefix ("[1] the tail")
627 => ([], 3) 637 => ([1], 3)
628 638
629INCREMENTAL PARSING 639INCREMENTAL PARSING
630 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.
631 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
632 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
… …
661 671
662 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
663 extract exactly *one* JSON object. If that is successful, it will 673 extract exactly *one* JSON object. If that is successful, it will
664 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
665 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
666 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
667 most common way of using the method. 677 most common way of using the method.
668 678
669 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
670 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
671 otherwise. For this to work, there must be no separators between the 681 otherwise. For this to work, there must be no separators between the
… …
699 "incr_parse" died, in which case the input buffer and incremental 709 "incr_parse" died, in which case the input buffer and incremental
700 parser state is left unchanged, to skip the text parsed so far and 710 parser state is left unchanged, to skip the text parsed so far and
701 to reset the parse state. 711 to reset the parse state.
702 712
703 The difference to "incr_reset" is that only text until the parse 713 The difference to "incr_reset" is that only text until the parse
704 error occured is removed. 714 error occurred is removed.
705 715
706 $json->incr_reset 716 $json->incr_reset
707 This completely resets the incremental parser, that is, after this 717 This completely resets the incremental parser, that is, after this
708 call, it will be as if the parser had never parsed anything. 718 call, it will be as if the parser had never parsed anything.
709 719
… …
893 If the number consists of digits only, JSON::XS will try to 903 If the number consists of digits only, JSON::XS will try to
894 represent it as an integer value. If that fails, it will try to 904 represent it as an integer value. If that fails, it will try to
895 represent it as a numeric (floating point) value if that is possible 905 represent it as a numeric (floating point) value if that is possible
896 without loss of precision. Otherwise it will preserve the number as 906 without loss of precision. Otherwise it will preserve the number as
897 a string value (in which case you lose roundtripping ability, as the 907 a string value (in which case you lose roundtripping ability, as the
898 JSON number will be re-encoded toa JSON string). 908 JSON number will be re-encoded to a JSON string).
899 909
900 Numbers containing a fractional or exponential part will always be 910 Numbers containing a fractional or exponential part will always be
901 represented as numeric (floating point) values, possibly at a loss 911 represented as numeric (floating point) values, possibly at a loss
902 of precision (in which case you might lose perfect roundtripping 912 of precision (in which case you might lose perfect roundtripping
903 ability, but the JSON number will still be re-encoded as a JSON 913 ability, but the JSON number will still be re-encoded as a JSON
904 number). 914 number).
905 915
906 Note that precision is not accuracy - binary floating point values 916 Note that precision is not accuracy - binary floating point values
907 cannot represent most decimal fractions exactly, and when converting 917 cannot represent most decimal fractions exactly, and when converting
908 from and to floating point, JSON::XS only guarantees precision up to 918 from and to floating point, JSON::XS only guarantees precision up to
909 but not including the leats significant bit. 919 but not including the least significant bit.
910 920
911 true, false 921 true, false
912 These JSON atoms become "JSON::XS::true" and "JSON::XS::false", 922 These JSON atoms become "Types::Serialiser::true" and
913 respectively. They are overloaded to act almost exactly like the 923 "Types::Serialiser::false", respectively. They are overloaded to act
914 numbers 1 and 0. You can check whether a scalar is a JSON boolean by 924 almost exactly like the numbers 1 and 0. You can check whether a
915 using the "JSON::XS::is_bool" function. 925 scalar is a JSON boolean by using the "Types::Serialiser::is_bool"
926 function (after "use Types::Serialier", of course).
916 927
917 null 928 null
918 A JSON null atom becomes "undef" in Perl. 929 A JSON null atom becomes "undef" in Perl.
930
931 shell-style comments ("# *text*")
932 As a nonstandard extension to the JSON syntax that is enabled by the
933 "relaxed" setting, shell-style comments are allowed. They can start
934 anywhere outside strings and go till the end of the line.
935
936 tagged values ("(*tag*)*value*").
937 Another nonstandard extension to the JSON syntax, enabled with the
938 "allow_tags" setting, are tagged values. In this implementation, the
939 *tag* must be a perl package/class name encoded as a JSON string,
940 and the *value* must be a JSON array encoding optional constructor
941 arguments.
942
943 See "OBJECT SERIALISATION", below, for details.
919 944
920 PERL -> JSON 945 PERL -> JSON
921 The mapping from Perl to JSON is slightly more difficult, as Perl is a 946 The mapping from Perl to JSON is slightly more difficult, as Perl is a
922 truly typeless language, so we can only guess which JSON type is meant 947 truly typeless language, so we can only guess which JSON type is meant
923 by a Perl value. 948 by a Perl value.
924 949
925 hash references 950 hash references
926 Perl hash references become JSON objects. As there is no inherent 951 Perl hash references become JSON objects. As there is no inherent
927 ordering in hash keys (or JSON objects), they will usually be 952 ordering in hash keys (or JSON objects), they will usually be
928 encoded in a pseudo-random order that can change between runs of the 953 encoded in a pseudo-random order. JSON::XS can optionally sort the
929 same program but stays generally the same within a single run of a 954 hash keys (determined by the *canonical* flag), so the same
930 program. JSON::XS can optionally sort the hash keys (determined by 955 datastructure will serialise to the same JSON text (given same
931 the *canonical* flag), so the same datastructure will serialise to 956 settings and version of JSON::XS), but this incurs a runtime
932 the same JSON text (given same settings and version of JSON::XS), 957 overhead and is only rarely useful, e.g. when you want to compare
933 but this incurs a runtime overhead and is only rarely useful, e.g. 958 some JSON text against another for equality.
934 when you want to compare some JSON text against another for
935 equality.
936 959
937 array references 960 array references
938 Perl array references become JSON arrays. 961 Perl array references become JSON arrays.
939 962
940 other references 963 other references
941 Other unblessed references are generally not allowed and will cause 964 Other unblessed references are generally not allowed and will cause
942 an exception to be thrown, except for references to the integers 0 965 an exception to be thrown, except for references to the integers 0
943 and 1, which get turned into "false" and "true" atoms in JSON. You 966 and 1, which get turned into "false" and "true" atoms in JSON.
944 can also use "JSON::XS::false" and "JSON::XS::true" to improve 967
968 Since "JSON::XS" uses the boolean model from Types::Serialiser, you
969 can also "use Types::Serialiser" and then use
970 "Types::Serialiser::false" and "Types::Serialiser::true" to improve
945 readability. 971 readability.
946 972
973 use Types::Serialiser;
947 encode_json [\0, JSON::XS::true] # yields [false,true] 974 encode_json [\0, Types::Serialiser::true] # yields [false,true]
948 975
949 JSON::XS::true, JSON::XS::false 976 Types::Serialiser::true, Types::Serialiser::false
950 These special values become JSON true and JSON false values, 977 These special values from the Types::Serialiser module become JSON
951 respectively. You can also use "\1" and "\0" directly if you want. 978 true and JSON false values, respectively. You can also use "\1" and
979 "\0" directly if you want.
952 980
953 blessed objects 981 blessed objects
954 Blessed objects are not directly representable in JSON. See the 982 Blessed objects are not directly representable in JSON, but
955 "allow_blessed" and "convert_blessed" methods on various options on 983 "JSON::XS" allows various ways of handling objects. See "OBJECT
956 how to deal with this: basically, you can choose between throwing an 984 SERIALISATION", below, for details.
957 exception, encoding the reference as if it weren't blessed, or
958 provide your own serialiser method.
959 985
960 simple scalars 986 simple scalars
961 Simple Perl scalars (any scalar that is not a reference) are the 987 Simple Perl scalars (any scalar that is not a reference) are the
962 most difficult objects to encode: JSON::XS will encode undefined 988 most difficult objects to encode: JSON::XS will encode undefined
963 scalars as JSON "null" values, scalars that have last been used in a 989 scalars as JSON "null" values, scalars that have last been used in a
… …
998 which can differ to other languages). Also, your perl interpreter 1024 which can differ to other languages). Also, your perl interpreter
999 might expose extensions to the floating point numbers of your 1025 might expose extensions to the floating point numbers of your
1000 platform, such as infinities or NaN's - these cannot be represented 1026 platform, such as infinities or NaN's - these cannot be represented
1001 in JSON, and it is an error to pass those in. 1027 in JSON, and it is an error to pass those in.
1002 1028
1029 OBJECT SERIALISATION
1030 As JSON cannot directly represent Perl objects, you have to choose
1031 between a pure JSON representation (without the ability to deserialise
1032 the object automatically again), and a nonstandard extension to the JSON
1033 syntax, tagged values.
1034
1035 SERIALISATION
1036 What happens when "JSON::XS" encounters a Perl object depends on the
1037 "allow_blessed", "convert_blessed" and "allow_tags" settings, which are
1038 used in this order:
1039
1040 1. "allow_tags" is enabled and the object has a "FREEZE" method.
1041 In this case, "JSON::XS" uses the Types::Serialiser object
1042 serialisation protocol to create a tagged JSON value, using a
1043 nonstandard extension to the JSON syntax.
1044
1045 This works by invoking the "FREEZE" method on the object, with the
1046 first argument being the object to serialise, and the second
1047 argument being the constant string "JSON" to distinguish it from
1048 other serialisers.
1049
1050 The "FREEZE" method can return any number of values (i.e. zero or
1051 more). These values and the paclkage/classname of the object will
1052 then be encoded as a tagged JSON value in the following format:
1053
1054 ("classname")[FREEZE return values...]
1055
1056 e.g.:
1057
1058 ("URI")["http://www.google.com/"]
1059 ("MyDate")[2013,10,29]
1060 ("ImageData::JPEG")["Z3...VlCg=="]
1061
1062 For example, the hypothetical "My::Object" "FREEZE" method might use
1063 the objects "type" and "id" members to encode the object:
1064
1065 sub My::Object::FREEZE {
1066 my ($self, $serialiser) = @_;
1067
1068 ($self->{type}, $self->{id})
1069 }
1070
1071 2. "convert_blessed" is enabled and the object has a "TO_JSON" method.
1072 In this case, the "TO_JSON" method of the object is invoked in
1073 scalar context. It must return a single scalar that can be directly
1074 encoded into JSON. This scalar replaces the object in the JSON text.
1075
1076 For example, the following "TO_JSON" method will convert all URI
1077 objects to JSON strings when serialised. The fatc that these values
1078 originally were URI objects is lost.
1079
1080 sub URI::TO_JSON {
1081 my ($uri) = @_;
1082 $uri->as_string
1083 }
1084
1085 3. "allow_blessed" is enabled.
1086 The object will be serialised as a JSON null value.
1087
1088 4. none of the above
1089 If none of the settings are enabled or the respective methods are
1090 missing, "JSON::XS" throws an exception.
1091
1092 DESERIALISATION
1093 For deserialisation there are only two cases to consider: either
1094 nonstandard tagging was used, in which case "allow_tags" decides, or
1095 objects cannot be automatically be deserialised, in which case you can
1096 use postprocessing or the "filter_json_object" or
1097 "filter_json_single_key_object" callbacks to get some real objects our
1098 of your JSON.
1099
1100 This section only considers the tagged value case: I a tagged JSON
1101 object is encountered during decoding and "allow_tags" is disabled, a
1102 parse error will result (as if tagged values were not part of the
1103 grammar).
1104
1105 If "allow_tags" is enabled, "JSON::XS" will look up the "THAW" method of
1106 the package/classname used during serialisation (it will not attempt to
1107 load the package as a Perl module). If there is no such method, the
1108 decoding will fail with an error.
1109
1110 Otherwise, the "THAW" method is invoked with the classname as first
1111 argument, the constant string "JSON" as second argument, and all the
1112 values from the JSON array (the values originally returned by the
1113 "FREEZE" method) as remaining arguments.
1114
1115 The method must then return the object. While technically you can return
1116 any Perl scalar, you might have to enable the "enable_nonref" setting to
1117 make that work in all cases, so better return an actual blessed
1118 reference.
1119
1120 As an example, let's implement a "THAW" function that regenerates the
1121 "My::Object" from the "FREEZE" example earlier:
1122
1123 sub My::Object::THAW {
1124 my ($class, $serialiser, $type, $id) = @_;
1125
1126 $class->new (type => $type, id => $id)
1127 }
1128
1003ENCODING/CODESET FLAG NOTES 1129ENCODING/CODESET FLAG NOTES
1004 The interested reader might have seen a number of flags that signify 1130 The interested reader might have seen a number of flags that signify
1005 encodings or codesets - "utf8", "latin1" and "ascii". There seems to be 1131 encodings or codesets - "utf8", "latin1" and "ascii". There seems to be
1006 some confusion on what these do, so here is a short comparison: 1132 some confusion on what these do, so here is a short comparison:
1007 1133
… …
1026 1152
1027 "utf8" flag disabled 1153 "utf8" flag disabled
1028 When "utf8" is disabled (the default), then "encode"/"decode" 1154 When "utf8" is disabled (the default), then "encode"/"decode"
1029 generate and expect Unicode strings, that is, characters with high 1155 generate and expect Unicode strings, that is, characters with high
1030 ordinal Unicode values (> 255) will be encoded as such characters, 1156 ordinal Unicode values (> 255) will be encoded as such characters,
1031 and likewise such characters are decoded as-is, no canges to them 1157 and likewise such characters are decoded as-is, no changes to them
1032 will be done, except "(re-)interpreting" them as Unicode codepoints 1158 will be done, except "(re-)interpreting" them as Unicode codepoints
1033 or Unicode characters, respectively (to Perl, these are the same 1159 or Unicode characters, respectively (to Perl, these are the same
1034 thing in strings unless you do funny/weird/dumb stuff). 1160 thing in strings unless you do funny/weird/dumb stuff).
1035 1161
1036 This is useful when you want to do the encoding yourself (e.g. when 1162 This is useful when you want to do the encoding yourself (e.g. when
… …
1152 output for these property strings, e.g.: 1278 output for these property strings, e.g.:
1153 1279
1154 $json =~ s/"__proto__"\s*:/"__proto__renamed":/g; 1280 $json =~ s/"__proto__"\s*:/"__proto__renamed":/g;
1155 1281
1156 This works because "__proto__" is not valid outside of strings, so every 1282 This works because "__proto__" is not valid outside of strings, so every
1157 occurence of ""__proto__"\s*:" must be a string used as property name. 1283 occurrence of ""__proto__"\s*:" must be a string used as property name.
1158 1284
1159 If you know of other incompatibilities, please let me know. 1285 If you know of other incompatibilities, please let me know.
1160 1286
1161 JSON and YAML 1287 JSON and YAML
1162 You often hear that JSON is a subset of YAML. This is, however, a mass 1288 You often hear that JSON is a subset of YAML. This is, however, a mass
… …
1313 to see whether you are vulnerable to some common attack vectors (which 1439 to see whether you are vulnerable to some common attack vectors (which
1314 really are browser design bugs, but it is still you who will have to 1440 really are browser design bugs, but it is still you who will have to
1315 deal with it, as major browser developers care only for features, not 1441 deal with it, as major browser developers care only for features, not
1316 about getting security right). 1442 about getting security right).
1317 1443
1444"OLD" VS. "NEW" JSON (RFC 4627 VS. RFC 7159)
1445 TL;DR: Due to security concerns, JSON::XS will not allow scalar data in
1446 JSON texts by default - you need to create your own JSON::XS object and
1447 enable "allow_nonref":
1448
1449 my $json = JSON::XS->new->allow_nonref;
1450
1451 $text = $json->encode ($data);
1452 $data = $json->decode ($text);
1453
1454 The long version: JSON being an important and supposedly stable format,
1455 the IETF standardised it as RFC 4627 in 2006. Unfortunately, the
1456 inventor of JSON, Dougles Crockford, unilaterally changed the definition
1457 of JSON in javascript. Rather than create a fork, the IETF decided to
1458 standardise the new syntax (apparently, so Iw as told, without finding
1459 it very amusing).
1460
1461 The biggest difference between thed original JSON and the new JSON is
1462 that the new JSON supports scalars (anything other than arrays and
1463 objects) at the toplevel of a JSON text. While this is strictly
1464 backwards compatible to older versions, it breaks a number of protocols
1465 that relied on sending JSON back-to-back, and is a minor security
1466 concern.
1467
1468 For example, imagine you have two banks communicating, and on one side,
1469 trhe JSON coder gets upgraded. Two messages, such as 10 and 1000 might
1470 then be confused to mean 101000, something that couldn't happen in the
1471 original JSON, because niether of these messages would be valid JSON.
1472
1473 If one side accepts these messages, then an upgrade in the coder on
1474 either side could result in this becoming exploitable.
1475
1476 This module has always allowed these messages as an optional extension,
1477 by default disabled. The security concerns are the reason why the
1478 default is still disabled, but future versions might/will likely upgrade
1479 to the newer RFC as default format, so you are advised to check your
1480 implementation and/or override the default with "->allow_nonref (0)" to
1481 ensure that future versions are safe.
1482
1483INTEROPERABILITY WITH OTHER MODULES
1484 "JSON::XS" uses the Types::Serialiser module to provide boolean
1485 constants. That means that the JSON true and false values will be
1486 comaptible to true and false values of iother modules that do the same,
1487 such as JSON::PP and CBOR::XS.
1488
1489INTEROPERABILITY WITH OTHER JSON DECODERS
1490 As long as you only serialise data that can be directly expressed in
1491 JSON, "JSON::XS" is incapable of generating invalid JSON output (modulo
1492 bugs, but "JSON::XS" has found more bugs in the official JSON testsuite
1493 (1) than the official JSON testsuite has found in "JSON::XS" (0)).
1494
1495 When you have trouble decoding JSON generated by this module using other
1496 decoders, then it is very likely that you have an encoding mismatch or
1497 the other decoder is broken.
1498
1499 When decoding, "JSON::XS" is strict by default and will likely catch all
1500 errors. There are currently two settings that change this: "relaxed"
1501 makes "JSON::XS" accept (but not generate) some non-standard extensions,
1502 and "allow_tags" will allow you to encode and decode Perl objects, at
1503 the cost of not outputting valid JSON anymore.
1504
1505 TAGGED VALUE SYNTAX AND STANDARD JSON EN/DECODERS
1506 When you use "allow_tags" to use the extended (and also nonstandard and
1507 invalid) JSON syntax for serialised objects, and you still want to
1508 decode the generated When you want to serialise objects, you can run a
1509 regex to replace the tagged syntax by standard JSON arrays (it only
1510 works for "normal" packagesnames without comma, newlines or single
1511 colons). First, the readable Perl version:
1512
1513 # if your FREEZE methods return no values, you need this replace first:
1514 $json =~ s/\( \s* (" (?: [^\\":,]+|\\.|::)* ") \s* \) \s* \[\s*\]/[$1]/gx;
1515
1516 # this works for non-empty constructor arg lists:
1517 $json =~ s/\( \s* (" (?: [^\\":,]+|\\.|::)* ") \s* \) \s* \[/[$1,/gx;
1518
1519 And here is a less readable version that is easy to adapt to other
1520 languages:
1521
1522 $json =~ s/\(\s*("([^\\":,]+|\\.|::)*")\s*\)\s*\[/[$1,/g;
1523
1524 Here is an ECMAScript version (same regex):
1525
1526 json = json.replace (/\(\s*("([^\\":,]+|\\.|::)*")\s*\)\s*\[/g, "[$1,");
1527
1528 Since this syntax converts to standard JSON arrays, it might be hard to
1529 distinguish serialised objects from normal arrays. You can prepend a
1530 "magic number" as first array element to reduce chances of a collision:
1531
1532 $json =~ s/\(\s*("([^\\":,]+|\\.|::)*")\s*\)\s*\[/["XU1peReLzT4ggEllLanBYq4G9VzliwKF",$1,/g;
1533
1534 And after decoding the JSON text, you could walk the data structure
1535 looking for arrays with a first element of
1536 "XU1peReLzT4ggEllLanBYq4G9VzliwKF".
1537
1538 The same approach can be used to create the tagged format with another
1539 encoder. First, you create an array with the magic string as first
1540 member, the classname as second, and constructor arguments last, encode
1541 it as part of your JSON structure, and then:
1542
1543 $json =~ s/\[\s*"XU1peReLzT4ggEllLanBYq4G9VzliwKF"\s*,\s*("([^\\":,]+|\\.|::)*")\s*,/($1)[/g;
1544
1545 Again, this has some limitations - the magic string must not be encoded
1546 with character escapes, and the constructor arguments must be non-empty.
1547
1548RFC7159
1549 Since this module was written, Google has written a new JSON RFC, RFC
1550 7159 (and RFC7158). Unfortunately, this RFC breaks compatibility with
1551 both the original JSON specification on www.json.org and RFC4627.
1552
1553 As far as I can see, you can get partial compatibility when parsing by
1554 using "->allow_nonref". However, consider thew security implications of
1555 doing so.
1556
1557 I haven't decided yet when to break compatibility with RFC4627 by
1558 default (and potentially leave applications insecure) and change the
1559 default to follow RFC7159, but application authors are well advised to
1560 call "->allow_nonref(0)" even if this is the current default, if they
1561 cannot handle non-reference values, in preparation for the day when the4
1562 default will change.
1563
1318THREADS 1564THREADS
1319 This module is *not* guaranteed to be thread safe and there are no plans 1565 This module is *not* guaranteed to be thread safe and there are no plans
1320 to change this until Perl gets thread support (as opposed to the 1566 to change this until Perl gets thread support (as opposed to the
1321 horribly slow so-called "threads" which are simply slow and bloated 1567 horribly slow so-called "threads" which are simply slow and bloated
1322 process simulations - use fork, it's *much* faster, cheaper, better). 1568 process simulations - use fork, it's *much* faster, cheaper, better).
… …
1326THE PERILS OF SETLOCALE 1572THE PERILS OF SETLOCALE
1327 Sometimes people avoid the Perl locale support and directly call the 1573 Sometimes people avoid the Perl locale support and directly call the
1328 system's setlocale function with "LC_ALL". 1574 system's setlocale function with "LC_ALL".
1329 1575
1330 This breaks both perl and modules such as JSON::XS, as stringification 1576 This breaks both perl and modules such as JSON::XS, as stringification
1331 of numbers no longer works correcly (e.g. "$x = 0.1; print "$x"+1" might 1577 of numbers no longer works correctly (e.g. "$x = 0.1; print "$x"+1"
1332 print 1, and JSON::XS might output illegal JSON as JSON::XS relies on 1578 might print 1, and JSON::XS might output illegal JSON as JSON::XS relies
1333 perl to stringify numbers). 1579 on perl to stringify numbers).
1334 1580
1335 The solution is simple: don't call "setlocale", or use it for only those 1581 The solution is simple: don't call "setlocale", or use it for only those
1336 categories you need, such as "LC_MESSAGES" or "LC_CTYPE". 1582 categories you need, such as "LC_MESSAGES" or "LC_CTYPE".
1337 1583
1338 If you need "LC_NUMERIC", you should enable it only around the code that 1584 If you need "LC_NUMERIC", you should enable it only around the code that

Diff Legend

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