JSON-XS/XS.pm

=head1 NAME

JSON::XS - JSON serialising/deserialising, done correctly and fast

=head1 SYNOPSIS

 use JSON::XS;

=head1 DESCRIPTION

This module converts Perl data structures to JSON and vice versa. Its
primary goal is to be I<correct> and its secondary goal is to be
I<fast>. To reach the latter goal it was written in C.

As this is the n-th-something JSON module on CPAN, what was the reason
to write yet another JSON module? While it seems there are many JSON
modules, none of them correctly handle all corner cases, and in most cases
their maintainers are unresponsive, gone missing, or not listening to bug
reports for other reasons.

See COMPARISON, below, for a comparison to some other JSON modules.

=head2 FEATURES

=over 4

=item * correct handling of unicode issues

This module knows how to handle Unicode, and even documents how it does so.

=item * round-trip integrity

When you serialise a perl data structure using only datatypes supported
by JSON, the deserialised data structure is identical on the Perl level.
(e.g. the string "2.0" doesn't suddenly become "2").

=item * strict checking of JSON correctness

There is no guessing, no generating of illegal JSON strings by default,
and only JSON is accepted as input (the latter is a security feature).

=item * fast

compared to other JSON modules, this module compares favourably.

=item * simple to use

This module has both a simple functional interface as well as an OO
interface.

=item * reasonably versatile output formats

You can choose between the most compact format possible, a pure-ascii
format, or a pretty-printed format. Or you can combine those features in
whatever way you like.

=back

=cut

package JSON::XS;

BEGIN {
   $VERSION = '0.2';
   @ISA = qw(Exporter);

   @EXPORT = qw(to_json from_json);
   require Exporter;

   require XSLoader;
   XSLoader::load JSON::XS::, $VERSION;
}

=head1 FUNCTIONAL INTERFACE

The following convinience methods are provided by this module. They are
exported by default:

=over 4

=item $json_string = to_json $perl_scalar

Converts the given Perl data structure (a simple scalar or a reference to
a hash or array) to a UTF-8 encoded, binary string (that is, the string contains
octets only). Croaks on error.

This function call is functionally identical to C<< JSON::XS->new->utf8
(1)->encode ($perl_scalar) >>.

=item $perl_scalar = from_json $json_string

The opposite of C<to_json>: expects an UTF-8 (binary) string and tries to
parse that as an UTF-8 encoded JSON string, returning the resulting simple
scalar or reference. Croaks on error.

This function call is functionally identical to C<< JSON::XS->new->utf8
(1)->decode ($json_string) >>.

=back

=head1 OBJECT-ORIENTED INTERFACE

The object oriented interface lets you configure your own encoding or
decoding style, within the limits of supported formats.

=over 4

=item $json = new JSON::XS

Creates a new JSON::XS object that can be used to de/encode JSON
strings. All boolean flags described below are by default I<disabled>.

The mutators for flags all return the JSON object again and thus calls can
be chained:

   my $json = JSON::XS->new->utf8(1)->space_after(1)->encode ({a => [1,2]})
   => {"a": [1, 2]}

=item $json = $json->ascii ([$enable])

If C<$enable> is true (or missing), then the C<encode> method will
not generate characters outside the code range C<0..127>. Any unicode
characters outside that range will be escaped using either a single
\uXXXX (BMP characters) or a double \uHHHH\uLLLLL escape sequence, as per
RFC4627.

If C<$enable> is false, then the C<encode> method will not escape Unicode
characters unless necessary.

  JSON::XS->new->ascii (1)->encode (chr 0x10401)
  => \ud801\udc01

=item $json = $json->utf8 ([$enable])

If C<$enable> is true (or missing), then the C<encode> method will encode
the JSON string into UTF-8, as required by many protocols, while the
C<decode> method expects to be handled an UTF-8-encoded string.  Please
note that UTF-8-encoded strings do not contain any characters outside the
range C<0..255>, they are thus useful for bytewise/binary I/O.

If C<$enable> is false, then the C<encode> method will return the JSON
string as a (non-encoded) unicode string, while C<decode> expects thus a
unicode string.  Any decoding or encoding (e.g. to UTF-8 or UTF-16) needs
to be done yourself, e.g. using the Encode module.

=item $json = $json->pretty ([$enable])

This enables (or disables) all of the C<indent>, C<space_before> and
C<space_after> (and in the future possibly more) flags in one call to
generate the most readable (or most compact) form possible.

   my $json = JSON::XS->new->pretty(1)->encode ({a => [1,2]})
   =>
   {
      "a" : [
         1,
         2
      ]
   }

=item $json = $json->indent ([$enable])

If C<$enable> is true (or missing), then the C<encode> method will use a multiline
format as output, putting every array member or object/hash key-value pair
into its own line, identing them properly.

If C<$enable> is false, no newlines or indenting will be produced, and the
resulting JSON strings is guarenteed not to contain any C<newlines>.

This setting has no effect when decoding JSON strings.

=item $json = $json->space_before ([$enable])

If C<$enable> is true (or missing), then the C<encode> method will add an extra
optional space before the C<:> separating keys from values in JSON objects.

If C<$enable> is false, then the C<encode> method will not add any extra
space at those places.

This setting has no effect when decoding JSON strings. You will also most
likely combine this setting with C<space_after>.

=item $json = $json->space_after ([$enable])

If C<$enable> is true (or missing), then the C<encode> method will add an extra
optional space after the C<:> separating keys from values in JSON objects
and extra whitespace after the C<,> separating key-value pairs and array
members.

If C<$enable> is false, then the C<encode> method will not add any extra
space at those places.

This setting has no effect when decoding JSON strings.

=item $json = $json->canonical ([$enable])

If C<$enable> is true (or missing), then the C<encode> method will output JSON objects
by sorting their keys. This is adding a comparatively high overhead.

If C<$enable> is false, then the C<encode> method will output key-value
pairs in the order Perl stores them (which will likely change between runs
of the same script).

This option is useful if you want the same data structure to be encoded as
the same JSON string (given the same overall settings). If it is disabled,
the same hash migh be encoded differently even if contains the same data,
as key-value pairs have no inherent ordering in Perl.

This setting has no effect when decoding JSON strings.

=item $json = $json->allow_nonref ([$enable])

If C<$enable> is true (or missing), then the C<encode> method can convert a
non-reference into its corresponding string, number or null JSON value,
which is an extension to RFC4627. Likewise, C<decode> will accept those JSON
values instead of croaking.

If C<$enable> is false, then the C<encode> method will croak if it isn't
passed an arrayref or hashref, as JSON strings must either be an object
or array. Likewise, C<decode> will croak if given something that is not a
JSON object or array.

=item $json = $json->shrink ([$enable])

Perl usually over-allocates memory a bit when allocating space for
strings.  This flag optionally resizes strings generated by either
C<encode> or C<decode> to their minimum size possible. This can save
memory when your JSON strings are either very very long or you have many
short strings. It will also try to downgrade any strings to octet-form
if possible: perl stores strings internally either in an encoding called
UTF-X or in octet-form. The latter cannot store everything but uses less
space in general.

If C<$enable> is true (or missing), the string returned by C<encode> will be shrunk-to-fit,
while all strings generated by C<decode> will also be shrunk-to-fit.

If C<$enable> is false, then the normal perl allocation algorithms are used.
If you work with your data, then this is likely to be faster.

In the future, this setting might control other things, such as converting
strings that look like integers or floats into integers or floats
internally (there is no difference on the Perl level), saving space.

=item $json_string = $json->encode ($perl_scalar)

Converts the given Perl data structure (a simple scalar or a reference
to a hash or array) to its JSON representation. Simple scalars will be
converted into JSON string or number sequences, while references to arrays
become JSON arrays and references to hashes become JSON objects. Undefined
Perl values (e.g. C<undef>) become JSON C<null> values. Neither C<true>
nor C<false> values will be generated.

=item $perl_scalar = $json->decode ($json_string)

The opposite of C<encode>: expects a JSON string and tries to parse it,
returning the resulting simple scalar or reference. Croaks on error.

JSON numbers and strings become simple Perl scalars. JSON arrays become
Perl arrayrefs and JSON objects become Perl hashrefs. C<true> becomes
C<1>, C<false> becomes C<0> and C<null> becomes C<undef>.

=back

=head1 COMPARISON

As already mentioned, this module was created because none of the existing
JSON modules could be made to work correctly. First I will describe the
problems (or pleasures) I encountered with various existing JSON modules,
followed by some benchmark values. JSON::XS was designed not to suffer
from any of these problems or limitations.

=over 4

=item JSON 1.07

Slow (but very portable, as it is written in pure Perl).

Undocumented/buggy Unicode handling (how JSON handles unicode values is
undocumented. One can get far by feeding it unicode strings and doing
en-/decoding oneself, but unicode escapes are not working properly).

No roundtripping (strings get clobbered if they look like numbers, e.g.
the string C<2.0> will encode to C<2.0> instead of C<"2.0">, and that will
decode into the number 2.

=item JSON::PC 0.01

Very fast.

Undocumented/buggy Unicode handling.

No roundtripping.

Has problems handling many Perl values (e.g. regex results and other magic
values will make it croak).

Does not even generate valid JSON (C<{1,2}> gets converted to C<{1:2}>
which is not a valid JSON string.

Unmaintained (maintainer unresponsive for many months, bugs are not
getting fixed).

=item JSON::Syck 0.21

Very buggy (often crashes).

Very inflexible (no human-readable format supported, format pretty much
undocumented. I need at least a format for easy reading by humans and a
single-line compact format for use in a protocol, and preferably a way to
generate ASCII-only JSON strings).

Completely broken (and confusingly documented) Unicode handling (unicode
escapes are not working properly, you need to set ImplicitUnicode to
I<different> values on en- and decoding to get symmetric behaviour).

No roundtripping (simple cases work, but this depends on wether the scalar
value was used in a numeric context or not).

Dumping hashes may skip hash values depending on iterator state.

Unmaintained (maintainer unresponsive for many months, bugs are not
getting fixed).

Does not check input for validity (i.e. will accept non-JSON input and
return "something" instead of raising an exception. This is a security
issue: imagine two banks transfering money between each other using
JSON. One bank might parse a given non-JSON request and deduct money,
while the other might reject the transaction with a syntax error. While a
good protocol will at least recover, that is extra unnecessary work and
the transaction will still not succeed).

=item JSON::DWIW 0.04

Very fast. Very natural. Very nice.

Undocumented unicode handling (but the best of the pack. Unicode escapes
still don't get parsed properly).

Very inflexible.

No roundtripping.

Does not generate valid JSON (key strings are often unquoted, empty keys
result in nothing being output)

Does not check input for validity.

=back

=head2 SPEED

It seems that JSON::XS is surprisingly fast, as shown in the following
tables. They have been generated with the help of the C<eg/bench> program
in the JSON::XS distribution, to make it easy to compare on your own
system.

First is a comparison between various modules using a very simple JSON
string, showing the number of encodes/decodes per second (JSON::XS is
the functional interface, while JSON::XS/2 is the OO interface with
pretty-printing and hashkey sorting enabled).

   module     |     encode |     decode |
   -----------|------------|------------|
   JSON       |      14006 |       6820 |
   JSON::DWIW |     200937 |     120386 |
   JSON::PC   |      85065 |     129366 |
   JSON::Syck |      59898 |      44232 |
   JSON::XS   |    1171478 |     342435 |
   JSON::XS/2 |     730760 |     328714 |
   -----------+------------+------------+

That is, JSON::XS is 6 times faster than than JSON::DWIW and about 80
times faster than JSON, even with pretty-printing and key sorting.

Using a longer test string (roughly 8KB, generated from Yahoo! Locals
search API (http://nanoref.com/yahooapis/mgPdGg):

   module     |     encode |     decode |
   -----------|------------|------------|
   JSON       |        673 |         38 |
   JSON::DWIW |       5271 |        770 |
   JSON::PC   |       9901 |       2491 |
   JSON::Syck |       2360 |        786 |
   JSON::XS   |      37398 |       3202 |
   JSON::XS/2 |      13765 |       3153 |
   -----------+------------+------------+

Again, JSON::XS leads by far in the encoding case, while still beating
every other module in the decoding case.

Last example is an almost 8MB large hash with many large binary values
(PNG files), resulting in a lot of escaping:

=head1 BUGS

While the goal of this module is to be correct, that unfortunately does
not mean its bug-free, only that I think its design is bug-free. It is
still very young and not well-tested. If you keep reporting bugs they will
be fixed swiftly, though.

=cut

1;

=head1 AUTHOR

 Marc Lehmann <schmorp@schmorp.de>
 http://home.schmorp.de/

=cut

Revision:	1.8
Committed:	Fri Mar 23 15:57:18 2007 UTC (17 years, 2 months ago) by root
Branch:	MAIN
Changes since 1.7:	+4 -1 lines
Log Message:	* empty log message *
#	User	Rev	Content
1	root	1.1	=head1 NAME
2
3			JSON::XS - JSON serialising/deserialising, done correctly and fast
4
5			=head1 SYNOPSIS
6
7			use JSON::XS;
8
9			=head1 DESCRIPTION
10
11	root	1.2	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
13			I<fast>. To reach the latter goal it was written in C.
14
15			As this is the n-th-something JSON module on CPAN, what was the reason
16			to write yet another JSON module? While it seems there are many JSON
17			modules, none of them correctly handle all corner cases, and in most cases
18			their maintainers are unresponsive, gone missing, or not listening to bug
19			reports for other reasons.
20
21			See COMPARISON, below, for a comparison to some other JSON modules.
22
23			=head2 FEATURES
24
25	root	1.1	=over 4
26
27	root	1.2	=item * correct handling of unicode issues
28
29			This module knows how to handle Unicode, and even documents how it does so.
30
31			=item * round-trip integrity
32
33			When you serialise a perl data structure using only datatypes supported
34			by JSON, the deserialised data structure is identical on the Perl level.
35			(e.g. the string "2.0" doesn't suddenly become "2").
36
37			=item * strict checking of JSON correctness
38
39			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).
41
42			=item * fast
43
44			compared to other JSON modules, this module compares favourably.
45
46			=item * simple to use
47
48			This module has both a simple functional interface as well as an OO
49			interface.
50
51			=item * reasonably versatile output formats
52
53			You can choose between the most compact format possible, a pure-ascii
54			format, or a pretty-printed format. Or you can combine those features in
55			whatever way you like.
56
57			=back
58
59	root	1.1	=cut
60
61			package JSON::XS;
62
63			BEGIN {
64	root	1.6	$VERSION = '0.2';
65	root	1.1	@ISA = qw(Exporter);
66
67	root	1.2	@EXPORT = qw(to_json from_json);
68	root	1.1	require Exporter;
69
70			require XSLoader;
71			XSLoader::load JSON::XS::, $VERSION;
72			}
73
74	root	1.2	=head1 FUNCTIONAL INTERFACE
75
76			The following convinience methods are provided by this module. They are
77			exported by default:
78
79			=over 4
80
81			=item $json_string = to_json $perl_scalar
82
83			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
85			octets only). Croaks on error.
86
87			This function call is functionally identical to C<< JSON::XS->new->utf8
88			(1)->encode ($perl_scalar) >>.
89
90			=item $perl_scalar = from_json $json_string
91
92			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
94			scalar or reference. Croaks on error.
95
96			This function call is functionally identical to C<< JSON::XS->new->utf8
97			(1)->decode ($json_string) >>.
98
99			=back
100
101			=head1 OBJECT-ORIENTED INTERFACE
102
103			The object oriented interface lets you configure your own encoding or
104			decoding style, within the limits of supported formats.
105
106			=over 4
107
108			=item $json = new JSON::XS
109
110			Creates a new JSON::XS object that can be used to de/encode JSON
111			strings. All boolean flags described below are by default I<disabled>.
112	root	1.1
113	root	1.2	The mutators for flags all return the JSON object again and thus calls can
114			be chained:
115
116	root	1.3	my $json = JSON::XS->new->utf8(1)->space_after(1)->encode ({a => [1,2]})
117			=> {"a": [1, 2]}
118	root	1.2
119	root	1.7	=item $json = $json->ascii ([$enable])
120	root	1.2
121	root	1.7	If C<$enable> is true (or missing), then the C<encode> method will
122			not generate characters outside the code range C<0..127>. Any unicode
123			characters outside that range will be escaped using either a single
124			\uXXXX (BMP characters) or a double \uHHHH\uLLLLL escape sequence, as per
125			RFC4627.
126	root	1.2
127			If C<$enable> is false, then the C<encode> method will not escape Unicode
128			characters unless necessary.
129
130	root	1.3	JSON::XS->new->ascii (1)->encode (chr 0x10401)
131			=> \ud801\udc01
132
133	root	1.7	=item $json = $json->utf8 ([$enable])
134	root	1.2
135	root	1.7	If C<$enable> is true (or missing), then the C<encode> method will encode
136			the JSON string into UTF-8, as required by many protocols, while the
137			C<decode> method expects to be handled an UTF-8-encoded string. Please
138			note that UTF-8-encoded strings do not contain any characters outside the
139			range C<0..255>, they are thus useful for bytewise/binary I/O.
140	root	1.2
141			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
143			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.
145
146	root	1.7	=item $json = $json->pretty ([$enable])
147	root	1.2
148			This enables (or disables) all of the C<indent>, C<space_before> and
149	root	1.3	C<space_after> (and in the future possibly more) flags in one call to
150	root	1.2	generate the most readable (or most compact) form possible.
151
152	root	1.3	my $json = JSON::XS->new->pretty(1)->encode ({a => [1,2]})
153			=>
154			{
155			"a" : [
156			1,
157			2
158			]
159			}
160
161	root	1.7	=item $json = $json->indent ([$enable])
162	root	1.2
163	root	1.7	If C<$enable> is true (or missing), then the C<encode> method will use a multiline
164	root	1.2	format as output, putting every array member or object/hash key-value pair
165			into its own line, identing them properly.
166
167			If C<$enable> is false, no newlines or indenting will be produced, and the
168			resulting JSON strings is guarenteed not to contain any C<newlines>.
169
170			This setting has no effect when decoding JSON strings.
171
172	root	1.7	=item $json = $json->space_before ([$enable])
173	root	1.2
174	root	1.7	If C<$enable> is true (or missing), then the C<encode> method will add an extra
175	root	1.2	optional space before the C<:> separating keys from values in JSON objects.
176
177			If C<$enable> is false, then the C<encode> method will not add any extra
178			space at those places.
179
180			This setting has no effect when decoding JSON strings. You will also most
181			likely combine this setting with C<space_after>.
182
183	root	1.7	=item $json = $json->space_after ([$enable])
184	root	1.2
185	root	1.7	If C<$enable> is true (or missing), then the C<encode> method will add an extra
186	root	1.2	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
188			members.
189
190			If C<$enable> is false, then the C<encode> method will not add any extra
191			space at those places.
192
193			This setting has no effect when decoding JSON strings.
194
195	root	1.7	=item $json = $json->canonical ([$enable])
196	root	1.2
197	root	1.7	If C<$enable> is true (or missing), then the C<encode> method will output JSON objects
198	root	1.2	by sorting their keys. This is adding a comparatively high overhead.
199
200			If C<$enable> is false, then the C<encode> method will output key-value
201			pairs in the order Perl stores them (which will likely change between runs
202			of the same script).
203
204			This option is useful if you want the same data structure to be encoded as
205			the same JSON string (given the same overall settings). If it is disabled,
206			the same hash migh be encoded differently even if contains the same data,
207			as key-value pairs have no inherent ordering in Perl.
208
209			This setting has no effect when decoding JSON strings.
210
211	root	1.7	=item $json = $json->allow_nonref ([$enable])
212	root	1.3
213	root	1.7	If C<$enable> is true (or missing), then the C<encode> method can convert a
214	root	1.3	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	root	1.7	=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	root	1.8	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	root	1.7
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.
243
244	root	1.2	=item $json_string = $json->encode ($perl_scalar)
245
246			Converts the given Perl data structure (a simple scalar or a reference
247			to a hash or array) to its JSON representation. Simple scalars will be
248			converted into JSON string or number sequences, while references to arrays
249			become JSON arrays and references to hashes become JSON objects. Undefined
250			Perl values (e.g. C<undef>) become JSON C<null> values. Neither C<true>
251			nor C<false> values will be generated.
252	root	1.1
253	root	1.2	=item $perl_scalar = $json->decode ($json_string)
254	root	1.1
255	root	1.2	The opposite of C<encode>: expects a JSON string and tries to parse it,
256			returning the resulting simple scalar or reference. Croaks on error.
257	root	1.1
258	root	1.2	JSON numbers and strings become simple Perl scalars. JSON arrays become
259			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>.
261	root	1.1
262			=back
263
264	root	1.3	=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	root	1.4	followed by some benchmark values. JSON::XS was designed not to suffer
270			from any of these problems or limitations.
271	root	1.3
272			=over 4
273
274	root	1.5	=item JSON 1.07
275	root	1.3
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	root	1.5	=item JSON::PC 0.01
287	root	1.3
288			Very fast.
289
290			Undocumented/buggy Unicode handling.
291
292			No roundtripping.
293
294	root	1.4	Has problems handling many Perl values (e.g. regex results and other magic
295			values will make it croak).
296	root	1.3
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	root	1.5	=item JSON::Syck 0.21
304	root	1.3
305			Very buggy (often crashes).
306
307	root	1.4	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	root	1.3
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	root	1.5	=item JSON::DWIW 0.04
333	root	1.3
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	root	1.4	Does not generate valid JSON (key strings are often unquoted, empty keys
344			result in nothing being output)
345
346	root	1.3	Does not check input for validity.
347
348			=back
349
350			=head2 SPEED
351
352	root	1.4	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
401	root	1.2	=cut
402
403			1;
404
405	root	1.1	=head1 AUTHOR
406
407			Marc Lehmann <schmorp@schmorp.de>
408			http://home.schmorp.de/
409
410			=cut
411