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

Comparing JSON-XS/XS.pm (file contents):
Revision 1.2 by root, Thu Mar 22 17:28:50 2007 UTC vs.
Revision 1.7 by root, Fri Mar 23 15:10:55 2007 UTC

…		…
59	=cut	59	=cut
60		60
61	package JSON::XS;	61	package JSON::XS;
62		62
63	BEGIN {	63	BEGIN {
64	$VERSION = '0.1';	64	$VERSION = '0.2';
65	@ISA = qw(Exporter);	65	@ISA = qw(Exporter);
66		66
67	@EXPORT = qw(to_json from_json);	67	@EXPORT = qw(to_json from_json);
68	require Exporter;	68	require Exporter;
69		69
…		…
111	strings. All boolean flags described below are by default I<disabled>.	111	strings. All boolean flags described below are by default I<disabled>.
112		112
113	The mutators for flags all return the JSON object again and thus calls can	113	The mutators for flags all return the JSON object again and thus calls can
114	be chained:	114	be chained:
115		115
116	my $json = JSON::XS->new->utf8(1)->pretty(1)->encode ({a => [1,2]})	116	my $json = JSON::XS->new->utf8(1)->space_after(1)->encode ({a => [1,2]})
117	=> {"a" : [1, 2]}	117	=> {"a": [1, 2]}
118		118
119	=item $json = $json->ascii ($enable)	119	=item $json = $json->ascii ([$enable])
120		120
121	If C<$enable> is true, then the C<encode> method will not generate	121	If C<$enable> is true (or missing), then the C<encode> method will
122	characters outside the code range C<0..127>. Any unicode characters	122	not generate characters outside the code range C<0..127>. Any unicode
123	outside that range will be escaped using either a single \uXXXX (BMP	123	characters outside that range will be escaped using either a single
124	characters) or a double \uHHHH\uLLLLL escape sequence, as per RFC4627.	124	\uXXXX (BMP characters) or a double \uHHHH\uLLLLL escape sequence, as per
		125	RFC4627.
125		126
126	If C<$enable> is false, then the C<encode> method will not escape Unicode	127	If C<$enable> is false, then the C<encode> method will not escape Unicode
127	characters unless necessary.	128	characters unless necessary.
128		129
		130	JSON::XS->new->ascii (1)->encode (chr 0x10401)
		131	=> \ud801\udc01
		132
129	=item $json = $json->utf8 ($enable)	133	=item $json = $json->utf8 ([$enable])
130		134
131	If C<$enable> is true, then the C<encode> method will encode the JSON	135	If C<$enable> is true (or missing), then the C<encode> method will encode
132	string into UTF-8, as required by many protocols, while the C<decode>	136	the JSON string into UTF-8, as required by many protocols, while the
133	method expects to be handled an UTF-8-encoded string. Please note that	137	C<decode> method expects to be handled an UTF-8-encoded string. Please
134	UTF-8-encoded strings do not contain any characters outside the range	138	note that UTF-8-encoded strings do not contain any characters outside the
135	C<0..255>, they are thus useful for bytewise/binary I/O.	139	range C<0..255>, they are thus useful for bytewise/binary I/O.
136		140
137	If C<$enable> is false, then the C<encode> method will return the JSON	141	If C<$enable> is false, then the C<encode> method will return the JSON
138	string as a (non-encoded) unicode string, while C<decode> expects thus a	142	string as a (non-encoded) unicode string, while C<decode> expects thus a
139	unicode string. Any decoding or encoding (e.g. to UTF-8 or UTF-16) needs	143	unicode string. Any decoding or encoding (e.g. to UTF-8 or UTF-16) needs
140	to be done yourself, e.g. using the Encode module.	144	to be done yourself, e.g. using the Encode module.
141		145
142	=item $json = $json->pretty ($enabla)	146	=item $json = $json->pretty ([$enable])
143		147
144	This enables (or disables) all of the C<indent>, C<space_before> and	148	This enables (or disables) all of the C<indent>, C<space_before> and
145	C<space_after> (and in the future possibly more) settings in one call to	149	C<space_after> (and in the future possibly more) flags in one call to
146	generate the most readable (or most compact) form possible.	150	generate the most readable (or most compact) form possible.
147		151
		152	my $json = JSON::XS->new->pretty(1)->encode ({a => [1,2]})
		153	=>
		154	{
		155	"a" : [
		156	1,
		157	2
		158	]
		159	}
		160
148	=item $json = $json->indent ($enable)	161	=item $json = $json->indent ([$enable])
149		162
150	If C<$enable> is true, then the C<encode> method will use a multiline	163	If C<$enable> is true (or missing), then the C<encode> method will use a multiline
151	format as output, putting every array member or object/hash key-value pair	164	format as output, putting every array member or object/hash key-value pair
152	into its own line, identing them properly.	165	into its own line, identing them properly.
153		166
154	If C<$enable> is false, no newlines or indenting will be produced, and the	167	If C<$enable> is false, no newlines or indenting will be produced, and the
155	resulting JSON strings is guarenteed not to contain any C<newlines>.	168	resulting JSON strings is guarenteed not to contain any C<newlines>.
156		169
157	This setting has no effect when decoding JSON strings.	170	This setting has no effect when decoding JSON strings.
158		171
159	=item $json = $json->space_before ($enable)	172	=item $json = $json->space_before ([$enable])
160		173
161	If C<$enable> is true, then the C<encode> method will add an extra	174	If C<$enable> is true (or missing), then the C<encode> method will add an extra
162	optional space before the C<:> separating keys from values in JSON objects.	175	optional space before the C<:> separating keys from values in JSON objects.
163		176
164	If C<$enable> is false, then the C<encode> method will not add any extra	177	If C<$enable> is false, then the C<encode> method will not add any extra
165	space at those places.	178	space at those places.
166		179
167	This setting has no effect when decoding JSON strings. You will also most	180	This setting has no effect when decoding JSON strings. You will also most
168	likely combine this setting with C<space_after>.	181	likely combine this setting with C<space_after>.
169		182
170	=item $json = $json->space_after ($enable)	183	=item $json = $json->space_after ([$enable])
171		184
172	If C<$enable> is true, then the C<encode> method will add an extra	185	If C<$enable> is true (or missing), then the C<encode> method will add an extra
173	optional space after the C<:> separating keys from values in JSON objects	186	optional space after the C<:> separating keys from values in JSON objects
174	and extra whitespace after the C<,> separating key-value pairs and array	187	and extra whitespace after the C<,> separating key-value pairs and array
175	members.	188	members.
176		189
177	If C<$enable> is false, then the C<encode> method will not add any extra	190	If C<$enable> is false, then the C<encode> method will not add any extra
178	space at those places.	191	space at those places.
179		192
180	This setting has no effect when decoding JSON strings.	193	This setting has no effect when decoding JSON strings.
181		194
182	=item $json = $json->canonical ($enable)	195	=item $json = $json->canonical ([$enable])
183		196
184	If C<$enable> is true, then the C<encode> method will output JSON objects	197	If C<$enable> is true (or missing), then the C<encode> method will output JSON objects
185	by sorting their keys. This is adding a comparatively high overhead.	198	by sorting their keys. This is adding a comparatively high overhead.
186		199
187	If C<$enable> is false, then the C<encode> method will output key-value	200	If C<$enable> is false, then the C<encode> method will output key-value
188	pairs in the order Perl stores them (which will likely change between runs	201	pairs in the order Perl stores them (which will likely change between runs
189	of the same script).	202	of the same script).
…		…
192	the same JSON string (given the same overall settings). If it is disabled,	205	the same JSON string (given the same overall settings). If it is disabled,
193	the same hash migh be encoded differently even if contains the same data,	206	the same hash migh be encoded differently even if contains the same data,
194	as key-value pairs have no inherent ordering in Perl.	207	as key-value pairs have no inherent ordering in Perl.
195		208
196	This setting has no effect when decoding JSON strings.	209	This setting has no effect when decoding JSON strings.
		210
		211	=item $json = $json->allow_nonref ([$enable])
		212
		213	If C<$enable> is true (or missing), then the C<encode> method can convert a
		214	non-reference into its corresponding string, number or null JSON value,
		215	which is an extension to RFC4627. Likewise, C<decode> will accept those JSON
		216	values instead of croaking.
		217
		218	If C<$enable> is false, then the C<encode> method will croak if it isn't
		219	passed an arrayref or hashref, as JSON strings must either be an object
		220	or array. Likewise, C<decode> will croak if given something that is not a
		221	JSON object or array.
		222
		223	=item $json = $json->shrink ([$enable])
		224
		225	Perl usually over-allocates memory a bit when allocating space for
		226	strings. This flag optionally resizes strings generated by either
		227	C<encode> or C<decode> to their minimum size possible. This can save
		228	memory when your JSON strings are either very very long or you have many
		229	short strings.
		230
		231	If C<$enable> is true (or missing), the string returned by C<encode> will be shrunk-to-fit,
		232	while all strings generated by C<decode> will also be shrunk-to-fit.
		233
		234	If C<$enable> is false, then the normal perl allocation algorithms are used.
		235	If you work with your data, then this is likely to be faster.
		236
		237	In the future, this setting might control other things, such as converting
		238	strings that look like integers or floats into integers or floats
		239	internally (there is no difference on the Perl level), saving space.
197		240
198	=item $json_string = $json->encode ($perl_scalar)	241	=item $json_string = $json->encode ($perl_scalar)
199		242
200	Converts the given Perl data structure (a simple scalar or a reference	243	Converts the given Perl data structure (a simple scalar or a reference
201	to a hash or array) to its JSON representation. Simple scalars will be	244	to a hash or array) to its JSON representation. Simple scalars will be
…		…
213	Perl arrayrefs and JSON objects become Perl hashrefs. C<true> becomes	256	Perl arrayrefs and JSON objects become Perl hashrefs. C<true> becomes
214	C<1>, C<false> becomes C<0> and C<null> becomes C<undef>.	257	C<1>, C<false> becomes C<0> and C<null> becomes C<undef>.
215		258
216	=back	259	=back
217		260
		261	=head1 COMPARISON
		262
		263	As already mentioned, this module was created because none of the existing
		264	JSON modules could be made to work correctly. First I will describe the
		265	problems (or pleasures) I encountered with various existing JSON modules,
		266	followed by some benchmark values. JSON::XS was designed not to suffer
		267	from any of these problems or limitations.
		268
		269	=over 4
		270
		271	=item JSON 1.07
		272
		273	Slow (but very portable, as it is written in pure Perl).
		274
		275	Undocumented/buggy Unicode handling (how JSON handles unicode values is
		276	undocumented. One can get far by feeding it unicode strings and doing
		277	en-/decoding oneself, but unicode escapes are not working properly).
		278
		279	No roundtripping (strings get clobbered if they look like numbers, e.g.
		280	the string C<2.0> will encode to C<2.0> instead of C<"2.0">, and that will
		281	decode into the number 2.
		282
		283	=item JSON::PC 0.01
		284
		285	Very fast.
		286
		287	Undocumented/buggy Unicode handling.
		288
		289	No roundtripping.
		290
		291	Has problems handling many Perl values (e.g. regex results and other magic
		292	values will make it croak).
		293
		294	Does not even generate valid JSON (C<{1,2}> gets converted to C<{1:2}>
		295	which is not a valid JSON string.
		296
		297	Unmaintained (maintainer unresponsive for many months, bugs are not
		298	getting fixed).
		299
		300	=item JSON::Syck 0.21
		301
		302	Very buggy (often crashes).
		303
		304	Very inflexible (no human-readable format supported, format pretty much
		305	undocumented. I need at least a format for easy reading by humans and a
		306	single-line compact format for use in a protocol, and preferably a way to
		307	generate ASCII-only JSON strings).
		308
		309	Completely broken (and confusingly documented) Unicode handling (unicode
		310	escapes are not working properly, you need to set ImplicitUnicode to
		311	I<different> values on en- and decoding to get symmetric behaviour).
		312
		313	No roundtripping (simple cases work, but this depends on wether the scalar
		314	value was used in a numeric context or not).
		315
		316	Dumping hashes may skip hash values depending on iterator state.
		317
		318	Unmaintained (maintainer unresponsive for many months, bugs are not
		319	getting fixed).
		320
		321	Does not check input for validity (i.e. will accept non-JSON input and
		322	return "something" instead of raising an exception. This is a security
		323	issue: imagine two banks transfering money between each other using
		324	JSON. One bank might parse a given non-JSON request and deduct money,
		325	while the other might reject the transaction with a syntax error. While a
		326	good protocol will at least recover, that is extra unnecessary work and
		327	the transaction will still not succeed).
		328
		329	=item JSON::DWIW 0.04
		330
		331	Very fast. Very natural. Very nice.
		332
		333	Undocumented unicode handling (but the best of the pack. Unicode escapes
		334	still don't get parsed properly).
		335
		336	Very inflexible.
		337
		338	No roundtripping.
		339
		340	Does not generate valid JSON (key strings are often unquoted, empty keys
		341	result in nothing being output)
		342
		343	Does not check input for validity.
		344
		345	=back
		346
		347	=head2 SPEED
		348
		349	It seems that JSON::XS is surprisingly fast, as shown in the following
		350	tables. They have been generated with the help of the C<eg/bench> program
		351	in the JSON::XS distribution, to make it easy to compare on your own
		352	system.
		353
		354	First is a comparison between various modules using a very simple JSON
		355	string, showing the number of encodes/decodes per second (JSON::XS is
		356	the functional interface, while JSON::XS/2 is the OO interface with
		357	pretty-printing and hashkey sorting enabled).
		358
		359	module \| encode \| decode \|
		360	-----------\|------------\|------------\|
		361	JSON \| 14006 \| 6820 \|
		362	JSON::DWIW \| 200937 \| 120386 \|
		363	JSON::PC \| 85065 \| 129366 \|
		364	JSON::Syck \| 59898 \| 44232 \|
		365	JSON::XS \| 1171478 \| 342435 \|
		366	JSON::XS/2 \| 730760 \| 328714 \|
		367	-----------+------------+------------+
		368
		369	That is, JSON::XS is 6 times faster than than JSON::DWIW and about 80
		370	times faster than JSON, even with pretty-printing and key sorting.
		371
		372	Using a longer test string (roughly 8KB, generated from Yahoo! Locals
		373	search API (http://nanoref.com/yahooapis/mgPdGg):
		374
		375	module \| encode \| decode \|
		376	-----------\|------------\|------------\|
		377	JSON \| 673 \| 38 \|
		378	JSON::DWIW \| 5271 \| 770 \|
		379	JSON::PC \| 9901 \| 2491 \|
		380	JSON::Syck \| 2360 \| 786 \|
		381	JSON::XS \| 37398 \| 3202 \|
		382	JSON::XS/2 \| 13765 \| 3153 \|
		383	-----------+------------+------------+
		384
		385	Again, JSON::XS leads by far in the encoding case, while still beating
		386	every other module in the decoding case.
		387
		388	Last example is an almost 8MB large hash with many large binary values
		389	(PNG files), resulting in a lot of escaping:
		390
		391	=head1 BUGS
		392
		393	While the goal of this module is to be correct, that unfortunately does
		394	not mean its bug-free, only that I think its design is bug-free. It is
		395	still very young and not well-tested. If you keep reporting bugs they will
		396	be fixed swiftly, though.
		397
218	=cut	398	=cut
219		399
220	1;	400	1;
221		401
222	=head1 AUTHOR	402	=head1 AUTHOR

Diff Legend

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

Comparing JSON-XS/XS.pm (file contents): Revision 1.2 by root, Thu Mar 22 17:28:50 2007 UTC vs. Revision 1.7 by root, Fri Mar 23 15:10:55 2007 UTC

Diff Legend

Comparing JSON-XS/XS.pm (file contents):
Revision 1.2 by root, Thu Mar 22 17:28:50 2007 UTC vs.
Revision 1.7 by root, Fri Mar 23 15:10:55 2007 UTC