[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.98 by root, Wed Mar 26 02:36:18 2008 UTC

…		…
683	=back	683	=back
684		684
685		685
686	=head1 INCREMENTAL PARSING	686	=head1 INCREMENTAL PARSING
687		687
688	[This section is still EXPERIMENTAL]	688	[This section and the API it details is still EXPERIMENTAL]
689		689
690	In some cases, there is the need for incremental parsing of JSON	690	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	691	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	692	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	693	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	714	return without doing anything further. This can be used to add more text
715	in as many chunks as you want.	715	in as many chunks as you want.
716		716
717	If the method is called in scalar context, then it will try to extract	717	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	718	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	719	object, otherwise it will return C<undef>. If there is a parse error,
		720	this method will croak just as C<decode> would do (one can then use
		721	C<incr_skip> to skip the errornous part). This is the most common way of
720	using the method.	722	using the method.
721		723
722	And finally, in list context, it will try to extract as many objects	724	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	725	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	726	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.	727	objects or arrays, instead they must be concatenated back-to-back. If
		728	an error occurs, an exception will be raised as in the scalar context
		729	case. Note that in this case, any previously-parsed JSON texts will be
		730	lost.
726		731
727	=item $lvalue_string = $json->incr_text	732	=item $lvalue_string = $json->incr_text
728		733
729	This method returns the currently stored JSON fragment as an lvalue, that	734	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	735	is, you can manipulate it. This I<only> works when a preceding call to
…		…
735	method before having parsed anything.	740	method before having parsed anything.
736		741
737	This function is useful in two cases: a) finding the trailing text after a	742	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	743	JSON object or b) parsing multiple JSON objects separated by non-JSON text
739	(such as commas).	744	(such as commas).
		745
		746	=item $json->incr_skip
		747
		748	This will reset the state of the incremental parser and will remove the
		749	parsed text from the input buffer. This is useful after C<incr_parse>
		750	died, in which case the input buffer and incremental parser state is left
		751	unchanged, to skip the text parsed so far and to reset the parse state.
740		752
741	=back	753	=back
742		754
743	=head2 LIMITATIONS	755	=head2 LIMITATIONS
744		756
…		…
1133	as UTF-8, ISO-8859-1, ASCII, KOI8-R or most about any character set and	1145	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	1146	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	1147	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	1148	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.	1149	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		1150
1237	=back	1151	=back
1238		1152
1239		1153
1240	=head2 JSON and YAML	1154	=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.98 by root, Wed Mar 26 02:36:18 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.98 by root, Wed Mar 26 02:36:18 2008 UTC