ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/JSON-XS/XS.pm
(Generate patch)

Comparing JSON-XS/XS.pm (file contents):
Revision 1.2 by root, Thu Mar 22 17:28:50 2007 UTC vs.
Revision 1.6 by root, Thu Mar 22 23:24:18 2007 UTC

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

Diff Legend

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