[ViewVC] Diff of: cvs/JSON-XS/XS.pm

Comparing JSON-XS/XS.pm (file contents):
Revision 1.113 by root, Thu Nov 20 03:59:53 2008 UTC vs.
Revision 1.123 by root, Sat Aug 8 10:06:02 2009 UTC

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

Diff Legend

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

Comparing JSON-XS/XS.pm (file contents): Revision 1.113 by root, Thu Nov 20 03:59:53 2008 UTC vs. Revision 1.123 by root, Sat Aug 8 10:06:02 2009 UTC

Diff Legend

Comparing JSON-XS/XS.pm (file contents):
Revision 1.113 by root, Thu Nov 20 03:59:53 2008 UTC vs.
Revision 1.123 by root, Sat Aug 8 10:06:02 2009 UTC