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.89 by root, Wed Mar 19 13:54:53 2008 UTC vs.
Revision 1.90 by root, Wed Mar 19 22:28:43 2008 UTC

… …
103 103
104package JSON::XS; 104package JSON::XS;
105 105
106use strict; 106use strict;
107 107
108our $VERSION = '2.01'; 108our $VERSION = '2.1';
109our @ISA = qw(Exporter); 109our @ISA = qw(Exporter);
110 110
111our @EXPORT = qw(encode_json decode_json to_json from_json); 111our @EXPORT = qw(encode_json decode_json to_json from_json);
112 112
113sub to_json($) { 113sub to_json($) {
… …
245 245
246If C<$enable> is false, then the C<encode> method will not escape Unicode 246If C<$enable> is false, then the C<encode> method will not escape Unicode
247characters unless required by the JSON syntax or other flags. This results 247characters unless required by the JSON syntax or other flags. This results
248in a faster and more compact format. 248in a faster and more compact format.
249 249
250See also the section I<ENCODING/CODESET FLAG NOTES> later in this
251document.
252
250The main use for this flag is to produce JSON texts that can be 253The main use for this flag is to produce JSON texts that can be
251transmitted over a 7-bit channel, as the encoded JSON texts will not 254transmitted over a 7-bit channel, as the encoded JSON texts will not
252contain any 8 bit characters. 255contain any 8 bit characters.
253 256
254 JSON::XS->new->ascii (1)->encode ([chr 0x10401]) 257 JSON::XS->new->ascii (1)->encode ([chr 0x10401])
… …
265will not be affected in any way by this flag, as C<decode> by default 268will not be affected in any way by this flag, as C<decode> by default
266expects Unicode, which is a strict superset of latin1. 269expects Unicode, which is a strict superset of latin1.
267 270
268If C<$enable> is false, then the C<encode> method will not escape Unicode 271If C<$enable> is false, then the C<encode> method will not escape Unicode
269characters unless required by the JSON syntax or other flags. 272characters unless required by the JSON syntax or other flags.
273
274See also the section I<ENCODING/CODESET FLAG NOTES> later in this
275document.
270 276
271The main use for this flag is efficiently encoding binary data as JSON 277The main use for this flag is efficiently encoding binary data as JSON
272text, as most octets will not be escaped, resulting in a smaller encoded 278text, as most octets will not be escaped, resulting in a smaller encoded
273size. The disadvantage is that the resulting JSON text is encoded 279size. The disadvantage is that the resulting JSON text is encoded
274in latin1 (and must correctly be treated as such when storing and 280in latin1 (and must correctly be treated as such when storing and
… …
293 299
294If C<$enable> is false, then the C<encode> method will return the JSON 300If C<$enable> is false, then the C<encode> method will return the JSON
295string as a (non-encoded) Unicode string, while C<decode> expects thus a 301string as a (non-encoded) Unicode string, while C<decode> expects thus a
296Unicode string. Any decoding or encoding (e.g. to UTF-8 or UTF-16) needs 302Unicode string. Any decoding or encoding (e.g. to UTF-8 or UTF-16) needs
297to be done yourself, e.g. using the Encode module. 303to be done yourself, e.g. using the Encode module.
304
305See also the section I<ENCODING/CODESET FLAG NOTES> later in this
306document.
298 307
299Example, output UTF-16BE-encoded JSON: 308Example, output UTF-16BE-encoded JSON:
300 309
301 use Encode; 310 use Encode;
302 $jsontext = encode "UTF-16BE", JSON::XS->new->encode ($object); 311 $jsontext = encode "UTF-16BE", JSON::XS->new->encode ($object);
… …
1021 1030
1022 1031
1023=head2 JSON and YAML 1032=head2 JSON and YAML
1024 1033
1025You often hear that JSON is a subset of YAML. This is, however, a mass 1034You often hear that JSON is a subset of YAML. This is, however, a mass
1026hysteria(*) and very far from the truth. In general, there is no way to 1035hysteria(*) and very far from the truth (as of the time of this writing),
1036so let me state it clearly: I<in general, there is no way to configure
1027configure JSON::XS to output a data structure as valid YAML that works for 1037JSON::XS to output a data structure as valid YAML> that works in all
1028all cases. 1038cases.
1029 1039
1030If you really must use JSON::XS to generate YAML, you should use this 1040If you really must use JSON::XS to generate YAML, you should use this
1031algorithm (subject to change in future versions): 1041algorithm (subject to change in future versions):
1032 1042
1033 my $to_yaml = JSON::XS->new->utf8->space_after (1); 1043 my $to_yaml = JSON::XS->new->utf8->space_after (1);
… …
1036This will I<usually> generate JSON texts that also parse as valid 1046This will I<usually> generate JSON texts that also parse as valid
1037YAML. Please note that YAML has hardcoded limits on (simple) object key 1047YAML. Please note that YAML has hardcoded limits on (simple) object key
1038lengths that JSON doesn't have and also has different and incompatible 1048lengths that JSON doesn't have and also has different and incompatible
1039unicode handling, so you should make sure that your hash keys are 1049unicode handling, so you should make sure that your hash keys are
1040noticeably shorter than the 1024 "stream characters" YAML allows and that 1050noticeably shorter than the 1024 "stream characters" YAML allows and that
1041you do not have codepoints with values outside the Unicode BMP (basic 1051you do not have characters with codepoint values outside the Unicode BMP
1042multilingual page). YAML also does not allow C<\/> sequences in strings 1052(basic multilingual page). YAML also does not allow C<\/> sequences in
1043(which JSON::XS does not I<currently> generate). 1053strings (which JSON::XS does not I<currently> generate, but other JSON
1054generators might).
1044 1055
1045There might be other incompatibilities that I am not aware of (or the YAML 1056There might be other incompatibilities that I am not aware of (or the YAML
1046specification has been changed yet again - it does so quite often). In 1057specification has been changed yet again - it does so quite often). In
1047general you should not try to generate YAML with a JSON generator or vice 1058general you should not try to generate YAML with a JSON generator or vice
1048versa, or try to parse JSON with a YAML parser or vice versa: chances are 1059versa, or try to parse JSON with a YAML parser or vice versa: chances are
… …
1051 1062
1052=over 4 1063=over 4
1053 1064
1054=item (*) 1065=item (*)
1055 1066
1056This is spread actively by the YAML team, however. For many years now they 1067I have been pressured multiple times by Brian Ingerson (one of the
1057claim YAML were a superset of JSON, even when proven otherwise. 1068authors of the YAML specification) to remove this paragraph, despite him
1069acknowledging that the actual incompatibilities exist. As I was personally
1070bitten by this "JSON is YAML" lie, I refused and said I will continue to
1071educate people about these issues, so others do not run into the same
1072problem again and again. After this, Brian called me a (quote)I<complete
1073and worthless idiot>(unquote).
1058 1074
1059Even the author of this manpage was at some point accused of providing 1075In my opinion, instead of pressuring and insulting people who actually
1060"incorrect" information, despite the evidence presented (claims ranged 1076clarify issues with YAML and the wrong statements of some of its
1061from "your documentation contains inaccurate and negative statements about 1077proponents, I would kindly suggest reading the JSON spec (which is not
1062YAML" (the only negative comment is this footnote, and it didn't exist 1078that difficult or long) and finally make YAML compatible to it, and
1063back then; the question on which claims were inaccurate was never answered 1079educating users about the changes, instead of spreading lies about the
1064etc.) to "the YAML spec is not up-to-date" (the *real* and supposedly 1080real compatibility for many I<years> and trying to silence people who
1065JSON-compatible spec is apparently not currently publicly available) 1081point out that it isn't true.
1066to actual requests to replace this section by *incorrect* information,
1067suppressing information about the real problem).
1068
1069So whenever you are told that YAML was a superset of JSON, first check
1070wether it is really true (it might be when you check it, but it certainly
1071was not true when this was written). I would much prefer if the YAML team
1072would spent their time on actually making JSON compatibility a truth
1073(JSON, after all, has a very small and simple specification) instead of
1074trying to lobby/force people into reporting untruths.
1075 1082
1076=back 1083=back
1077 1084
1078 1085
1079=head2 SPEED 1086=head2 SPEED

Diff Legend

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