… | |
… | |
774 | These special values become JSON true and JSON false values, |
774 | These special values become JSON true and JSON false values, |
775 | respectively. You can also use C<\1> and C<\0> directly if you want. |
775 | respectively. You can also use C<\1> and C<\0> directly if you want. |
776 | |
776 | |
777 | =item blessed objects |
777 | =item blessed objects |
778 | |
778 | |
779 | Blessed objects are not allowed. JSON::XS currently tries to encode their |
779 | Blessed objects are not directly representable in JSON. See the |
780 | underlying representation (hash- or arrayref), but this behaviour might |
780 | C<allow_blessed> and C<convert_blessed> methods on various options on |
781 | change in future versions. |
781 | how to deal with this: basically, you can choose between throwing an |
|
|
782 | exception, encoding the reference as if it weren't blessed, or provide |
|
|
783 | your own serialiser method. |
782 | |
784 | |
783 | =item simple scalars |
785 | =item simple scalars |
784 | |
786 | |
785 | Simple Perl scalars (any scalar that is not a reference) are the most |
787 | Simple Perl scalars (any scalar that is not a reference) are the most |
786 | difficult objects to encode: JSON::XS will encode undefined scalars as |
788 | difficult objects to encode: JSON::XS will encode undefined scalars as |
787 | JSON null value, scalars that have last been used in a string context |
789 | JSON C<null> values, scalars that have last been used in a string context |
788 | before encoding as JSON strings and anything else as number value: |
790 | before encoding as JSON strings, and anything else as number value: |
789 | |
791 | |
790 | # dump as number |
792 | # dump as number |
791 | encode_json [2] # yields [2] |
793 | encode_json [2] # yields [2] |
792 | encode_json [-3.0e17] # yields [-3e+17] |
794 | encode_json [-3.0e17] # yields [-3e+17] |
793 | my $value = 5; encode_json [$value] # yields [5] |
795 | my $value = 5; encode_json [$value] # yields [5] |
… | |
… | |
811 | my $x = "3"; # some variable containing a string |
813 | my $x = "3"; # some variable containing a string |
812 | $x += 0; # numify it, ensuring it will be dumped as a number |
814 | $x += 0; # numify it, ensuring it will be dumped as a number |
813 | $x *= 1; # same thing, the choice is yours. |
815 | $x *= 1; # same thing, the choice is yours. |
814 | |
816 | |
815 | You can not currently force the type in other, less obscure, ways. Tell me |
817 | You can not currently force the type in other, less obscure, ways. Tell me |
816 | if you need this capability. |
818 | if you need this capability (but don't forget to explain why its needed |
|
|
819 | :). |
817 | |
820 | |
818 | =back |
821 | =back |
819 | |
822 | |
820 | |
823 | |
821 | =head1 COMPARISON |
824 | =head1 COMPARISON |
… | |
… | |
906 | |
909 | |
907 | |
910 | |
908 | =head2 JSON and YAML |
911 | =head2 JSON and YAML |
909 | |
912 | |
910 | You often hear that JSON is a subset of YAML. This is, however, a mass |
913 | You often hear that JSON is a subset of YAML. This is, however, a mass |
911 | hysteria and very far from the truth. In general, there is no way to |
914 | hysteria(*) and very far from the truth. In general, there is no way to |
912 | configure JSON::XS to output a data structure as valid YAML that works for |
915 | configure JSON::XS to output a data structure as valid YAML that works for |
913 | all cases. |
916 | all cases. |
914 | |
917 | |
915 | If you really must use JSON::XS to generate YAML, you should use this |
918 | If you really must use JSON::XS to generate YAML, you should use this |
916 | algorithm (subject to change in future versions): |
919 | algorithm (subject to change in future versions): |
917 | |
920 | |
918 | my $to_yaml = JSON::XS->new->utf8->space_after (1); |
921 | my $to_yaml = JSON::XS->new->utf8->space_after (1); |
919 | my $yaml = $to_yaml->encode ($ref) . "\n"; |
922 | my $yaml = $to_yaml->encode ($ref) . "\n"; |
920 | |
923 | |
921 | This will usually generate JSON texts that also parse as valid |
924 | This will I<usually> generate JSON texts that also parse as valid |
922 | YAML. Please note that YAML has hardcoded limits on (simple) object key |
925 | YAML. Please note that YAML has hardcoded limits on (simple) object key |
923 | lengths that JSON doesn't have and also has different and incompatible |
926 | 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 |
927 | unicode handling, so you should make sure that your hash keys are |
925 | noticeably shorter than the 1024 "stream characters" YAML allows and that |
928 | noticeably shorter than the 1024 "stream characters" YAML allows and that |
926 | you do not have codepoints with values outside the Unicode BMP (basic |
929 | you do not have codepoints with values outside the Unicode BMP (basic |
927 | multilingual page). YAML also does not allow C<\/> sequences in strings |
930 | multilingual page). YAML also does not allow C<\/> sequences in strings |
928 | (which JSON::XS does not I<currently> generate). |
931 | (which JSON::XS does not I<currently> generate). |
929 | |
932 | |
930 | There might be other incompatibilities that I am not aware of. In general |
933 | There might be other incompatibilities that I am not aware of (or the YAML |
|
|
934 | specification has been changed yet again - it does so quite often). In |
931 | you should not try to generate YAML with a JSON generator or vice versa, |
935 | general you should not try to generate YAML with a JSON generator or vice |
932 | or try to parse JSON with a YAML parser or vice versa: chances are high |
936 | versa, or try to parse JSON with a YAML parser or vice versa: chances are |
933 | that you will run into severe interoperability problems when you least |
937 | high that you will run into severe interoperability problems when you |
934 | expect it. |
938 | least expect it. |
|
|
939 | |
|
|
940 | =over 4 |
|
|
941 | |
|
|
942 | =item (*) |
|
|
943 | |
|
|
944 | This is spread actively by the YAML team, however. For many years now they |
|
|
945 | claim YAML were a superset of JSON, even when proven otherwise. |
|
|
946 | |
|
|
947 | Even the author of this manpage was at some point accused of providing |
|
|
948 | "incorrect" information, despite the evidence presented (claims ranged |
|
|
949 | from "your documentation contains inaccurate and negative statements about |
|
|
950 | YAML" (the only negative comment is this footnote, and it didn't exist |
|
|
951 | back then; the question on which claims were inaccurate was never answered |
|
|
952 | etc.) to "the YAML spec is not up-to-date" (the *real* and supposedly |
|
|
953 | JSON-compatible spec is apparently not currently publicly available) |
|
|
954 | to actual requests to replace this section by *incorrect* information, |
|
|
955 | suppressing information about the real problem). |
|
|
956 | |
|
|
957 | So whenever you are told that YAML was a superset of JSON, first check |
|
|
958 | wether it is really true (it might be when you check it, but it certainly |
|
|
959 | was not true when this was written). I would much prefer if the YAML team |
|
|
960 | would spent their time on actually making JSON compatibility a truth |
|
|
961 | (JSON, after all, has a very small and simple specification) instead of |
|
|
962 | trying to lobby/force people into reporting untruths. |
|
|
963 | |
|
|
964 | =back |
935 | |
965 | |
936 | |
966 | |
937 | =head2 SPEED |
967 | =head2 SPEED |
938 | |
968 | |
939 | It seems that JSON::XS is surprisingly fast, as shown in the following |
969 | It seems that JSON::XS is surprisingly fast, as shown in the following |