--- JSON-XS/XS.pm 2008/03/19 13:54:53 1.89 +++ JSON-XS/XS.pm 2008/03/19 22:28:43 1.90 @@ -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; @@ -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