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.37 by root, Thu May 23 09:32:02 2013 UTC

… …
369 output JSON objects by sorting their keys. This is adding a 369 output JSON objects by sorting their keys. This is adding a
370 comparatively high overhead. 370 comparatively high overhead.
371 371
372 If $enable is false, then the "encode" method will output key-value 372 If $enable is false, then the "encode" method will output key-value
373 pairs in the order Perl stores them (which will likely change 373 pairs in the order Perl stores them (which will likely change
374 between runs of the same script). 374 between runs of the same script, and can change even within the same
375 run from 5.18 onwards).
375 376
376 This option is useful if you want the same data structure to be 377 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 378 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 379 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 380 contains the same data, as key-value pairs have no inherent ordering
… …
636 calls). 637 calls).
637 638
638 JSON::XS will only attempt to parse the JSON text once it is sure it has 639 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 640 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 641 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. 642 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 643 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 644 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 645 resource limits (e.g. "max_size") to ensure the parser will stop parsing
645 in the presence if syntax errors. 646 in the presence if syntax errors.
646 647
… …
1143 characters as well - using "eval" naively simply *will* cause problems. 1144 characters as well - using "eval" naively simply *will* cause problems.
1144 1145
1145 Another problem is that some javascript implementations reserve some 1146 Another problem is that some javascript implementations reserve some
1146 property names for their own purposes (which probably makes them 1147 property names for their own purposes (which probably makes them
1147 non-ECMAscript-compliant). For example, Iceweasel reserves the 1148 non-ECMAscript-compliant). For example, Iceweasel reserves the
1148 "__proto__" property name for it's own purposes. 1149 "__proto__" property name for its own purposes.
1149 1150
1150 If that is a problem, you could parse try to filter the resulting JSON 1151 If that is a problem, you could parse try to filter the resulting JSON
1151 output for these property strings, e.g.: 1152 output for these property strings, e.g.:
1152 1153
1153 $json =~ s/"__proto__"\s*:/"__proto__renamed":/g; 1154 $json =~ s/"__proto__"\s*:/"__proto__renamed":/g;
… …
1201 (which is not that difficult or long) and finally make YAML 1202 (which is not that difficult or long) and finally make YAML
1202 compatible to it, and educating users about the changes, instead of 1203 compatible to it, and educating users about the changes, instead of
1203 spreading lies about the real compatibility for many *years* and 1204 spreading lies about the real compatibility for many *years* and
1204 trying to silence people who point out that it isn't true. 1205 trying to silence people who point out that it isn't true.
1205 1206
1206 Addendum/2009: the YAML 1.2 spec is still incomaptible with JSON, 1207 Addendum/2009: the YAML 1.2 spec is still incompatible with JSON,
1207 even though the incompatibilities have been documented (and are 1208 even though the incompatibilities have been documented (and are
1208 known to Brian) for many years and the spec makes explicit claims 1209 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 1210 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. 1211 apparently, bullying people and corrupting userdata is so much
1212 easier.
1211 1213
1212 SPEED 1214 SPEED
1213 It seems that JSON::XS is surprisingly fast, as shown in the following 1215 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 1216 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 1217 in the JSON::XS distribution, to make it easy to compare on your own
… …
1319 horribly slow so-called "threads" which are simply slow and bloated 1321 horribly slow so-called "threads" which are simply slow and bloated
1320 process simulations - use fork, it's *much* faster, cheaper, better). 1322 process simulations - use fork, it's *much* faster, cheaper, better).
1321 1323
1322 (It might actually work, but you have been warned). 1324 (It might actually work, but you have been warned).
1323 1325
1326THE PERILS OF SETLOCALE
1327 Sometimes people avoid the Perl locale support and directly call the
1328 system's setlocale function with "LC_ALL".
1329
1330 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
1332 print 1, and JSON::XS might output illegal JSON as JSON::XS relies on
1333 perl to stringify numbers).
1334
1335 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".
1337
1338 If you need "LC_NUMERIC", you should enable it only around the code that
1339 actually needs it (avoiding stringification of numbers), and restore it
1340 afterwards.
1341
1324BUGS 1342BUGS
1325 While the goal of this module is to be correct, that unfortunately does 1343 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 1344 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. 1345 keep reporting bugs they will be fixed swiftly, though.
1328 1346

Diff Legend

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