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

Comparing JSON-XS/XS.pm (file contents):
Revision 1.94 by root, Tue Mar 25 07:46:15 2008 UTC vs.
Revision 1.99 by root, Thu Mar 27 06:37:35 2008 UTC

…		…
103		103
104	package JSON::XS;	104	package JSON::XS;
105		105
106	use strict;	106	use strict;
107		107
108	our $VERSION = '2.1';	108	our $VERSION = '2.2';
109	our @ISA = qw(Exporter);	109	our @ISA = qw(Exporter);
110		110
111	our @EXPORT = qw(encode_json decode_json to_json from_json);	111	our @EXPORT = qw(encode_json decode_json to_json from_json);
112		112
113	sub to_json($) {	113	sub to_json($) {
…		…
462	Example, encode a Perl scalar as JSON value with enabled C<allow_nonref>,	462	Example, encode a Perl scalar as JSON value with enabled C<allow_nonref>,
463	resulting in an invalid JSON text:	463	resulting in an invalid JSON text:
464		464
465	JSON::XS->new->allow_nonref->encode ("Hello, World!")	465	JSON::XS->new->allow_nonref->encode ("Hello, World!")
466	=> "Hello, World!"	466	=> "Hello, World!"
		467
		468	=item $json = $json->allow_unknown ([$enable])
		469
		470	=item $enabled = $json->get_allow_unknown
		471
		472	If C<$enable> is true (or missing), then C<encode> will I<not> throw an
		473	exception when it encounters values it cannot represent in JSON (for
		474	example, filehandles) but instead will encode a JSON C<null> value. Note
		475	that blessed objects are not included here and are handled separately by
		476	c<allow_nonref>.
		477
		478	If C<$enable> is false (the default), then C<encode> will throw an
		479	exception when it encounters anything it cannot encode as JSON.
		480
		481	This option does not affect C<decode> in any way, and it is recommended to
		482	leave it off unless you know your communications partner.
467		483
468	=item $json = $json->allow_blessed ([$enable])	484	=item $json = $json->allow_blessed ([$enable])
469		485
470	=item $enabled = $json->get_allow_blessed	486	=item $enabled = $json->get_allow_blessed
471		487
…		…
683	=back	699	=back
684		700
685		701
686	=head1 INCREMENTAL PARSING	702	=head1 INCREMENTAL PARSING
687		703
688	[This section is still EXPERIMENTAL]	704	[This section and the API it details is still EXPERIMENTAL]
689		705
690	In some cases, there is the need for incremental parsing of JSON	706	In some cases, there is the need for incremental parsing of JSON
691	texts. While this module always has to keep both JSON text and resulting	707	texts. While this module always has to keep both JSON text and resulting
692	Perl data structure in memory at one time, it does allow you to parse a	708	Perl data structure in memory at one time, it does allow you to parse a
693	JSON stream incrementally. It does so by accumulating text until it has	709	JSON stream incrementally. It does so by accumulating text until it has
…		…
714	return without doing anything further. This can be used to add more text	730	return without doing anything further. This can be used to add more text
715	in as many chunks as you want.	731	in as many chunks as you want.
716		732
717	If the method is called in scalar context, then it will try to extract	733	If the method is called in scalar context, then it will try to extract
718	exactly I<one> JSON object. If that is successful, it will return this	734	exactly I<one> JSON object. If that is successful, it will return this
719	object, otherwise it will return C<undef>. This is the most common way of	735	object, otherwise it will return C<undef>. If there is a parse error,
		736	this method will croak just as C<decode> would do (one can then use
		737	C<incr_skip> to skip the errornous part). This is the most common way of
720	using the method.	738	using the method.
721		739
722	And finally, in list context, it will try to extract as many objects	740	And finally, in list context, it will try to extract as many objects
723	from the stream as it can find and return them, or the empty list	741	from the stream as it can find and return them, or the empty list
724	otherwise. For this to work, there must be no separators between the JSON	742	otherwise. For this to work, there must be no separators between the JSON
725	objects or arrays, instead they must be concatenated back-to-back.	743	objects or arrays, instead they must be concatenated back-to-back. If
		744	an error occurs, an exception will be raised as in the scalar context
		745	case. Note that in this case, any previously-parsed JSON texts will be
		746	lost.
726		747
727	=item $lvalue_string = $json->incr_text	748	=item $lvalue_string = $json->incr_text
728		749
729	This method returns the currently stored JSON fragment as an lvalue, that	750	This method returns the currently stored JSON fragment as an lvalue, that
730	is, you can manipulate it. This I<only> works when a preceding call to	751	is, you can manipulate it. This I<only> works when a preceding call to
…		…
735	method before having parsed anything.	756	method before having parsed anything.
736		757
737	This function is useful in two cases: a) finding the trailing text after a	758	This function is useful in two cases: a) finding the trailing text after a
738	JSON object or b) parsing multiple JSON objects separated by non-JSON text	759	JSON object or b) parsing multiple JSON objects separated by non-JSON text
739	(such as commas).	760	(such as commas).
		761
		762	=item $json->incr_skip
		763
		764	This will reset the state of the incremental parser and will remove the
		765	parsed text from the input buffer. This is useful after C<incr_parse>
		766	died, in which case the input buffer and incremental parser state is left
		767	unchanged, to skip the text parsed so far and to reset the parse state.
740		768
741	=back	769	=back
742		770
743	=head2 LIMITATIONS	771	=head2 LIMITATIONS
744		772
…		…
1133	as UTF-8, ISO-8859-1, ASCII, KOI8-R or most about any character set and	1161	as UTF-8, ISO-8859-1, ASCII, KOI8-R or most about any character set and
1134	8-bit-encoding, and still get the same data structure back. This is useful	1162	8-bit-encoding, and still get the same data structure back. This is useful
1135	when your channel for JSON transfer is not 8-bit clean or the encoding	1163	when your channel for JSON transfer is not 8-bit clean or the encoding
1136	might be mangled in between (e.g. in mail), and works because ASCII is a	1164	might be mangled in between (e.g. in mail), and works because ASCII is a
1137	proper subset of most 8-bit and multibyte encodings in use in the world.	1165	proper subset of most 8-bit and multibyte encodings in use in the world.
1138
1139	=back
1140
1141
1142	=head1 COMPARISON
1143
1144	As already mentioned, this module was created because none of the existing
1145	JSON modules could be made to work correctly. First I will describe the
1146	problems (or pleasures) I encountered with various existing JSON modules,
1147	followed by some benchmark values. JSON::XS was designed not to suffer
1148	from any of these problems or limitations.
1149
1150	=over 4
1151
1152	=item JSON 2.xx
1153
1154	A marvellous piece of engineering, this module either uses JSON::XS
1155	directly when available (so will be 100% compatible with it, including
1156	speed), or it uses JSON::PP, which is basically JSON::XS translated to
1157	Pure Perl, which should be 100% compatible with JSON::XS, just a bit
1158	slower.
1159
1160	You cannot really lose by using this module, especially as it tries very
1161	hard to work even with ancient Perl versions, while JSON::XS does not.
1162
1163	=item JSON 1.07
1164
1165	Slow (but very portable, as it is written in pure Perl).
1166
1167	Undocumented/buggy Unicode handling (how JSON handles Unicode values is
1168	undocumented. One can get far by feeding it Unicode strings and doing
1169	en-/decoding oneself, but Unicode escapes are not working properly).
1170
1171	No round-tripping (strings get clobbered if they look like numbers, e.g.
1172	the string C<2.0> will encode to C<2.0> instead of C<"2.0">, and that will
1173	decode into the number 2.
1174
1175	=item JSON::PC 0.01
1176
1177	Very fast.
1178
1179	Undocumented/buggy Unicode handling.
1180
1181	No round-tripping.
1182
1183	Has problems handling many Perl values (e.g. regex results and other magic
1184	values will make it croak).
1185
1186	Does not even generate valid JSON (C<{1,2}> gets converted to C<{1:2}>
1187	which is not a valid JSON text.
1188
1189	Unmaintained (maintainer unresponsive for many months, bugs are not
1190	getting fixed).
1191
1192	=item JSON::Syck 0.21
1193
1194	Very buggy (often crashes).
1195
1196	Very inflexible (no human-readable format supported, format pretty much
1197	undocumented. I need at least a format for easy reading by humans and a
1198	single-line compact format for use in a protocol, and preferably a way to
1199	generate ASCII-only JSON texts).
1200
1201	Completely broken (and confusingly documented) Unicode handling (Unicode
1202	escapes are not working properly, you need to set ImplicitUnicode to
1203	I<different> values on en- and decoding to get symmetric behaviour).
1204
1205	No round-tripping (simple cases work, but this depends on whether the scalar
1206	value was used in a numeric context or not).
1207
1208	Dumping hashes may skip hash values depending on iterator state.
1209
1210	Unmaintained (maintainer unresponsive for many months, bugs are not
1211	getting fixed).
1212
1213	Does not check input for validity (i.e. will accept non-JSON input and
1214	return "something" instead of raising an exception. This is a security
1215	issue: imagine two banks transferring money between each other using
1216	JSON. One bank might parse a given non-JSON request and deduct money,
1217	while the other might reject the transaction with a syntax error. While a
1218	good protocol will at least recover, that is extra unnecessary work and
1219	the transaction will still not succeed).
1220
1221	=item JSON::DWIW 0.04
1222
1223	Very fast. Very natural. Very nice.
1224
1225	Undocumented Unicode handling (but the best of the pack. Unicode escapes
1226	still don't get parsed properly).
1227
1228	Very inflexible.
1229
1230	No round-tripping.
1231
1232	Does not generate valid JSON texts (key strings are often unquoted, empty keys
1233	result in nothing being output)
1234
1235	Does not check input for validity.
1236		1166
1237	=back	1167	=back
1238		1168
1239		1169
1240	=head2 JSON and YAML	1170	=head2 JSON and YAML

Diff Legend

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

Comparing JSON-XS/XS.pm (file contents): Revision 1.94 by root, Tue Mar 25 07:46:15 2008 UTC vs. Revision 1.99 by root, Thu Mar 27 06:37:35 2008 UTC

Diff Legend

Comparing JSON-XS/XS.pm (file contents):
Revision 1.94 by root, Tue Mar 25 07:46:15 2008 UTC vs.
Revision 1.99 by root, Thu Mar 27 06:37:35 2008 UTC