--- JSON-XS/XS.pm 2008/03/19 02:55:23 1.85 +++ JSON-XS/XS.pm 2008/03/21 21:47:43 1.92 @@ -1,7 +1,7 @@ -=encoding utf-8 - =head1 NAME +=encoding utf-8 + JSON::XS - JSON serialising/deserialising, done correctly and fast JSON::XS - 正しくて高速な JSON シリアライザ/デシリアライザ @@ -105,7 +105,7 @@ use strict; -our $VERSION = '2.01'; +our $VERSION = '2.1'; our @ISA = qw(Exporter); our @EXPORT = qw(encode_json decode_json to_json from_json); @@ -247,6 +247,9 @@ characters unless required by the JSON syntax or other flags. This results in a faster and more compact format. +See also the section I later in this +document. + The main use for this flag is to produce JSON texts that can be transmitted over a 7-bit channel, as the encoded JSON texts will not contain any 8 bit characters. @@ -268,6 +271,9 @@ If C<$enable> is false, then the C method will not escape Unicode characters unless required by the JSON syntax or other flags. +See also the section I later in this +document. + The main use for this flag is efficiently encoding binary data as JSON text, as most octets will not be escaped, resulting in a smaller encoded size. The disadvantage is that the resulting JSON text is encoded @@ -296,6 +302,9 @@ Unicode string. Any decoding or encoding (e.g. to UTF-8 or UTF-16) needs to be done yourself, e.g. using the Encode module. +See also the section I later in this +document. + Example, output UTF-16BE-encoded JSON: use Encode; @@ -818,7 +827,7 @@ $x *= 1; # same thing, the choice is yours. You can not currently force the type in other, less obscure, ways. Tell me -if you need this capability (but don't forget to explain why its needed +if you need this capability (but don't forget to explain why it's needed :). =back @@ -830,9 +839,9 @@ encodings or codesets - C, C and C. There seems to be some confusion on what these do, so here is a short comparison: -C controls wether the JSON text created by C (and expected +C controls whether the JSON text created by C (and expected by C) is UTF-8 encoded or not, while C and C only -control wether C escapes character values outside their respective +control whether C escapes character values outside their respective codeset range. Neither of these flags conflict with each other, although some combinations make less sense than others. @@ -1023,9 +1032,10 @@ =head2 JSON and YAML You often hear that JSON is a subset of YAML. This is, however, a mass -hysteria(*) and very far from the truth. In general, there is no way to -configure JSON::XS to output a data structure as valid YAML that works for -all cases. +hysteria(*) and very far from the truth (as of the time of this writing), +so let me state it clearly: I that works in all +cases. If you really must use JSON::XS to generate YAML, you should use this algorithm (subject to change in future versions): @@ -1038,9 +1048,10 @@ lengths that JSON doesn't have and also has different and incompatible unicode handling, so you should make sure that your hash keys are noticeably shorter than the 1024 "stream characters" YAML allows and that -you do not have codepoints with values outside the Unicode BMP (basic -multilingual page). YAML also does not allow C<\/> sequences in strings -(which JSON::XS does not I generate). +you do not have characters with codepoint values outside the Unicode BMP +(basic multilingual page). YAML also does not allow C<\/> sequences in +strings (which JSON::XS does not I generate, but other JSON +generators might). There might be other incompatibilities that I am not aware of (or the YAML specification has been changed yet again - it does so quite often). In @@ -1053,25 +1064,21 @@ =item (*) -This is spread actively by the YAML team, however. For many years now they -claim YAML were a superset of JSON, even when proven otherwise. - -Even the author of this manpage was at some point accused of providing -"incorrect" information, despite the evidence presented (claims ranged -from "your documentation contains inaccurate and negative statements about -YAML" (the only negative comment is this footnote, and it didn't exist -back then; the question on which claims were inaccurate was never answered -etc.) to "the YAML spec is not up-to-date" (the *real* and supposedly -JSON-compatible spec is apparently not currently publicly available) -to actual requests to replace this section by *incorrect* information, -suppressing information about the real problem). - -So whenever you are told that YAML was a superset of JSON, first check -wether it is really true (it might be when you check it, but it certainly -was not true when this was written). I would much prefer if the YAML team -would spent their time on actually making JSON compatibility a truth -(JSON, after all, has a very small and simple specification) instead of -trying to lobby/force people into reporting untruths. +I have been pressured multiple times by Brian Ingerson (one of the +authors of the YAML specification) to remove this paragraph, despite him +acknowledging that the actual incompatibilities exist. As I was personally +bitten by this "JSON is YAML" lie, I refused and said I will continue to +educate people about these issues, so others do not run into the same +problem again and again. After this, Brian called me a (quote)I(unquote). + +In my opinion, instead of pressuring and insulting people who actually +clarify issues with YAML and the wrong statements of some of its +proponents, I would kindly suggest reading the JSON spec (which is not +that difficult or long) and finally make YAML compatible to it, and +educating users about the changes, instead of spreading lies about the +real compatibility for many I and trying to silence people who +point out that it isn't true. =back @@ -1083,8 +1090,9 @@ in the JSON::XS distribution, to make it easy to compare on your own system. -First comes a comparison between various modules using a very short -single-line JSON string: +First comes a comparison between various modules using +a very short single-line JSON string (also available at +L). {"method": "handleMessage", "params": ["user1", "we were just talking"], \ "id": null, "array":[1,11,234,-5,1e5,1e7, true, false]} @@ -1113,7 +1121,7 @@ favourably to Storable for small amounts of data. Using a longer test string (roughly 18KB, generated from Yahoo! Locals -search API (http://nanoref.com/yahooapis/mgPdGg): +search API (L). module | encode | decode | -----------|------------|------------| @@ -1165,9 +1173,13 @@ has a smaller stack, you should adjust this setting accordingly with the C method. -And last but least, something else could bomb you that I forgot to think -of. In that case, you get to keep the pieces. I am always open for hints, -though... +Something else could bomb you, too, that I forgot to think of. In that +case, you get to keep the pieces. I am always open for hints, though... + +Also keep in mind that JSON::XS might leak contents of your Perl data +structures in its error messages, so when you serialise sensitive +information you might want to make sure that exceptions thrown by JSON::XS +will not end up in front of untrusted eyes. If you are using JSON::XS to return packets to consumption by JavaScript scripts in a browser you should have a look at @@ -1183,7 +1195,7 @@ This module is I guaranteed to be thread safe and there are no plans to change this until Perl gets thread support (as opposed to the horribly slow so-called "threads" which are simply slow and bloated -process simulations - use fork, its I faster, cheaper, better). +process simulations - use fork, it's I faster, cheaper, better). (It might actually work, but you have been warned). @@ -1191,7 +1203,7 @@ =head1 BUGS While the goal of this module is to be correct, that unfortunately does -not mean its bug-free, only that I think its design is bug-free. It is +not mean it's bug-free, only that I think its design is bug-free. It is still relatively early in its development. If you keep reporting bugs they will be fixed swiftly, though.