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

Comparing JSON-XS/XS.pm (file contents):
Revision 1.106 by root, Tue May 27 05:31:39 2008 UTC vs.
Revision 1.121 by root, Mon Jul 13 22:13:17 2009 UTC

…		…
49	to write yet another JSON module? While it seems there are many JSON	49	to write yet another JSON module? While it seems there are many JSON
50	modules, none of them correctly handle all corner cases, and in most cases	50	modules, none of them correctly handle all corner cases, and in most cases
51	their maintainers are unresponsive, gone missing, or not listening to bug	51	their maintainers are unresponsive, gone missing, or not listening to bug
52	reports for other reasons.	52	reports for other reasons.
53		53
54	See COMPARISON, below, for a comparison to some other JSON modules.
55
56	See MAPPING, below, on how JSON::XS maps perl values to JSON values and	54	See MAPPING, below, on how JSON::XS maps perl values to JSON values and
57	vice versa.	55	vice versa.
58		56
59	=head2 FEATURES	57	=head2 FEATURES
60		58
…		…
101		99
102	=cut	100	=cut
103		101
104	package JSON::XS;	102	package JSON::XS;
105		103
106	use strict;	104	use common::sense;
107		105
108	our $VERSION = '2.2';	106	our $VERSION = '2.24';
109	our @ISA = qw(Exporter);	107	our @ISA = qw(Exporter);
110		108
111	our @EXPORT = qw(encode_json decode_json to_json from_json);	109	our @EXPORT = qw(encode_json decode_json to_json from_json);
112		110
113	sub to_json($) {	111	sub to_json($) {
…		…
706	In some cases, there is the need for incremental parsing of JSON	704	In some cases, there is the need for incremental parsing of JSON
707	texts. While this module always has to keep both JSON text and resulting	705	texts. While this module always has to keep both JSON text and resulting
708	Perl data structure in memory at one time, it does allow you to parse a	706	Perl data structure in memory at one time, it does allow you to parse a
709	JSON stream incrementally. It does so by accumulating text until it has	707	JSON stream incrementally. It does so by accumulating text until it has
710	a full JSON object, which it then can decode. This process is similar to	708	a full JSON object, which it then can decode. This process is similar to
711	using C<decode_prefix> to see if a full JSON object is available, but is	709	using C<decode_prefix> to see if a full JSON object is available, but
712	much more efficient (JSON::XS will only attempt to parse the JSON text	710	is much more efficient (and can be implemented with a minimum of method
		711	calls).
		712
		713	JSON::XS will only attempt to parse the JSON text once it is sure it
713	once it is sure it has enough text to get a decisive result, using a very	714	has enough text to get a decisive result, using a very simple but
714	simple but truly incremental parser).	715	truly incremental parser. This means that it sometimes won't stop as
		716	early as the full parser, for example, it doesn't detect parenthese
		717	mismatches. The only thing it guarantees is that it starts decoding as
		718	soon as a syntactically valid JSON text has been seen. This means you need
		719	to set resource limits (e.g. C<max_size>) to ensure the parser will stop
		720	parsing in the presence if syntax errors.
715		721
716	The following two methods deal with this.	722	The following methods implement this incremental parser.
717		723
718	=over 4	724	=over 4
719		725
720	=item [void, scalar or list context] = $json->incr_parse ([$string])	726	=item [void, scalar or list context] = $json->incr_parse ([$string])
721		727
…		…
759	JSON object or b) parsing multiple JSON objects separated by non-JSON text	765	JSON object or b) parsing multiple JSON objects separated by non-JSON text
760	(such as commas).	766	(such as commas).
761		767
762	=item $json->incr_skip	768	=item $json->incr_skip
763		769
764	This will reset the state of the incremental parser and will remove the	770	This will reset the state of the incremental parser and will remove
765	parsed text from the input buffer. This is useful after C<incr_parse>	771	the parsed text from the input buffer so far. This is useful after
766	died, in which case the input buffer and incremental parser state is left	772	C<incr_parse> died, in which case the input buffer and incremental parser
767	unchanged, to skip the text parsed so far and to reset the parse state.	773	state is left unchanged, to skip the text parsed so far and to reset the
		774	parse state.
		775
		776	The difference to C<incr_reset> is that only text until the parse error
		777	occured is removed.
768		778
769	=item $json->incr_reset	779	=item $json->incr_reset
770		780
771	This completely resets the incremental parser, that is, after this call,	781	This completely resets the incremental parser, that is, after this call,
772	it will be as if the parser had never parsed anything.	782	it will be as if the parser had never parsed anything.
773		783
774	This is useful if you want ot repeatedly parse JSON objects and want to	784	This is useful if you want to repeatedly parse JSON objects and want to
775	ignore any trailing data, which means you have to reset the parser after	785	ignore any trailing data, which means you have to reset the parser after
776	each successful decode.	786	each successful decode.
777		787
778	=back	788	=back
779		789
…		…
1172	when your channel for JSON transfer is not 8-bit clean or the encoding	1182	when your channel for JSON transfer is not 8-bit clean or the encoding
1173	might be mangled in between (e.g. in mail), and works because ASCII is a	1183	might be mangled in between (e.g. in mail), and works because ASCII is a
1174	proper subset of most 8-bit and multibyte encodings in use in the world.	1184	proper subset of most 8-bit and multibyte encodings in use in the world.
1175		1185
1176	=back	1186	=back
		1187
		1188
		1189	=head2 JSON and ECMAscript
		1190
		1191	JSON syntax is based on how literals are represented in javascript (the
		1192	not-standardised predecessor of ECMAscript) which is presumably why it is
		1193	called "JavaScript Object Notation".
		1194
		1195	However, JSON is not a subset (and also not a superset of course) of
		1196	ECMAscript (the standard) or javascript (whatever browsers actually
		1197	implement).
		1198
		1199	If you want to use javascript's C<eval> function to "parse" JSON, you
		1200	might run into parse errors for valid JSON texts, or the resulting data
		1201	structure might not be queryable:
		1202
		1203	One of the problems is that U+2028 and U+2029 are valid characters inside
		1204	JSON strings, but are not allowed in ECMAscript string literals, so the
		1205	following Perl fragment will not output something that can be guaranteed
		1206	to be parsable by javascript's C<eval>:
		1207
		1208	use JSON::XS;
		1209
		1210	print encode_json [chr 0x2028];
		1211
		1212	The right fix for this is to use a proper JSON parser in your javascript
		1213	programs, and not rely on C<eval> (see for example Douglas Crockford's
		1214	F<json2.js> parser).
		1215
		1216	If this is not an option, you can, as a stop-gap measure, simply encode to
		1217	ASCII-only JSON:
		1218
		1219	use JSON::XS;
		1220
		1221	print JSON::XS->new->ascii->encode ([chr 0x2028]);
		1222
		1223	Note that this will enlarge the resulting JSON text quite a bit if you
		1224	have many non-ASCII characters. You might be tempted to run some regexes
		1225	to 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
		1233	Note that I<this is a bad idea>: the above only works for U+2028 and
		1234	U+2029 and thus only for fully ECMAscript-compliant parsers. Many existing
		1235	javascript implementations, however, have issues with other characters as
		1236	well - using C<eval> naively simply I<will> cause problems.
		1237
		1238	Another problem is that some javascript implementations reserve
		1239	some property names for their own purposes (which probably makes
		1240	them non-ECMAscript-compliant). For example, Iceweasel reserves the
		1241	C<__proto__> property name for it's own purposes.
		1242
		1243	If that is a problem, you could parse try to filter the resulting JSON
		1244	output for these property strings, e.g.:
		1245
		1246	$json =~ s/"__proto__"\s*:/"__proto__renamed":/g;
		1247
		1248	This works because C<__proto__> is not valid outside of strings, so every
		1249	occurence of C<"__proto__"\s*:> must be a string used as property name.
		1250
		1251	If you know of other incompatibilities, please let me know.
1177		1252
1178		1253
1179	=head2 JSON and YAML	1254	=head2 JSON and YAML
1180		1255
1181	You often hear that JSON is a subset of YAML. This is, however, a mass	1256	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.106 by root, Tue May 27 05:31:39 2008 UTC vs. Revision 1.121 by root, Mon Jul 13 22:13:17 2009 UTC

Diff Legend

Comparing JSON-XS/XS.pm (file contents):
Revision 1.106 by root, Tue May 27 05:31:39 2008 UTC vs.
Revision 1.121 by root, Mon Jul 13 22:13:17 2009 UTC