… | |
… | |
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 |
… | |
… | |
147 | 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 |
148 | 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 |
149 | 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 |
150 | to be done yourself, e.g. using the Encode module. |
161 | to be done yourself, e.g. using the Encode module. |
151 | |
162 | |
|
|
163 | Example, output UTF-16-encoded JSON: |
|
|
164 | |
152 | =item $json = $json->pretty ([$enable]) |
165 | =item $json = $json->pretty ([$enable]) |
153 | |
166 | |
154 | 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 |
155 | 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 |
156 | 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: |
157 | |
172 | |
158 | my $json = JSON::XS->new->pretty(1)->encode ({a => [1,2]}) |
173 | my $json = JSON::XS->new->pretty(1)->encode ({a => [1,2]}) |
159 | => |
174 | => |
160 | { |
175 | { |
161 | "a" : [ |
176 | "a" : [ |
… | |
… | |
184 | space at those places. |
199 | space at those places. |
185 | |
200 | |
186 | 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 |
187 | likely combine this setting with C<space_after>. |
202 | likely combine this setting with C<space_after>. |
188 | |
203 | |
|
|
204 | Example, space_before enabled, space_after and indent disabled: |
|
|
205 | |
|
|
206 | {"key" :"value"} |
|
|
207 | |
189 | =item $json = $json->space_after ([$enable]) |
208 | =item $json = $json->space_after ([$enable]) |
190 | |
209 | |
191 | 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 |
192 | 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 |
193 | 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 |
… | |
… | |
196 | 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 |
197 | space at those places. |
216 | space at those places. |
198 | |
217 | |
199 | This setting has no effect when decoding JSON strings. |
218 | This setting has no effect when decoding JSON strings. |
200 | |
219 | |
|
|
220 | Example, space_before and indent disabled, space_after enabled: |
|
|
221 | |
|
|
222 | {"key": "value"} |
|
|
223 | |
201 | =item $json = $json->canonical ([$enable]) |
224 | =item $json = $json->canonical ([$enable]) |
202 | |
225 | |
203 | 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 |
204 | by sorting their keys. This is adding a comparatively high overhead. |
227 | by sorting their keys. This is adding a comparatively high overhead. |
205 | |
228 | |
… | |
… | |
223 | |
246 | |
224 | 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 |
225 | 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 |
226 | 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 |
227 | 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!" |
228 | |
257 | |
229 | =item $json = $json->shrink ([$enable]) |
258 | =item $json = $json->shrink ([$enable]) |
230 | |
259 | |
231 | Perl usually over-allocates memory a bit when allocating space for |
260 | Perl usually over-allocates memory a bit when allocating space for |
232 | strings. This flag optionally resizes strings generated by either |
261 | strings. This flag optionally resizes strings generated by either |
… | |
… | |
283 | =over 4 |
312 | =over 4 |
284 | |
313 | |
285 | =item object |
314 | =item object |
286 | |
315 | |
287 | A JSON object becomes a reference to a hash in Perl. No ordering of object |
316 | A JSON object becomes a reference to a hash in Perl. No ordering of object |
288 | keys is preserved. |
317 | keys is preserved (JSON does not preserver object key ordering itself). |
289 | |
318 | |
290 | =item array |
319 | =item array |
291 | |
320 | |
292 | A JSON array becomes a reference to an array in Perl. |
321 | A JSON array becomes a reference to an array in Perl. |
293 | |
322 | |
… | |
… | |
329 | =item hash references |
358 | =item hash references |
330 | |
359 | |
331 | Perl hash references become JSON objects. As there is no inherent ordering |
360 | Perl hash references become JSON objects. As there is no inherent ordering |
332 | in hash keys, they will usually be encoded in a pseudo-random order that |
361 | in hash keys, they will usually be encoded in a pseudo-random order that |
333 | can change between runs of the same program but stays generally the same |
362 | can change between runs of the same program but stays generally the same |
334 | within the single run of a program. JSON::XS can optionally sort the hash |
363 | within a single run of a program. JSON::XS can optionally sort the hash |
335 | keys (determined by the I<canonical> flag), so the same datastructure |
364 | keys (determined by the I<canonical> flag), so the same datastructure |
336 | will serialise to the same JSON text (given same settings and version of |
365 | will serialise to the same JSON text (given same settings and version of |
337 | JSON::XS), but this incurs a runtime overhead. |
366 | JSON::XS), but this incurs a runtime overhead. |
338 | |
367 | |
339 | =item array references |
368 | =item array references |
… | |
… | |
378 | $x += 0; # numify it, ensuring it will be dumped as a number |
407 | $x += 0; # numify it, ensuring it will be dumped as a number |
379 | $x *= 1; # same thing, the choise is yours. |
408 | $x *= 1; # same thing, the choise is yours. |
380 | |
409 | |
381 | You can not currently output JSON booleans or force the type in other, |
410 | You can not currently output JSON booleans or force the type in other, |
382 | less obscure, ways. Tell me if you need this capability. |
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. |
383 | |
416 | |
384 | =back |
417 | =back |
385 | |
418 | |
386 | =head1 COMPARISON |
419 | =head1 COMPARISON |
387 | |
420 | |
… | |
… | |
474 | 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 |
475 | 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 |
476 | 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 |
477 | system. |
510 | system. |
478 | |
511 | |
479 | 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 |
480 | string, showing the number of encodes/decodes per second (JSON::XS is |
513 | string (83 bytes), showing the number of encodes/decodes per second |
481 | 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 |
482 | pretty-printing and hashkey sorting enabled). |
515 | interface with pretty-printing and hashkey sorting enabled). Higher is |
|
|
516 | better: |
483 | |
517 | |
484 | module | encode | decode | |
518 | module | encode | decode | |
485 | -----------|------------|------------| |
519 | -----------|------------|------------| |
486 | JSON | 14006 | 6820 | |
520 | JSON | 14006 | 6820 | |
487 | JSON::DWIW | 200937 | 120386 | |
521 | JSON::DWIW | 200937 | 120386 | |
… | |
… | |
492 | -----------+------------+------------+ |
526 | -----------+------------+------------+ |
493 | |
527 | |
494 | 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 |
495 | times faster than JSON, even with pretty-printing and key sorting. |
529 | times faster than JSON, even with pretty-printing and key sorting. |
496 | |
530 | |
497 | Using a longer test string (roughly 8KB, generated from Yahoo! Locals |
531 | Using a longer test string (roughly 18KB, generated from Yahoo! Locals |
498 | search API (http://nanoref.com/yahooapis/mgPdGg): |
532 | search API (http://nanoref.com/yahooapis/mgPdGg): |
499 | |
533 | |
500 | module | encode | decode | |
534 | module | encode | decode | |
501 | -----------|------------|------------| |
535 | -----------|------------|------------| |
502 | JSON | 673 | 38 | |
536 | JSON | 673 | 38 | |
… | |
… | |
508 | -----------+------------+------------+ |
542 | -----------+------------+------------+ |
509 | |
543 | |
510 | 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 |
511 | every other module in the decoding case. |
545 | every other module in the decoding case. |
512 | |
546 | |
513 | Last example is an almost 8MB large hash with many large binary values |
547 | On large strings containing lots of unicode characters, some modules |
514 | (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. |
515 | |
559 | |
516 | =head1 BUGS |
560 | =head1 BUGS |
517 | |
561 | |
518 | 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 |
519 | 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 |