--- JSON-XS/XS.pm 2007/12/05 10:59:28 1.78 +++ JSON-XS/XS.pm 2007/12/29 17:33:38 1.81 @@ -907,9 +907,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): @@ -919,13 +920,18 @@ This will usually 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. 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. +that you will run into severe interoperability problems when you least +expect it. =head2 SPEED @@ -1012,7 +1018,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 +1032,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).