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

Comparing JSON-XS/README (file contents):
Revision 1.36 by root, Wed Jul 27 15:53:40 2011 UTC vs.
Revision 1.38 by root, Tue Oct 29 00:36:18 2013 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
… …
369 output JSON objects by sorting their keys. This is adding a 360 output JSON objects by sorting their keys. This is adding a
370 comparatively high overhead. 361 comparatively high overhead.
371 362
372 If $enable is false, then the "encode" method will output key-value 363 If $enable is false, then the "encode" method will output key-value
373 pairs in the order Perl stores them (which will likely change 364 pairs in the order Perl stores them (which will likely change
374 between runs of the same script). 365 between runs of the same script, and can change even within the same
366 run from 5.18 onwards).
375 367
376 This option is useful if you want the same data structure to be 368 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 369 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 370 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 371 contains the same data, as key-value pairs have no inherent ordering
… …
416 recommended to leave it off unless you know your communications 408 recommended to leave it off unless you know your communications
417 partner. 409 partner.
418 410
419 $json = $json->allow_blessed ([$enable]) 411 $json = $json->allow_blessed ([$enable])
420 $enabled = $json->get_allow_blessed 412 $enabled = $json->get_allow_blessed
413 See "OBJECT SERIALISATION" for details.
414
421 If $enable is true (or missing), then the "encode" method will not 415 If $enable is true (or missing), then the "encode" method will not
422 barf when it encounters a blessed reference. Instead, the value of 416 barf when it encounters a blessed reference that it cannot convert
423 the convert_blessed option will decide whether "null" 417 otherwise. Instead, a JSON "null" value is encoded instead of the
424 ("convert_blessed" disabled or no "TO_JSON" method found) or a 418 object.
425 representation of the object ("convert_blessed" enabled and
426 "TO_JSON" method found) is being encoded. Has no effect on "decode".
427 419
428 If $enable is false (the default), then "encode" will throw an 420 If $enable is false (the default), then "encode" will throw an
429 exception when it encounters a blessed object. 421 exception when it encounters a blessed object that it cannot convert
422 otherwise.
423
424 This setting has no effect on "decode".
430 425
431 $json = $json->convert_blessed ([$enable]) 426 $json = $json->convert_blessed ([$enable])
432 $enabled = $json->get_convert_blessed 427 $enabled = $json->get_convert_blessed
428 See "OBJECT SERIALISATION" for details.
429
433 If $enable is true (or missing), then "encode", upon encountering a 430 If $enable is true (or missing), then "encode", upon encountering a
434 blessed object, will check for the availability of the "TO_JSON" 431 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 432 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 433 context and the resulting scalar will be encoded instead of the
437 object. If no "TO_JSON" method is found, the value of 434 object.
438 "allow_blessed" will decide what to do.
439 435
440 The "TO_JSON" method may safely call die if it wants. If "TO_JSON" 436 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 437 returns other blessed objects, those will be handled in the same
442 way. "TO_JSON" must take care of not causing an endless recursion 438 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 439 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 440 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 441 the object) are usually in upper case letters and to avoid
446 collisions with any "to_json" function or method. 442 collisions with any "to_json" function or method.
447 443
448 This setting does not yet influence "decode" in any way, but in the 444 If $enable is false (the default), then "encode" will not consider
449 future, global hooks might get installed that influence "decode" and 445 this type of conversion.
450 are enabled by this setting.
451 446
452 If $enable is false, then the "allow_blessed" setting will decide 447 This setting has no effect on "decode".
453 what to do when a blessed object is found. 448
449 $json = $json->allow_tags ([$enable])
450 $enabled = $json->allow_tags
451 See "OBJECT SERIALISATION" for details.
452
453 If $enable is true (or missing), then "encode", upon encountering a
454 blessed object, will check for the availability of the "FREEZE"
455 method on the object's class. If found, it will be used to serialise
456 the object into a nonstandard tagged JSON value (that JSON decoders
457 cannot decode).
458
459 It also causes "decode" to parse such tagged JSON values and
460 deserialise them via a call to the "THAW" method.
461
462 If $enable is false (the default), then "encode" will not consider
463 this type of conversion, and tagged JSON values will cause a parse
464 error in "decode", as if tags were not part of the grammar.
454 465
455 $json = $json->filter_json_object ([$coderef->($hashref)]) 466 $json = $json->filter_json_object ([$coderef->($hashref)])
456 When $coderef is specified, it will be called from "decode" each 467 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 468 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 469 the newly-created hash. If the code references returns a single
… …
594 605
595 See SECURITY CONSIDERATIONS, below, for more info on why this is 606 See SECURITY CONSIDERATIONS, below, for more info on why this is
596 useful. 607 useful.
597 608
598 $json_text = $json->encode ($perl_scalar) 609 $json_text = $json->encode ($perl_scalar)
599 Converts the given Perl data structure (a simple scalar or a 610 Converts the given Perl value or data structure to its JSON
600 reference to a hash or array) to its JSON representation. Simple 611 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 612
607 $perl_scalar = $json->decode ($json_text) 613 $perl_scalar = $json->decode ($json_text)
608 The opposite of "encode": expects a JSON text and tries to parse it, 614 The opposite of "encode": expects a JSON text and tries to parse it,
609 returning the resulting simple scalar or reference. Croaks on error. 615 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 616
615 ($perl_scalar, $characters) = $json->decode_prefix ($json_text) 617 ($perl_scalar, $characters) = $json->decode_prefix ($json_text)
616 This works like the "decode" method, but instead of raising an 618 This works like the "decode" method, but instead of raising an
617 exception when there is trailing garbage after the first JSON 619 exception when there is trailing garbage after the first JSON
618 object, it will silently stop parsing there and return the number of 620 object, it will silently stop parsing there and return the number of
619 characters consumed so far. 621 characters consumed so far.
620 622
621 This is useful if your JSON texts are not delimited by an outer 623 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. 624 protocol and you need to know where the JSON text ends.
624 625
625 JSON::XS->new->decode_prefix ("[1] the tail") 626 JSON::XS->new->decode_prefix ("[1] the tail")
626 => ([], 3) 627 => ([], 3)
627 628
628INCREMENTAL PARSING 629INCREMENTAL PARSING
… …
660 661
661 If the method is called in scalar context, then it will try to 662 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 663 extract exactly *one* JSON object. If that is successful, it will
663 return this object, otherwise it will return "undef". If there is a 664 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 665 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 666 can then use "incr_skip" to skip the erroneous part). This is the
666 most common way of using the method. 667 most common way of using the method.
667 668
668 And finally, in list context, it will try to extract as many objects 669 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 670 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 671 otherwise. For this to work, there must be no separators between the
… …
698 "incr_parse" died, in which case the input buffer and incremental 699 "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 700 parser state is left unchanged, to skip the text parsed so far and
700 to reset the parse state. 701 to reset the parse state.
701 702
702 The difference to "incr_reset" is that only text until the parse 703 The difference to "incr_reset" is that only text until the parse
703 error occured is removed. 704 error occurred is removed.
704 705
705 $json->incr_reset 706 $json->incr_reset
706 This completely resets the incremental parser, that is, after this 707 This completely resets the incremental parser, that is, after this
707 call, it will be as if the parser had never parsed anything. 708 call, it will be as if the parser had never parsed anything.
708 709
… …
892 If the number consists of digits only, JSON::XS will try to 893 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 894 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 895 represent it as a numeric (floating point) value if that is possible
895 without loss of precision. Otherwise it will preserve the number as 896 without loss of precision. Otherwise it will preserve the number as
896 a string value (in which case you lose roundtripping ability, as the 897 a string value (in which case you lose roundtripping ability, as the
897 JSON number will be re-encoded toa JSON string). 898 JSON number will be re-encoded to a JSON string).
898 899
899 Numbers containing a fractional or exponential part will always be 900 Numbers containing a fractional or exponential part will always be
900 represented as numeric (floating point) values, possibly at a loss 901 represented as numeric (floating point) values, possibly at a loss
901 of precision (in which case you might lose perfect roundtripping 902 of precision (in which case you might lose perfect roundtripping
902 ability, but the JSON number will still be re-encoded as a JSON 903 ability, but the JSON number will still be re-encoded as a JSON
903 number). 904 number).
904 905
905 Note that precision is not accuracy - binary floating point values 906 Note that precision is not accuracy - binary floating point values
906 cannot represent most decimal fractions exactly, and when converting 907 cannot represent most decimal fractions exactly, and when converting
907 from and to floating point, JSON::XS only guarantees precision up to 908 from and to floating point, JSON::XS only guarantees precision up to
908 but not including the leats significant bit. 909 but not including the least significant bit.
909 910
910 true, false 911 true, false
911 These JSON atoms become "JSON::XS::true" and "JSON::XS::false", 912 These JSON atoms become "Types::Serialiser::true" and
912 respectively. They are overloaded to act almost exactly like the 913 "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 914 almost exactly like the numbers 1 and 0. You can check whether a
914 using the "JSON::XS::is_bool" function. 915 scalar is a JSON boolean by using the "Types::Serialiser::is_bool"
916 function (after "use Types::Serialier", of course).
915 917
916 null 918 null
917 A JSON null atom becomes "undef" in Perl. 919 A JSON null atom becomes "undef" in Perl.
920
921 shell-style comments ("# *text*")
922 As a nonstandard extension to the JSON syntax that is enabled by the
923 "relaxed" setting, shell-style comments are allowed. They can start
924 anywhere outside strings and go till the end of the line.
925
926 tagged values ("(*tag*)*value*").
927 Another nonstandard extension to the JSON syntax, enabled with the
928 "allow_tags" setting, are tagged values. In this implementation, the
929 *tag* must be a perl package/class name encoded as a JSON string,
930 and the *value* must be a JSON array encoding optional constructor
931 arguments.
932
933 See "OBJECT SERIALISATION", below, for details.
918 934
919 PERL -> JSON 935 PERL -> JSON
920 The mapping from Perl to JSON is slightly more difficult, as Perl is a 936 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 937 truly typeless language, so we can only guess which JSON type is meant
922 by a Perl value. 938 by a Perl value.
923 939
924 hash references 940 hash references
925 Perl hash references become JSON objects. As there is no inherent 941 Perl hash references become JSON objects. As there is no inherent
926 ordering in hash keys (or JSON objects), they will usually be 942 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 943 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 944 hash keys (determined by the *canonical* flag), so the same
929 program. JSON::XS can optionally sort the hash keys (determined by 945 datastructure will serialise to the same JSON text (given same
930 the *canonical* flag), so the same datastructure will serialise to 946 settings and version of JSON::XS), but this incurs a runtime
931 the same JSON text (given same settings and version of JSON::XS), 947 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. 948 some JSON text against another for equality.
933 when you want to compare some JSON text against another for
934 equality.
935 949
936 array references 950 array references
937 Perl array references become JSON arrays. 951 Perl array references become JSON arrays.
938 952
939 other references 953 other references
940 Other unblessed references are generally not allowed and will cause 954 Other unblessed references are generally not allowed and will cause
941 an exception to be thrown, except for references to the integers 0 955 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 956 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 957
958 Since "JSON::XS" uses the boolean model from Types::Serialiser, you
959 can also "use Types::Serialiser" and then use
960 "Types::Serialiser::false" and "Types::Serialiser::true" to improve
944 readability. 961 readability.
945 962
963 use Types::Serialiser;
946 encode_json [\0, JSON::XS::true] # yields [false,true] 964 encode_json [\0, Types::Serialiser::true] # yields [false,true]
947 965
948 JSON::XS::true, JSON::XS::false 966 Types::Serialiser::true, Types::Serialiser::false
949 These special values become JSON true and JSON false values, 967 These special values from the Types::Serialiser module become JSON
950 respectively. You can also use "\1" and "\0" directly if you want. 968 true and JSON false values, respectively. You can also use "\1" and
969 "\0" directly if you want.
951 970
952 blessed objects 971 blessed objects
953 Blessed objects are not directly representable in JSON. See the 972 Blessed objects are not directly representable in JSON, but
954 "allow_blessed" and "convert_blessed" methods on various options on 973 "JSON::XS" allows various ways of handling objects. See "OBJECT
955 how to deal with this: basically, you can choose between throwing an 974 SERIALISATION", below, for details.
956 exception, encoding the reference as if it weren't blessed, or
957 provide your own serialiser method.
958 975
959 simple scalars 976 simple scalars
960 Simple Perl scalars (any scalar that is not a reference) are the 977 Simple Perl scalars (any scalar that is not a reference) are the
961 most difficult objects to encode: JSON::XS will encode undefined 978 most difficult objects to encode: JSON::XS will encode undefined
962 scalars as JSON "null" values, scalars that have last been used in a 979 scalars as JSON "null" values, scalars that have last been used in a
… …
997 which can differ to other languages). Also, your perl interpreter 1014 which can differ to other languages). Also, your perl interpreter
998 might expose extensions to the floating point numbers of your 1015 might expose extensions to the floating point numbers of your
999 platform, such as infinities or NaN's - these cannot be represented 1016 platform, such as infinities or NaN's - these cannot be represented
1000 in JSON, and it is an error to pass those in. 1017 in JSON, and it is an error to pass those in.
1001 1018
1019 OBJECT SERIALISATION
1020 As JSON cannot directly represent Perl objects, you have to choose
1021 between a pure JSON representation (without the ability to deserialise
1022 the object automatically again), and a nonstandard extension to the JSON
1023 syntax, tagged values.
1024
1025 SERIALISATION
1026 What happens when "JSON::XS" encounters a Perl object depends on the
1027 "allow_blessed", "convert_blessed" and "allow_tags" settings, which are
1028 used in this order:
1029
1030 1. "allow_tags" is enabled and the object has a "FREEZE" method.
1031 In this case, "JSON::XS" uses the Types::Serialiser object
1032 serialisation protocol to create a tagged JSON value, using a
1033 nonstandard extension to the JSON syntax.
1034
1035 This works by invoking the "FREEZE" method on the object, with the
1036 first argument being the object to serialise, and the second
1037 argument being the constant string "JSON" to distinguish it from
1038 other serialisers.
1039
1040 The "FREEZE" method can return any number of values (i.e. zero or
1041 more). These values and the paclkage/classname of the object will
1042 then be encoded as a tagged JSON value in the following format:
1043
1044 ("classname")[FREEZE return values...]
1045
1046 For example, the hypothetical "My::Object" "FREEZE" method might use
1047 the objects "type" and "id" members to encode the object:
1048
1049 sub My::Object::FREEZE {
1050 my ($self, $serialiser) = @_;
1051
1052 ($self->{type}, $self->{id})
1053 }
1054
1055 2. "convert_blessed" is enabled and the object has a "TO_JSON" method.
1056 In this case, the "TO_JSON" method of the object is invoked in
1057 scalar context. It must return a single scalar that can be directly
1058 encoded into JSON. This scalar replaces the object in the JSON text.
1059
1060 For example, the following "TO_JSON" method will convert all URI
1061 objects to JSON strings when serialised. The fatc that these values
1062 originally were URI objects is lost.
1063
1064 sub URI::TO_JSON {
1065 my ($uri) = @_;
1066 $uri->as_string
1067 }
1068
1069 3. "allow_blessed" is enabled.
1070 The object will be serialised as a JSON null value.
1071
1072 4. none of the above
1073 If none of the settings are enabled or the respective methods are
1074 missing, "JSON::XS" throws an exception.
1075
1076 DESERIALISATION
1077 For deserialisation there are only two cases to consider: either
1078 nonstandard tagging was used, in which case "allow_tags" decides, or
1079 objects cannot be automatically be deserialised, in which case you can
1080 use postprocessing or the "filter_json_object" or
1081 "filter_json_single_key_object" callbacks to get some real objects our
1082 of your JSON.
1083
1084 This section only considers the tagged value case: I a tagged JSON
1085 object is encountered during decoding and "allow_tags" is disabled, a
1086 parse error will result (as if tagged values were not part of the
1087 grammar).
1088
1089 If "allow_tags" is enabled, "JSON::XS" will look up the "THAW" method of
1090 the package/classname used during serialisation (it will not attempt to
1091 load the package as a Perl module). If there is no such method, the
1092 decoding will fail with an error.
1093
1094 Otherwise, the "THAW" method is invoked with the classname as first
1095 argument, the constant string "JSON" as second argument, and all the
1096 values from the JSON array (the values originally returned by the
1097 "FREEZE" method) as remaining arguments.
1098
1099 The method must then return the object. While technically you can return
1100 any Perl scalar, you might have to enable the "enable_nonref" setting to
1101 make that work in all cases, so better return an actual blessed
1102 reference.
1103
1104 As an example, let's implement a "THAW" function that regenerates the
1105 "My::Object" from the "FREEZE" example earlier:
1106
1107 sub My::Object::THAW {
1108 my ($class, $serialiser, $type, $id) = @_;
1109
1110 $class->new (type => $type, id => $id)
1111 }
1112
1002ENCODING/CODESET FLAG NOTES 1113ENCODING/CODESET FLAG NOTES
1003 The interested reader might have seen a number of flags that signify 1114 The interested reader might have seen a number of flags that signify
1004 encodings or codesets - "utf8", "latin1" and "ascii". There seems to be 1115 encodings or codesets - "utf8", "latin1" and "ascii". There seems to be
1005 some confusion on what these do, so here is a short comparison: 1116 some confusion on what these do, so here is a short comparison:
1006 1117
… …
1025 1136
1026 "utf8" flag disabled 1137 "utf8" flag disabled
1027 When "utf8" is disabled (the default), then "encode"/"decode" 1138 When "utf8" is disabled (the default), then "encode"/"decode"
1028 generate and expect Unicode strings, that is, characters with high 1139 generate and expect Unicode strings, that is, characters with high
1029 ordinal Unicode values (> 255) will be encoded as such characters, 1140 ordinal Unicode values (> 255) will be encoded as such characters,
1030 and likewise such characters are decoded as-is, no canges to them 1141 and likewise such characters are decoded as-is, no changes to them
1031 will be done, except "(re-)interpreting" them as Unicode codepoints 1142 will be done, except "(re-)interpreting" them as Unicode codepoints
1032 or Unicode characters, respectively (to Perl, these are the same 1143 or Unicode characters, respectively (to Perl, these are the same
1033 thing in strings unless you do funny/weird/dumb stuff). 1144 thing in strings unless you do funny/weird/dumb stuff).
1034 1145
1035 This is useful when you want to do the encoding yourself (e.g. when 1146 This is useful when you want to do the encoding yourself (e.g. when
… …
1151 output for these property strings, e.g.: 1262 output for these property strings, e.g.:
1152 1263
1153 $json =~ s/"__proto__"\s*:/"__proto__renamed":/g; 1264 $json =~ s/"__proto__"\s*:/"__proto__renamed":/g;
1154 1265
1155 This works because "__proto__" is not valid outside of strings, so every 1266 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. 1267 occurrence of ""__proto__"\s*:" must be a string used as property name.
1157 1268
1158 If you know of other incompatibilities, please let me know. 1269 If you know of other incompatibilities, please let me know.
1159 1270
1160 JSON and YAML 1271 JSON and YAML
1161 You often hear that JSON is a subset of YAML. This is, however, a mass 1272 You often hear that JSON is a subset of YAML. This is, however, a mass
… …
1312 to see whether you are vulnerable to some common attack vectors (which 1423 to see whether you are vulnerable to some common attack vectors (which
1313 really are browser design bugs, but it is still you who will have to 1424 really are browser design bugs, but it is still you who will have to
1314 deal with it, as major browser developers care only for features, not 1425 deal with it, as major browser developers care only for features, not
1315 about getting security right). 1426 about getting security right).
1316 1427
1428INTEROPERABILITY WITH OTHER MODULES
1429 "JSON::XS" uses the Types::Serialiser module to provide boolean
1430 constants. That means that the JSON true and false values will be
1431 comaptible to true and false values of iother modules that do the same,
1432 such as JSON::PP and CBOR::XS.
1433
1317THREADS 1434THREADS
1318 This module is *not* guaranteed to be thread safe and there are no plans 1435 This module is *not* guaranteed to be thread safe and there are no plans
1319 to change this until Perl gets thread support (as opposed to the 1436 to change this until Perl gets thread support (as opposed to the
1320 horribly slow so-called "threads" which are simply slow and bloated 1437 horribly slow so-called "threads" which are simply slow and bloated
1321 process simulations - use fork, it's *much* faster, cheaper, better). 1438 process simulations - use fork, it's *much* faster, cheaper, better).
1322 1439
1323 (It might actually work, but you have been warned). 1440 (It might actually work, but you have been warned).
1324 1441
1442THE PERILS OF SETLOCALE
1443 Sometimes people avoid the Perl locale support and directly call the
1444 system's setlocale function with "LC_ALL".
1445
1446 This breaks both perl and modules such as JSON::XS, as stringification
1447 of numbers no longer works correctly (e.g. "$x = 0.1; print "$x"+1"
1448 might print 1, and JSON::XS might output illegal JSON as JSON::XS relies
1449 on perl to stringify numbers).
1450
1451 The solution is simple: don't call "setlocale", or use it for only those
1452 categories you need, such as "LC_MESSAGES" or "LC_CTYPE".
1453
1454 If you need "LC_NUMERIC", you should enable it only around the code that
1455 actually needs it (avoiding stringification of numbers), and restore it
1456 afterwards.
1457
1325BUGS 1458BUGS
1326 While the goal of this module is to be correct, that unfortunately does 1459 While the goal of this module is to be correct, that unfortunately does
1327 not mean it's bug-free, only that I think its design is bug-free. If you 1460 not mean it's bug-free, only that I think its design is bug-free. If you
1328 keep reporting bugs they will be fixed swiftly, though. 1461 keep reporting bugs they will be fixed swiftly, though.
1329 1462

Diff Legend

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