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.81 by root, Sat Dec 29 17:33:38 2007 UTC vs.
Revision 1.83 by root, Sun Jan 20 19:19:07 2008 UTC

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

Diff Legend

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