[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.9 by root, Fri Mar 23 16:00:19 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.3';
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. It will also try to downgrade any strings to octet-form
		230	if possible: perl stores strings internally either in an encoding called
		231	UTF-X or in octet-form. The latter cannot store everything but uses less
		232	space in general.
		233
		234	If C<$enable> is true (or missing), the string returned by C<encode> will be shrunk-to-fit,
		235	while all strings generated by C<decode> will also be shrunk-to-fit.
		236
		237	If C<$enable> is false, then the normal perl allocation algorithms are used.
		238	If you work with your data, then this is likely to be faster.
		239
		240	In the future, this setting might control other things, such as converting
		241	strings that look like integers or floats into integers or floats
		242	internally (there is no difference on the Perl level), saving space.
197		243
198	=item $json_string = $json->encode ($perl_scalar)	244	=item $json_string = $json->encode ($perl_scalar)
199		245
200	Converts the given Perl data structure (a simple scalar or a reference	246	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	247	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	259	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>.	260	C<1>, C<false> becomes C<0> and C<null> becomes C<undef>.
215		261
216	=back	262	=back
217		263
		264	=head1 COMPARISON
		265
		266	As already mentioned, this module was created because none of the existing
		267	JSON modules could be made to work correctly. First I will describe the
		268	problems (or pleasures) I encountered with various existing JSON modules,
		269	followed by some benchmark values. JSON::XS was designed not to suffer
		270	from any of these problems or limitations.
		271
		272	=over 4
		273
		274	=item JSON 1.07
		275
		276	Slow (but very portable, as it is written in pure Perl).
		277
		278	Undocumented/buggy Unicode handling (how JSON handles unicode values is
		279	undocumented. One can get far by feeding it unicode strings and doing
		280	en-/decoding oneself, but unicode escapes are not working properly).
		281
		282	No roundtripping (strings get clobbered if they look like numbers, e.g.
		283	the string C<2.0> will encode to C<2.0> instead of C<"2.0">, and that will
		284	decode into the number 2.
		285
		286	=item JSON::PC 0.01
		287
		288	Very fast.
		289
		290	Undocumented/buggy Unicode handling.
		291
		292	No roundtripping.
		293
		294	Has problems handling many Perl values (e.g. regex results and other magic
		295	values will make it croak).
		296
		297	Does not even generate valid JSON (C<{1,2}> gets converted to C<{1:2}>
		298	which is not a valid JSON string.
		299
		300	Unmaintained (maintainer unresponsive for many months, bugs are not
		301	getting fixed).
		302
		303	=item JSON::Syck 0.21
		304
		305	Very buggy (often crashes).
		306
		307	Very inflexible (no human-readable format supported, format pretty much
		308	undocumented. I need at least a format for easy reading by humans and a
		309	single-line compact format for use in a protocol, and preferably a way to
		310	generate ASCII-only JSON strings).
		311
		312	Completely broken (and confusingly documented) Unicode handling (unicode
		313	escapes are not working properly, you need to set ImplicitUnicode to
		314	I<different> values on en- and decoding to get symmetric behaviour).
		315
		316	No roundtripping (simple cases work, but this depends on wether the scalar
		317	value was used in a numeric context or not).
		318
		319	Dumping hashes may skip hash values depending on iterator state.
		320
		321	Unmaintained (maintainer unresponsive for many months, bugs are not
		322	getting fixed).
		323
		324	Does not check input for validity (i.e. will accept non-JSON input and
		325	return "something" instead of raising an exception. This is a security
		326	issue: imagine two banks transfering money between each other using
		327	JSON. One bank might parse a given non-JSON request and deduct money,
		328	while the other might reject the transaction with a syntax error. While a
		329	good protocol will at least recover, that is extra unnecessary work and
		330	the transaction will still not succeed).
		331
		332	=item JSON::DWIW 0.04
		333
		334	Very fast. Very natural. Very nice.
		335
		336	Undocumented unicode handling (but the best of the pack. Unicode escapes
		337	still don't get parsed properly).
		338
		339	Very inflexible.
		340
		341	No roundtripping.
		342
		343	Does not generate valid JSON (key strings are often unquoted, empty keys
		344	result in nothing being output)
		345
		346	Does not check input for validity.
		347
		348	=back
		349
		350	=head2 SPEED
		351
		352	It seems that JSON::XS is surprisingly fast, as shown in the following
		353	tables. They have been generated with the help of the C<eg/bench> program
		354	in the JSON::XS distribution, to make it easy to compare on your own
		355	system.
		356
		357	First is a comparison between various modules using a very simple JSON
		358	string, showing the number of encodes/decodes per second (JSON::XS is
		359	the functional interface, while JSON::XS/2 is the OO interface with
		360	pretty-printing and hashkey sorting enabled).
		361
		362	module \| encode \| decode \|
		363	-----------\|------------\|------------\|
		364	JSON \| 14006 \| 6820 \|
		365	JSON::DWIW \| 200937 \| 120386 \|
		366	JSON::PC \| 85065 \| 129366 \|
		367	JSON::Syck \| 59898 \| 44232 \|
		368	JSON::XS \| 1171478 \| 342435 \|
		369	JSON::XS/2 \| 730760 \| 328714 \|
		370	-----------+------------+------------+
		371
		372	That is, JSON::XS is 6 times faster than than JSON::DWIW and about 80
		373	times faster than JSON, even with pretty-printing and key sorting.
		374
		375	Using a longer test string (roughly 8KB, generated from Yahoo! Locals
		376	search API (http://nanoref.com/yahooapis/mgPdGg):
		377
		378	module \| encode \| decode \|
		379	-----------\|------------\|------------\|
		380	JSON \| 673 \| 38 \|
		381	JSON::DWIW \| 5271 \| 770 \|
		382	JSON::PC \| 9901 \| 2491 \|
		383	JSON::Syck \| 2360 \| 786 \|
		384	JSON::XS \| 37398 \| 3202 \|
		385	JSON::XS/2 \| 13765 \| 3153 \|
		386	-----------+------------+------------+
		387
		388	Again, JSON::XS leads by far in the encoding case, while still beating
		389	every other module in the decoding case.
		390
		391	Last example is an almost 8MB large hash with many large binary values
		392	(PNG files), resulting in a lot of escaping:
		393
		394	=head1 BUGS
		395
		396	While the goal of this module is to be correct, that unfortunately does
		397	not mean its bug-free, only that I think its design is bug-free. It is
		398	still very young and not well-tested. If you keep reporting bugs they will
		399	be fixed swiftly, though.
		400
218	=cut	401	=cut
219		402
220	1;	403	1;
221		404
222	=head1 AUTHOR	405	=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.9 by root, Fri Mar 23 16:00:19 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.9 by root, Fri Mar 23 16:00:19 2007 UTC