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.113 by root, Thu Nov 20 03:59:53 2008 UTC vs.
Revision 1.121 by root, Mon Jul 13 22:13:17 2009 UTC

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

Diff Legend

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