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

Comparing JSON-XS/README (file contents):
Revision 1.27 by root, Tue Jul 15 11:29:29 2008 UTC vs.
Revision 1.31 by root, Sat Aug 8 10:06:02 2009 UTC

… …
20 $perl_scalar = $coder->decode ($unicode_json_text); 20 $perl_scalar = $coder->decode ($unicode_json_text);
21 21
22 # Note that JSON version 2.0 and above will automatically use JSON::XS 22 # Note that JSON version 2.0 and above will automatically use JSON::XS
23 # if available, at virtually no speed overhead either, so you should 23 # if available, at virtually no speed overhead either, so you should
24 # be able to just: 24 # be able to just:
25 25
26 use JSON; 26 use JSON;
27 27
28 # and do the same things, except that you have a pure-perl fallback now. 28 # and do the same things, except that you have a pure-perl fallback now.
29 29
30DESCRIPTION 30DESCRIPTION
31 This module converts Perl data structures to JSON and vice versa. Its 31 This module converts Perl data structures to JSON and vice versa. Its
… …
43 As this is the n-th-something JSON module on CPAN, what was the reason 43 As this is the n-th-something JSON module on CPAN, what was the reason
44 to write yet another JSON module? While it seems there are many JSON 44 to write yet another JSON module? While it seems there are many JSON
45 modules, none of them correctly handle all corner cases, and in most 45 modules, none of them correctly handle all corner cases, and in most
46 cases their maintainers are unresponsive, gone missing, or not listening 46 cases their maintainers are unresponsive, gone missing, or not listening
47 to bug reports for other reasons. 47 to bug reports for other reasons.
48
49 See COMPARISON, below, for a comparison to some other JSON modules.
50 48
51 See MAPPING, below, on how JSON::XS maps perl values to JSON values and 49 See MAPPING, below, on how JSON::XS maps perl values to JSON values and
52 vice versa. 50 vice versa.
53 51
54 FEATURES 52 FEATURES
… …
379 it is disabled, the same hash might be encoded differently even if 377 it is disabled, the same hash might be encoded differently even if
380 contains the same data, as key-value pairs have no inherent ordering 378 contains the same data, as key-value pairs have no inherent ordering
381 in Perl. 379 in Perl.
382 380
383 This setting has no effect when decoding JSON texts. 381 This setting has no effect when decoding JSON texts.
382
383 This setting has currently no effect on tied hashes.
384 384
385 $json = $json->allow_nonref ([$enable]) 385 $json = $json->allow_nonref ([$enable])
386 $enabled = $json->get_allow_nonref 386 $enabled = $json->get_allow_nonref
387 If $enable is true (or missing), then the "encode" method can 387 If $enable is true (or missing), then the "encode" method can
388 convert a non-reference into its corresponding string, number or 388 convert a non-reference into its corresponding string, number or
… …
686 after a JSON object or b) parsing multiple JSON objects separated by 686 after a JSON object or b) parsing multiple JSON objects separated by
687 non-JSON text (such as commas). 687 non-JSON text (such as commas).
688 688
689 $json->incr_skip 689 $json->incr_skip
690 This will reset the state of the incremental parser and will remove 690 This will reset the state of the incremental parser and will remove
691 the parsed text from the input buffer. This is useful after 691 the parsed text from the input buffer so far. This is useful after
692 "incr_parse" died, in which case the input buffer and incremental 692 "incr_parse" died, in which case the input buffer and incremental
693 parser state is left unchanged, to skip the text parsed so far and 693 parser state is left unchanged, to skip the text parsed so far and
694 to reset the parse state. 694 to reset the parse state.
695 695
696 The difference to "incr_reset" is that only text until the parse
697 error occured is removed.
698
696 $json->incr_reset 699 $json->incr_reset
697 This completely resets the incremental parser, that is, after this 700 This completely resets the incremental parser, that is, after this
698 call, it will be as if the parser had never parsed anything. 701 call, it will be as if the parser had never parsed anything.
699 702
700 This is useful if you want ot repeatedly parse JSON objects and want 703 This is useful if you want to repeatedly parse JSON objects and want
701 to ignore any trailing data, which means you have to reset the 704 to ignore any trailing data, which means you have to reset the
702 parser after each successful decode. 705 parser after each successful decode.
703 706
704 LIMITATIONS 707 LIMITATIONS
705 All options that affect decoding are supported, except "allow_nonref". 708 All options that affect decoding are supported, except "allow_nonref".
… …
1070 any character set and 8-bit-encoding, and still get the same data 1073 any character set and 8-bit-encoding, and still get the same data
1071 structure back. This is useful when your channel for JSON transfer 1074 structure back. This is useful when your channel for JSON transfer
1072 is not 8-bit clean or the encoding might be mangled in between (e.g. 1075 is not 8-bit clean or the encoding might be mangled in between (e.g.
1073 in mail), and works because ASCII is a proper subset of most 8-bit 1076 in mail), and works because ASCII is a proper subset of most 8-bit
1074 and multibyte encodings in use in the world. 1077 and multibyte encodings in use in the world.
1078
1079 JSON and ECMAscript
1080 JSON syntax is based on how literals are represented in javascript (the
1081 not-standardised predecessor of ECMAscript) which is presumably why it
1082 is called "JavaScript Object Notation".
1083
1084 However, JSON is not a subset (and also not a superset of course) of
1085 ECMAscript (the standard) or javascript (whatever browsers actually
1086 implement).
1087
1088 If you want to use javascript's "eval" function to "parse" JSON, you
1089 might run into parse errors for valid JSON texts, or the resulting data
1090 structure might not be queryable:
1091
1092 One of the problems is that U+2028 and U+2029 are valid characters
1093 inside JSON strings, but are not allowed in ECMAscript string literals,
1094 so the following Perl fragment will not output something that can be
1095 guaranteed to be parsable by javascript's "eval":
1096
1097 use JSON::XS;
1098
1099 print encode_json [chr 0x2028];
1100
1101 The right fix for this is to use a proper JSON parser in your javascript
1102 programs, and not rely on "eval" (see for example Douglas Crockford's
1103 json2.js parser).
1104
1105 If this is not an option, you can, as a stop-gap measure, simply encode
1106 to ASCII-only JSON:
1107
1108 use JSON::XS;
1109
1110 print JSON::XS->new->ascii->encode ([chr 0x2028]);
1111
1112 Note that this will enlarge the resulting JSON text quite a bit if you
1113 have many non-ASCII characters. You might be tempted to run some regexes
1114 to only escape U+2028 and U+2029, e.g.:
1115
1116 # DO NOT USE THIS!
1117 my $json = JSON::XS->new->utf8->encode ([chr 0x2028]);
1118 $json =~ s/\xe2\x80\xa8/\\u2028/g; # escape U+2028
1119 $json =~ s/\xe2\x80\xa9/\\u2029/g; # escape U+2029
1120 print $json;
1121
1122 Note that *this is a bad idea*: the above only works for U+2028 and
1123 U+2029 and thus only for fully ECMAscript-compliant parsers. Many
1124 existing javascript implementations, however, have issues with other
1125 characters as well - using "eval" naively simply *will* cause problems.
1126
1127 Another problem is that some javascript implementations reserve some
1128 property names for their own purposes (which probably makes them
1129 non-ECMAscript-compliant). For example, Iceweasel reserves the
1130 "__proto__" property name for it's own purposes.
1131
1132 If that is a problem, you could parse try to filter the resulting JSON
1133 output for these property strings, e.g.:
1134
1135 $json =~ s/"__proto__"\s*:/"__proto__renamed":/g;
1136
1137 This works because "__proto__" is not valid outside of strings, so every
1138 occurence of ""__proto__"\s*:" must be a string used as property name.
1139
1140 If you know of other incompatibilities, please let me know.
1075 1141
1076 JSON and YAML 1142 JSON and YAML
1077 You often hear that JSON is a subset of YAML. This is, however, a mass 1143 You often hear that JSON is a subset of YAML. This is, however, a mass
1078 hysteria(*) and very far from the truth (as of the time of this 1144 hysteria(*) and very far from the truth (as of the time of this
1079 writing), so let me state it clearly: *in general, there is no way to 1145 writing), so let me state it clearly: *in general, there is no way to

Diff Legend

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