--- JSON-XS/XS.pm 2007/12/05 10:59:28 1.78 +++ JSON-XS/XS.pm 2008/01/20 19:19:07 1.83 @@ -776,16 +776,18 @@ =item blessed objects -Blessed objects are not allowed. JSON::XS currently tries to encode their -underlying representation (hash- or arrayref), but this behaviour might -change in future versions. +Blessed objects are not directly representable in JSON. See the +C and C methods on various options on +how to deal with this: basically, you can choose between throwing an +exception, encoding the reference as if it weren't blessed, or provide +your own serialiser method. =item simple scalars Simple Perl scalars (any scalar that is not a reference) are the most difficult objects to encode: JSON::XS will encode undefined scalars as -JSON null value, scalars that have last been used in a string context -before encoding as JSON strings and anything else as number value: +JSON C values, scalars that have last been used in a string context +before encoding as JSON strings, and anything else as number value: # dump as number encode_json [2] # yields [2] @@ -813,7 +815,8 @@ $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. +if you need this capability (but don't forget to explain why its needed +:). =back @@ -907,9 +910,10 @@ =head2 JSON and YAML -You often hear that JSON is a subset (or a close 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. +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. If you really must use JSON::XS to generate YAML, you should use this algorithm (subject to change in future versions): @@ -917,15 +921,47 @@ my $to_yaml = JSON::XS->new->utf8->space_after (1); my $yaml = $to_yaml->encode ($ref) . "\n"; -This will usually generate JSON texts that also parse as valid +This will I generate JSON texts that also parse as valid YAML. Please note that YAML has hardcoded limits on (simple) object key -lengths that JSON doesn't have, so you should make sure that your hash -keys are noticeably shorter than the 1024 characters YAML allows. +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). + +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 +general you should not try to generate YAML with a JSON generator or vice +versa, or try to parse JSON with a YAML parser or vice versa: chances are +high that you will run into severe interoperability problems when you +least expect it. -There might be other incompatibilities that I am not aware of. In general -you should not try to generate YAML with a JSON generator or vice versa, -or try to parse JSON with a YAML parser or vice versa: chances are high -that you will run into severe interoperability problems. +=over 4 + +=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. + +=back =head2 SPEED @@ -1012,7 +1048,7 @@ arrays. The C stack is a limited resource: for instance, on my amd64 machine with 8MB of stack size I can decode around 180k nested arrays but only 14k nested JSON objects (due to perl itself recursing deeply on croak -to free the temporary). If that is exceeded, the program crashes. to be +to free the temporary). If that is exceeded, the program crashes. To be conservative, the default nesting limit is set to 512. If your process has a smaller stack, you should adjust this setting accordingly with the C method. @@ -1026,7 +1062,7 @@ L to see whether you are vulnerable to some common attack vectors (which really are browser design bugs, but it is still you who will have to deal with it, as major -browser developers care only for features, not about doing security +browser developers care only for features, not about getting security right).