… | |
… | |
905 | =back |
905 | =back |
906 | |
906 | |
907 | |
907 | |
908 | =head2 JSON and YAML |
908 | =head2 JSON and YAML |
909 | |
909 | |
910 | You often hear that JSON is a subset (or a close subset) of YAML. This is, |
910 | You often hear that JSON is a subset of YAML. This is, however, a mass |
911 | however, a mass hysteria and very far from the truth. In general, there is |
911 | hysteria(*) and very far from the truth. In general, there is no way to |
912 | no way to configure JSON::XS to output a data structure as valid YAML. |
912 | configure JSON::XS to output a data structure as valid YAML that works for |
|
|
913 | all cases. |
913 | |
914 | |
914 | If you really must use JSON::XS to generate YAML, you should use this |
915 | If you really must use JSON::XS to generate YAML, you should use this |
915 | algorithm (subject to change in future versions): |
916 | algorithm (subject to change in future versions): |
916 | |
917 | |
917 | my $to_yaml = JSON::XS->new->utf8->space_after (1); |
918 | my $to_yaml = JSON::XS->new->utf8->space_after (1); |
918 | my $yaml = $to_yaml->encode ($ref) . "\n"; |
919 | my $yaml = $to_yaml->encode ($ref) . "\n"; |
919 | |
920 | |
920 | This will usually generate JSON texts that also parse as valid |
921 | This will usually generate JSON texts that also parse as valid |
921 | YAML. Please note that YAML has hardcoded limits on (simple) object key |
922 | YAML. Please note that YAML has hardcoded limits on (simple) object key |
922 | lengths that JSON doesn't have, so you should make sure that your hash |
923 | lengths that JSON doesn't have and also has different and incompatible |
|
|
924 | unicode handling, so you should make sure that your hash keys are |
923 | keys are noticeably shorter than the 1024 characters YAML allows. |
925 | noticeably shorter than the 1024 "stream characters" YAML allows and that |
|
|
926 | you do not have codepoints with values outside the Unicode BMP (basic |
|
|
927 | multilingual page). YAML also does not allow C<\/> sequences in strings |
|
|
928 | (which JSON::XS does not I<currently> generate). |
924 | |
929 | |
925 | There might be other incompatibilities that I am not aware of. In general |
930 | There might be other incompatibilities that I am not aware of. In general |
926 | you should not try to generate YAML with a JSON generator or vice versa, |
931 | you should not try to generate YAML with a JSON generator or vice versa, |
927 | or try to parse JSON with a YAML parser or vice versa: chances are high |
932 | or try to parse JSON with a YAML parser or vice versa: chances are high |
928 | that you will run into severe interoperability problems. |
933 | that you will run into severe interoperability problems when you least |
|
|
934 | expect it. |
|
|
935 | |
|
|
936 | =over 4 |
|
|
937 | |
|
|
938 | =item (*) |
|
|
939 | |
|
|
940 | This is spread actively by the YAML team, however. For many years now they |
|
|
941 | claim YAML were a superset of JSON, even when proven otherwise. |
|
|
942 | |
|
|
943 | Even the author of this manpage was at some point accused of providing |
|
|
944 | "incorrect" information, despite the evidence presented (claims ranged |
|
|
945 | from "your documentation contains inaccurate and negative statements about |
|
|
946 | YAML" (the only negative comment is this footnote, and it didn't exist |
|
|
947 | back then; the question on which claims were inaccurate was never answered |
|
|
948 | etc.) to "the YAML spec is not up-to-date" (the *real* and suppsedly |
|
|
949 | JSON-compatible spec is apparently not currently publicly available) |
|
|
950 | to actual requests to replace this section by *incorrect* information, |
|
|
951 | suppressing information about the real problem). |
|
|
952 | |
|
|
953 | So whenever you are told that YAML was a superset of JSON, first check |
|
|
954 | wether it is really true (it might be when you check it, but it cetrainly |
|
|
955 | is not true when this was written). I would much prefer if the YAML team |
|
|
956 | would spent their time on actually making JSON compatibility a truth |
|
|
957 | (JSON, after all, has a very small and simple specification) instead of |
|
|
958 | trying to lobby/force people into reporting untruths. |
|
|
959 | |
|
|
960 | =back |
929 | |
961 | |
930 | |
962 | |
931 | =head2 SPEED |
963 | =head2 SPEED |
932 | |
964 | |
933 | It seems that JSON::XS is surprisingly fast, as shown in the following |
965 | It seems that JSON::XS is surprisingly fast, as shown in the following |