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

Comparing JSON-XS/XS.pm (file contents):
Revision 1.9 by root, Fri Mar 23 16:00:19 2007 UTC vs.
Revision 1.14 by root, Fri Mar 23 19:02:02 2007 UTC

…		…
3	JSON::XS - JSON serialising/deserialising, done correctly and fast	3	JSON::XS - JSON serialising/deserialising, done correctly and fast
4		4
5	=head1 SYNOPSIS	5	=head1 SYNOPSIS
6		6
7	use JSON::XS;	7	use JSON::XS;
		8
		9	# exported functions, croak on error
		10
		11	$utf8_encoded_json_text = to_json $perl_hash_or_arrayref;
		12	$perl_hash_or_arrayref = from_json $utf8_encoded_json_text;
		13
		14	# oo-interface
		15
		16	$coder = JSON::XS->new->ascii->pretty->allow_nonref;
		17	$pretty_printed_unencoded = $coder->encode ($perl_scalar);
		18	$perl_scalar = $coder->decode ($unicode_json_text);
8		19
9	=head1 DESCRIPTION	20	=head1 DESCRIPTION
10		21
11	This module converts Perl data structures to JSON and vice versa. Its	22	This module converts Perl data structures to JSON and vice versa. Its
12	primary goal is to be I<correct> and its secondary goal is to be	23	primary goal is to be I<correct> and its secondary goal is to be
…		…
18	their maintainers are unresponsive, gone missing, or not listening to bug	29	their maintainers are unresponsive, gone missing, or not listening to bug
19	reports for other reasons.	30	reports for other reasons.
20		31
21	See COMPARISON, below, for a comparison to some other JSON modules.	32	See COMPARISON, below, for a comparison to some other JSON modules.
22		33
		34	See MAPPING, below, on how JSON::XS maps perl values to JSON values and
		35	vice versa.
		36
23	=head2 FEATURES	37	=head2 FEATURES
24		38
25	=over 4	39	=over 4
26		40
27	=item * correct handling of unicode issues	41	=item * correct handling of unicode issues
28		42
29	This module knows how to handle Unicode, and even documents how it does so.	43	This module knows how to handle Unicode, and even documents how and when
		44	it does so.
30		45
31	=item * round-trip integrity	46	=item * round-trip integrity
32		47
33	When you serialise a perl data structure using only datatypes supported	48	When you serialise a perl data structure using only datatypes supported
34	by JSON, the deserialised data structure is identical on the Perl level.	49	by JSON, the deserialised data structure is identical on the Perl level.
35	(e.g. the string "2.0" doesn't suddenly become "2").	50	(e.g. the string "2.0" doesn't suddenly become "2").
36		51
37	=item * strict checking of JSON correctness	52	=item * strict checking of JSON correctness
38		53
39	There is no guessing, no generating of illegal JSON strings by default,	54	There is no guessing, no generating of illegal JSON strings by default,
40	and only JSON is accepted as input (the latter is a security feature).	55	and only JSON is accepted as input by default (the latter is a security
		56	feature).
41		57
42	=item * fast	58	=item * fast
43		59
44	compared to other JSON modules, this module compares favourably.	60	Compared to other JSON modules, this module compares favourably in terms
		61	of speed, too.
45		62
46	=item * simple to use	63	=item * simple to use
47		64
48	This module has both a simple functional interface as well as an OO	65	This module has both a simple functional interface as well as an OO
49	interface.	66	interface.
50		67
51	=item * reasonably versatile output formats	68	=item * reasonably versatile output formats
52		69
53	You can choose between the most compact format possible, a pure-ascii	70	You can choose between the most compact guarenteed single-line format
54	format, or a pretty-printed format. Or you can combine those features in	71	possible (nice for simple line-based protocols), a pure-ascii format (for
		72	when your transport is not 8-bit clean), or a pretty-printed format (for
		73	when you want to read that stuff). Or you can combine those features in
55	whatever way you like.	74	whatever way you like.
56		75
57	=back	76	=back
58		77
59	=cut	78	=cut
…		…
82		101
83	Converts the given Perl data structure (a simple scalar or a reference to	102	Converts the given Perl data structure (a simple scalar or a reference to
84	a hash or array) to a UTF-8 encoded, binary string (that is, the string contains	103	a hash or array) to a UTF-8 encoded, binary string (that is, the string contains
85	octets only). Croaks on error.	104	octets only). Croaks on error.
86		105
87	This function call is functionally identical to C<< JSON::XS->new->utf8	106	This function call is functionally identical to C<< JSON::XS->new->utf8->encode ($perl_scalar) >>.
88	(1)->encode ($perl_scalar) >>.
89		107
90	=item $perl_scalar = from_json $json_string	108	=item $perl_scalar = from_json $json_string
91		109
92	The opposite of C<to_json>: expects an UTF-8 (binary) string and tries to	110	The opposite of C<to_json>: expects an UTF-8 (binary) string and tries to
93	parse that as an UTF-8 encoded JSON string, returning the resulting simple	111	parse that as an UTF-8 encoded JSON string, returning the resulting simple
94	scalar or reference. Croaks on error.	112	scalar or reference. Croaks on error.
95		113
96	This function call is functionally identical to C<< JSON::XS->new->utf8	114	This function call is functionally identical to C<< JSON::XS->new->utf8->decode ($json_string) >>.
97	(1)->decode ($json_string) >>.
98		115
99	=back	116	=back
100		117
101	=head1 OBJECT-ORIENTED INTERFACE	118	=head1 OBJECT-ORIENTED INTERFACE
102		119
…		…
141	If C<$enable> is false, then the C<encode> method will return the JSON	158	If C<$enable> is false, then the C<encode> method will return the JSON
142	string as a (non-encoded) unicode string, while C<decode> expects thus a	159	string as a (non-encoded) unicode string, while C<decode> expects thus a
143	unicode string. Any decoding or encoding (e.g. to UTF-8 or UTF-16) needs	160	unicode string. Any decoding or encoding (e.g. to UTF-8 or UTF-16) needs
144	to be done yourself, e.g. using the Encode module.	161	to be done yourself, e.g. using the Encode module.
145		162
		163	Example, output UTF-16-encoded JSON:
		164
146	=item $json = $json->pretty ([$enable])	165	=item $json = $json->pretty ([$enable])
147		166
148	This enables (or disables) all of the C<indent>, C<space_before> and	167	This enables (or disables) all of the C<indent>, C<space_before> and
149	C<space_after> (and in the future possibly more) flags in one call to	168	C<space_after> (and in the future possibly more) flags in one call to
150	generate the most readable (or most compact) form possible.	169	generate the most readable (or most compact) form possible.
		170
		171	Example, pretty-print some simple structure:
151		172
152	my $json = JSON::XS->new->pretty(1)->encode ({a => [1,2]})	173	my $json = JSON::XS->new->pretty(1)->encode ({a => [1,2]})
153	=>	174	=>
154	{	175	{
155	"a" : [	176	"a" : [
…		…
178	space at those places.	199	space at those places.
179		200
180	This setting has no effect when decoding JSON strings. You will also most	201	This setting has no effect when decoding JSON strings. You will also most
181	likely combine this setting with C<space_after>.	202	likely combine this setting with C<space_after>.
182		203
		204	Example, space_before enabled, space_after and indent disabled:
		205
		206	{"key" :"value"}
		207
183	=item $json = $json->space_after ([$enable])	208	=item $json = $json->space_after ([$enable])
184		209
185	If C<$enable> is true (or missing), then the C<encode> method will add an extra	210	If C<$enable> is true (or missing), then the C<encode> method will add an extra
186	optional space after the C<:> separating keys from values in JSON objects	211	optional space after the C<:> separating keys from values in JSON objects
187	and extra whitespace after the C<,> separating key-value pairs and array	212	and extra whitespace after the C<,> separating key-value pairs and array
…		…
190	If C<$enable> is false, then the C<encode> method will not add any extra	215	If C<$enable> is false, then the C<encode> method will not add any extra
191	space at those places.	216	space at those places.
192		217
193	This setting has no effect when decoding JSON strings.	218	This setting has no effect when decoding JSON strings.
194		219
		220	Example, space_before and indent disabled, space_after enabled:
		221
		222	{"key": "value"}
		223
195	=item $json = $json->canonical ([$enable])	224	=item $json = $json->canonical ([$enable])
196		225
197	If C<$enable> is true (or missing), then the C<encode> method will output JSON objects	226	If C<$enable> is true (or missing), then the C<encode> method will output JSON objects
198	by sorting their keys. This is adding a comparatively high overhead.	227	by sorting their keys. This is adding a comparatively high overhead.
199		228
…		…
217		246
218	If C<$enable> is false, then the C<encode> method will croak if it isn't	247	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	248	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	249	or array. Likewise, C<decode> will croak if given something that is not a
221	JSON object or array.	250	JSON object or array.
		251
		252	Example, encode a Perl scalar as JSON value with enabled C<allow_nonref>,
		253	resulting in an invalid JSON text:
		254
		255	JSON::XS->new->allow_nonref->encode ("Hello, World!")
		256	=> "Hello, World!"
222		257
223	=item $json = $json->shrink ([$enable])	258	=item $json = $json->shrink ([$enable])
224		259
225	Perl usually over-allocates memory a bit when allocating space for	260	Perl usually over-allocates memory a bit when allocating space for
226	strings. This flag optionally resizes strings generated by either	261	strings. This flag optionally resizes strings generated by either
…		…
259	Perl arrayrefs and JSON objects become Perl hashrefs. C<true> becomes	294	Perl arrayrefs and JSON objects become Perl hashrefs. C<true> becomes
260	C<1>, C<false> becomes C<0> and C<null> becomes C<undef>.	295	C<1>, C<false> becomes C<0> and C<null> becomes C<undef>.
261		296
262	=back	297	=back
263		298
		299	=head1 MAPPING
		300
		301	This section describes how JSON::XS maps Perl values to JSON values and
		302	vice versa. These mappings are designed to "do the right thing" in most
		303	circumstances automatically, preserving round-tripping characteristics
		304	(what you put in comes out as something equivalent).
		305
		306	For the more enlightened: note that in the following descriptions,
		307	lowercase I<perl> refers to the Perl interpreter, while uppcercase I<Perl>
		308	refers to the abstract Perl language itself.
		309
		310	=head2 JSON -> PERL
		311
		312	=over 4
		313
		314	=item object
		315
		316	A JSON object becomes a reference to a hash in Perl. No ordering of object
		317	keys is preserved (JSON does not preserver object key ordering itself).
		318
		319	=item array
		320
		321	A JSON array becomes a reference to an array in Perl.
		322
		323	=item string
		324
		325	A JSON string becomes a string scalar in Perl - Unicode codepoints in JSON
		326	are represented by the same codepoints in the Perl string, so no manual
		327	decoding is necessary.
		328
		329	=item number
		330
		331	A JSON number becomes either an integer or numeric (floating point)
		332	scalar in perl, depending on its range and any fractional parts. On the
		333	Perl level, there is no difference between those as Perl handles all the
		334	conversion details, but an integer may take slightly less memory and might
		335	represent more values exactly than (floating point) numbers.
		336
		337	=item true, false
		338
		339	These JSON atoms become C<0>, C<1>, respectively. Information is lost in
		340	this process. Future versions might represent those values differently,
		341	but they will be guarenteed to act like these integers would normally in
		342	Perl.
		343
		344	=item null
		345
		346	A JSON null atom becomes C<undef> in Perl.
		347
		348	=back
		349
		350	=head2 PERL -> JSON
		351
		352	The mapping from Perl to JSON is slightly more difficult, as Perl is a
		353	truly typeless language, so we can only guess which JSON type is meant by
		354	a Perl value.
		355
		356	=over 4
		357
		358	=item hash references
		359
		360	Perl hash references become JSON objects. As there is no inherent ordering
		361	in hash keys, they will usually be encoded in a pseudo-random order that
		362	can change between runs of the same program but stays generally the same
		363	within a single run of a program. JSON::XS can optionally sort the hash
		364	keys (determined by the I<canonical> flag), so the same datastructure
		365	will serialise to the same JSON text (given same settings and version of
		366	JSON::XS), but this incurs a runtime overhead.
		367
		368	=item array references
		369
		370	Perl array references become JSON arrays.
		371
		372	=item blessed objects
		373
		374	Blessed objects are not allowed. JSON::XS currently tries to encode their
		375	underlying representation (hash- or arrayref), but this behaviour might
		376	change in future versions.
		377
		378	=item simple scalars
		379
		380	Simple Perl scalars (any scalar that is not a reference) are the most
		381	difficult objects to encode: JSON::XS will encode undefined scalars as
		382	JSON null value, scalars that have last been used in a string context
		383	before encoding as JSON strings and anything else as number value:
		384
		385	# dump as number
		386	to_json [2] # yields [2]
		387	to_json [-3.0e17] # yields [-3e+17]
		388	my $value = 5; to_json [$value] # yields [5]
		389
		390	# used as string, so dump as string
		391	print $value;
		392	to_json [$value] # yields ["5"]
		393
		394	# undef becomes null
		395	to_json [undef] # yields [null]
		396
		397	You can force the type to be a string by stringifying it:
		398
		399	my $x = 3.1; # some variable containing a number
		400	"$x"; # stringified
		401	$x .= ""; # another, more awkward way to stringify
		402	print $x; # perl does it for you, too, quite often
		403
		404	You can force the type to be a number by numifying it:
		405
		406	my $x = "3"; # some variable containing a string
		407	$x += 0; # numify it, ensuring it will be dumped as a number
		408	$x *= 1; # same thing, the choise is yours.
		409
		410	You can not currently output JSON booleans or force the type in other,
		411	less obscure, ways. Tell me if you need this capability.
		412
		413	=item circular data structures
		414
		415	Those will be encoded until memory or stackspace runs out.
		416
		417	=back
		418
264	=head1 COMPARISON	419	=head1 COMPARISON
265		420
266	As already mentioned, this module was created because none of the existing	421	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	422	JSON modules could be made to work correctly. First I will describe the
268	problems (or pleasures) I encountered with various existing JSON modules,	423	problems (or pleasures) I encountered with various existing JSON modules,
…		…
352	It seems that JSON::XS is surprisingly fast, as shown in the following	507	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	508	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	509	in the JSON::XS distribution, to make it easy to compare on your own
355	system.	510	system.
356		511
357	First is a comparison between various modules using a very simple JSON	512	First comes a comparison between various modules using a very short JSON
358	string, showing the number of encodes/decodes per second (JSON::XS is	513	string (83 bytes), showing the number of encodes/decodes per second
359	the functional interface, while JSON::XS/2 is the OO interface with	514	(JSON::XS is the functional interface, while JSON::XS/2 is the OO
360	pretty-printing and hashkey sorting enabled).	515	interface with pretty-printing and hashkey sorting enabled). Higher is
		516	better:
361		517
362	module \| encode \| decode \|	518	module \| encode \| decode \|
363	-----------\|------------\|------------\|	519	-----------\|------------\|------------\|
364	JSON \| 14006 \| 6820 \|	520	JSON \| 14006 \| 6820 \|
365	JSON::DWIW \| 200937 \| 120386 \|	521	JSON::DWIW \| 200937 \| 120386 \|
…		…
370	-----------+------------+------------+	526	-----------+------------+------------+
371		527
372	That is, JSON::XS is 6 times faster than than JSON::DWIW and about 80	528	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.	529	times faster than JSON, even with pretty-printing and key sorting.
374		530
375	Using a longer test string (roughly 8KB, generated from Yahoo! Locals	531	Using a longer test string (roughly 18KB, generated from Yahoo! Locals
376	search API (http://nanoref.com/yahooapis/mgPdGg):	532	search API (http://nanoref.com/yahooapis/mgPdGg):
377		533
378	module \| encode \| decode \|	534	module \| encode \| decode \|
379	-----------\|------------\|------------\|	535	-----------\|------------\|------------\|
380	JSON \| 673 \| 38 \|	536	JSON \| 673 \| 38 \|
…		…
386	-----------+------------+------------+	542	-----------+------------+------------+
387		543
388	Again, JSON::XS leads by far in the encoding case, while still beating	544	Again, JSON::XS leads by far in the encoding case, while still beating
389	every other module in the decoding case.	545	every other module in the decoding case.
390		546
391	Last example is an almost 8MB large hash with many large binary values	547	On large strings containing lots of unicode characters, some modules
392	(PNG files), resulting in a lot of escaping:	548	(such as JSON::PC) decode faster than JSON::XS, but the result will be
		549	broken due to missing unicode handling. Others refuse to decode or encode
		550	properly, so it was impossible to prepare a fair comparison table for that
		551	case.
		552
		553	=head1 RESOURCE LIMITS
		554
		555	JSON::XS does not impose any limits on the size of JSON texts or Perl
		556	values they represent - if your machine can handle it, JSON::XS will
		557	encode or decode it. Future versions might optionally impose structure
		558	depth and memory use resource limits.
393		559
394	=head1 BUGS	560	=head1 BUGS
395		561
396	While the goal of this module is to be correct, that unfortunately does	562	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	563	not mean its bug-free, only that I think its design is bug-free. It is

Diff Legend

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

Comparing JSON-XS/XS.pm (file contents): Revision 1.9 by root, Fri Mar 23 16:00:19 2007 UTC vs. Revision 1.14 by root, Fri Mar 23 19:02:02 2007 UTC

Diff Legend

Comparing JSON-XS/XS.pm (file contents):
Revision 1.9 by root, Fri Mar 23 16:00:19 2007 UTC vs.
Revision 1.14 by root, Fri Mar 23 19:02:02 2007 UTC