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.111 by root, Mon Jul 21 02:45:17 2008 UTC vs.
Revision 1.119 by root, Sun Feb 22 10:13:16 2009 UTC

… …
102package JSON::XS; 102package JSON::XS;
103 103
104no warnings; 104no warnings;
105use strict; 105use strict;
106 106
107our $VERSION = '2.2222'; 107our $VERSION = '2.232';
108our @ISA = qw(Exporter); 108our @ISA = qw(Exporter);
109 109
110our @EXPORT = qw(encode_json decode_json to_json from_json); 110our @EXPORT = qw(encode_json decode_json to_json from_json);
111 111
112sub to_json($) { 112sub to_json($) {
… …
766JSON object or b) parsing multiple JSON objects separated by non-JSON text 766JSON object or b) parsing multiple JSON objects separated by non-JSON text
767(such as commas). 767(such as commas).
768 768
769=item $json->incr_skip 769=item $json->incr_skip
770 770
771This will reset the state of the incremental parser and will remove the 771This will reset the state of the incremental parser and will remove
772parsed text from the input buffer. This is useful after C<incr_parse> 772the parsed text from the input buffer so far. This is useful after
773died, in which case the input buffer and incremental parser state is left 773C<incr_parse> died, in which case the input buffer and incremental parser
774unchanged, to skip the text parsed so far and to reset the parse state. 774state is left unchanged, to skip the text parsed so far and to reset the
775parse state.
776
777The difference to C<incr_reset> is that only text until the parse error
778occured is removed.
775 779
776=item $json->incr_reset 780=item $json->incr_reset
777 781
778This completely resets the incremental parser, that is, after this call, 782This completely resets the incremental parser, that is, after this call,
779it will be as if the parser had never parsed anything. 783it will be as if the parser had never parsed anything.
780 784
781This is useful if you want ot repeatedly parse JSON objects and want to 785This is useful if you want to repeatedly parse JSON objects and want to
782ignore any trailing data, which means you have to reset the parser after 786ignore any trailing data, which means you have to reset the parser after
783each successful decode. 787each successful decode.
784 788
785=back 789=back
786 790
… …
1179when your channel for JSON transfer is not 8-bit clean or the encoding 1183when your channel for JSON transfer is not 8-bit clean or the encoding
1180might be mangled in between (e.g. in mail), and works because ASCII is a 1184might be mangled in between (e.g. in mail), and works because ASCII is a
1181proper subset of most 8-bit and multibyte encodings in use in the world. 1185proper subset of most 8-bit and multibyte encodings in use in the world.
1182 1186
1183=back 1187=back
1188
1189
1190=head2 JSON and ECMAscript
1191
1192JSON syntax is based on how literals are represented in javascript (the
1193not-standardised predecessor of ECMAscript) which is presumably why it is
1194called "JavaScript Object Notation".
1195
1196However, JSON is not a subset (and also not a superset of course) of
1197ECMAscript (the standard) or javascript (whatever browsers actually
1198implement).
1199
1200If you want to use javascript's C<eval> function to "parse" JSON, you
1201might run into parse errors for valid JSON texts, or the resulting data
1202structure might not be queryable:
1203
1204One of the problems is that U+2028 and U+2029 are valid characters inside
1205JSON strings, but are not allowed in ECMAscript string literals, so the
1206following Perl fragment will not output something that can be guaranteed
1207to be parsable by javascript's C<eval>:
1208
1209 use JSON::XS;
1210
1211 print encode_json [chr 0x2028];
1212
1213The right fix for this is to use a proper JSON parser in your javascript
1214programs, and not rely on C<eval> (see for example Douglas Crockford's
1215F<json2.js> parser).
1216
1217If this is not an option, you can, as a stop-gap measure, simply encode to
1218ASCII-only JSON:
1219
1220 use JSON::XS;
1221
1222 print JSON::XS->new->ascii->encode ([chr 0x2028]);
1223
1224Note that this will enlarge the resulting JSON text quite a bit if you
1225have many non-ASCII characters. You might be tempted to run some regexes
1226to only escape U+2028 and U+2029, e.g.:
1227
1228 # DO NOT USE THIS!
1229 my $json = JSON::XS->new->utf8->encode ([chr 0x2028]);
1230 $json =~ s/\xe2\x80\xa8/\\u2028/g; # escape U+2028
1231 $json =~ s/\xe2\x80\xa9/\\u2029/g; # escape U+2029
1232 print $json;
1233
1234Note that I<this is a bad idea>: the above only works for U+2028 and
1235U+2029 and thus only for fully ECMAscript-compliant parsers. Many existing
1236javascript implementations, however, have issues with other characters as
1237well - using C<eval> naively simply I<will> cause problems.
1238
1239Another problem is that some javascript implementations reserve
1240some property names for their own purposes (which probably makes
1241them non-ECMAscript-compliant). For example, Iceweasel reserves the
1242C<__proto__> property name for it's own purposes.
1243
1244If that is a problem, you could parse try to filter the resulting JSON
1245output for these property strings, e.g.:
1246
1247 $json =~ s/"__proto__"\s*:/"__proto__renamed":/g;
1248
1249This works because C<__proto__> is not valid outside of strings, so every
1250occurence of C<"__proto__"\s*:> must be a string used as property name.
1251
1252If you know of other incompatibilities, please let me know.
1184 1253
1185 1254
1186=head2 JSON and YAML 1255=head2 JSON and YAML
1187 1256
1188You often hear that JSON is a subset of YAML. This is, however, a mass 1257You often hear that JSON is a subset of YAML. This is, however, a mass

Diff Legend

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