ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/JSON-XS/XS.pm
(Generate patch)

Comparing JSON-XS/XS.pm (file contents):
Revision 1.78 by root, Wed Dec 5 10:59:28 2007 UTC vs.
Revision 1.82 by root, Sun Dec 30 21:24:57 2007 UTC

… …
905=back 905=back
906 906
907 907
908=head2 JSON and YAML 908=head2 JSON and YAML
909 909
910You often hear that JSON is a subset (or a close subset) of YAML. This is, 910You often hear that JSON is a subset of YAML. This is, however, a mass
911however, a mass hysteria and very far from the truth. In general, there is 911hysteria(*) and very far from the truth. In general, there is no way to
912no way to configure JSON::XS to output a data structure as valid YAML. 912configure JSON::XS to output a data structure as valid YAML that works for
913all cases.
913 914
914If you really must use JSON::XS to generate YAML, you should use this 915If you really must use JSON::XS to generate YAML, you should use this
915algorithm (subject to change in future versions): 916algorithm (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
920This will usually generate JSON texts that also parse as valid 921This will usually generate JSON texts that also parse as valid
921YAML. Please note that YAML has hardcoded limits on (simple) object key 922YAML. Please note that YAML has hardcoded limits on (simple) object key
922lengths that JSON doesn't have, so you should make sure that your hash 923lengths that JSON doesn't have and also has different and incompatible
924unicode handling, so you should make sure that your hash keys are
923keys are noticeably shorter than the 1024 characters YAML allows. 925noticeably shorter than the 1024 "stream characters" YAML allows and that
926you do not have codepoints with values outside the Unicode BMP (basic
927multilingual page). YAML also does not allow C<\/> sequences in strings
928(which JSON::XS does not I<currently> generate).
924 929
925There might be other incompatibilities that I am not aware of. In general 930There might be other incompatibilities that I am not aware of. In general
926you should not try to generate YAML with a JSON generator or vice versa, 931you should not try to generate YAML with a JSON generator or vice versa,
927or try to parse JSON with a YAML parser or vice versa: chances are high 932or try to parse JSON with a YAML parser or vice versa: chances are high
928that you will run into severe interoperability problems. 933that you will run into severe interoperability problems when you least
934expect it.
935
936=over 4
937
938=item (*)
939
940This is spread actively by the YAML team, however. For many years now they
941claim YAML were a superset of JSON, even when proven otherwise.
942
943Even the author of this manpage was at some point accused of providing
944"incorrect" information, despite the evidence presented (claims ranged
945from "your documentation contains inaccurate and negative statements about
946YAML" (the only negative comment is this footnote, and it didn't exist
947back then; the question on which claims were inaccurate was never answered
948etc.) to "the YAML spec is not up-to-date" (the *real* and suppsedly
949JSON-compatible spec is apparently not currently publicly available)
950to actual requests to replace this section by *incorrect* information,
951suppressing information about the real problem).
952
953So whenever you are told that YAML was a superset of JSON, first check
954wether it is really true (it might be when you check it, but it cetrainly
955is not true when this was written). I would much prefer if the YAML team
956would spent their time on actually making JSON compatibility a truth
957(JSON, after all, has a very small and simple specification) instead of
958trying to lobby/force people into reporting untruths.
959
960=back
929 961
930 962
931=head2 SPEED 963=head2 SPEED
932 964
933It seems that JSON::XS is surprisingly fast, as shown in the following 965It seems that JSON::XS is surprisingly fast, as shown in the following
… …
1010 1042
1011Third, JSON::XS recurses using the C stack when decoding objects and 1043Third, JSON::XS recurses using the C stack when decoding objects and
1012arrays. The C stack is a limited resource: for instance, on my amd64 1044arrays. The C stack is a limited resource: for instance, on my amd64
1013machine with 8MB of stack size I can decode around 180k nested arrays but 1045machine with 8MB of stack size I can decode around 180k nested arrays but
1014only 14k nested JSON objects (due to perl itself recursing deeply on croak 1046only 14k nested JSON objects (due to perl itself recursing deeply on croak
1015to free the temporary). If that is exceeded, the program crashes. to be 1047to free the temporary). If that is exceeded, the program crashes. To be
1016conservative, the default nesting limit is set to 512. If your process 1048conservative, the default nesting limit is set to 512. If your process
1017has a smaller stack, you should adjust this setting accordingly with the 1049has a smaller stack, you should adjust this setting accordingly with the
1018C<max_depth> method. 1050C<max_depth> method.
1019 1051
1020And last but least, something else could bomb you that I forgot to think 1052And last but least, something else could bomb you that I forgot to think
… …
1024If you are using JSON::XS to return packets to consumption 1056If you are using JSON::XS to return packets to consumption
1025by JavaScript scripts in a browser you should have a look at 1057by JavaScript scripts in a browser you should have a look at
1026L<http://jpsykes.com/47/practical-csrf-and-json-security> to see whether 1058L<http://jpsykes.com/47/practical-csrf-and-json-security> to see whether
1027you are vulnerable to some common attack vectors (which really are browser 1059you are vulnerable to some common attack vectors (which really are browser
1028design bugs, but it is still you who will have to deal with it, as major 1060design bugs, but it is still you who will have to deal with it, as major
1029browser developers care only for features, not about doing security 1061browser developers care only for features, not about getting security
1030right). 1062right).
1031 1063
1032 1064
1033=head1 THREADS 1065=head1 THREADS
1034 1066

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines