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.82 by root, Sun Dec 30 21:24:57 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
… …
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.
935 939
936=over 4 940=over 4
937 941
938=item (*) 942=item (*)
939 943
… …
943Even the author of this manpage was at some point accused of providing 947Even the author of this manpage was at some point accused of providing
944"incorrect" information, despite the evidence presented (claims ranged 948"incorrect" information, despite the evidence presented (claims ranged
945from "your documentation contains inaccurate and negative statements about 949from "your documentation contains inaccurate and negative statements about
946YAML" (the only negative comment is this footnote, and it didn't exist 950YAML" (the only negative comment is this footnote, and it didn't exist
947back then; the question on which claims were inaccurate was never answered 951back 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 952etc.) to "the YAML spec is not up-to-date" (the *real* and supposedly
949JSON-compatible spec is apparently not currently publicly available) 953JSON-compatible spec is apparently not currently publicly available)
950to actual requests to replace this section by *incorrect* information, 954to actual requests to replace this section by *incorrect* information,
951suppressing information about the real problem). 955suppressing information about the real problem).
952 956
953So whenever you are told that YAML was a superset of JSON, first check 957So 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 958wether it is really true (it might be when you check it, but it certainly
955is not true when this was written). I would much prefer if the YAML team 959was 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 960would spent their time on actually making JSON compatibility a truth
957(JSON, after all, has a very small and simple specification) instead of 961(JSON, after all, has a very small and simple specification) instead of
958trying to lobby/force people into reporting untruths. 962trying to lobby/force people into reporting untruths.
959 963
960=back 964=back

Diff Legend

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