… | |
… | |
19 | |
19 | |
20 | $coder = JSON::XS->new->ascii->pretty->allow_nonref; |
20 | $coder = JSON::XS->new->ascii->pretty->allow_nonref; |
21 | $pretty_printed_unencoded = $coder->encode ($perl_scalar); |
21 | $pretty_printed_unencoded = $coder->encode ($perl_scalar); |
22 | $perl_scalar = $coder->decode ($unicode_json_text); |
22 | $perl_scalar = $coder->decode ($unicode_json_text); |
23 | |
23 | |
|
|
24 | # Note that JSON version 2.0 and above will automatically use JSON::XS |
|
|
25 | # if available, at virtually no speed overhead either, so you should |
|
|
26 | # be able to just: |
|
|
27 | |
|
|
28 | use JSON; |
|
|
29 | |
|
|
30 | # and do the same things, except that you have a pure-perl fallback now. |
|
|
31 | |
24 | =head1 DESCRIPTION |
32 | =head1 DESCRIPTION |
25 | |
33 | |
26 | This module converts Perl data structures to JSON and vice versa. Its |
34 | This module converts Perl data structures to JSON and vice versa. Its |
27 | primary goal is to be I<correct> and its secondary goal is to be |
35 | primary goal is to be I<correct> and its secondary goal is to be |
28 | I<fast>. To reach the latter goal it was written in C. |
36 | I<fast>. To reach the latter goal it was written in C. |
|
|
37 | |
|
|
38 | Beginning with version 2.0 of the JSON module, when both JSON and |
|
|
39 | JSON::XS are installed, then JSON will fall back on JSON::XS (this can be |
|
|
40 | overriden) with no overhead due to emulation (by inheritign constructor |
|
|
41 | and methods). If JSON::XS is not available, it will fall back to the |
|
|
42 | compatible JSON::PP module as backend, so using JSON instead of JSON::XS |
|
|
43 | gives you a portable JSON API that can be fast when you need and doesn't |
|
|
44 | require a C compiler when that is a problem. |
29 | |
45 | |
30 | As this is the n-th-something JSON module on CPAN, what was the reason |
46 | As this is the n-th-something JSON module on CPAN, what was the reason |
31 | to write yet another JSON module? While it seems there are many JSON |
47 | to write yet another JSON module? While it seems there are many JSON |
32 | modules, none of them correctly handle all corner cases, and in most cases |
48 | modules, none of them correctly handle all corner cases, and in most cases |
33 | their maintainers are unresponsive, gone missing, or not listening to bug |
49 | their maintainers are unresponsive, gone missing, or not listening to bug |
… | |
… | |
84 | |
100 | |
85 | package JSON::XS; |
101 | package JSON::XS; |
86 | |
102 | |
87 | use strict; |
103 | use strict; |
88 | |
104 | |
89 | our $VERSION = '1.53'; |
105 | our $VERSION = '2.0'; |
90 | our @ISA = qw(Exporter); |
106 | our @ISA = qw(Exporter); |
91 | |
107 | |
92 | our @EXPORT = qw(to_json from_json); |
108 | our @EXPORT = qw(to_json from_json); |
93 | |
109 | |
94 | use Exporter; |
110 | use Exporter; |
… | |
… | |
201 | |
217 | |
202 | my $json = JSON::XS->new->utf8->space_after->encode ({a => [1,2]}) |
218 | my $json = JSON::XS->new->utf8->space_after->encode ({a => [1,2]}) |
203 | => {"a": [1, 2]} |
219 | => {"a": [1, 2]} |
204 | |
220 | |
205 | =item $json = $json->ascii ([$enable]) |
221 | =item $json = $json->ascii ([$enable]) |
|
|
222 | |
|
|
223 | =item $enabled = $json->get_ascii |
206 | |
224 | |
207 | If C<$enable> is true (or missing), then the C<encode> method will not |
225 | If C<$enable> is true (or missing), then the C<encode> method will not |
208 | generate characters outside the code range C<0..127> (which is ASCII). Any |
226 | generate characters outside the code range C<0..127> (which is ASCII). Any |
209 | Unicode characters outside that range will be escaped using either a |
227 | Unicode characters outside that range will be escaped using either a |
210 | single \uXXXX (BMP characters) or a double \uHHHH\uLLLLL escape sequence, |
228 | single \uXXXX (BMP characters) or a double \uHHHH\uLLLLL escape sequence, |
… | |
… | |
223 | JSON::XS->new->ascii (1)->encode ([chr 0x10401]) |
241 | JSON::XS->new->ascii (1)->encode ([chr 0x10401]) |
224 | => ["\ud801\udc01"] |
242 | => ["\ud801\udc01"] |
225 | |
243 | |
226 | =item $json = $json->latin1 ([$enable]) |
244 | =item $json = $json->latin1 ([$enable]) |
227 | |
245 | |
|
|
246 | =item $enabled = $json->get_latin1 |
|
|
247 | |
228 | If C<$enable> is true (or missing), then the C<encode> method will encode |
248 | If C<$enable> is true (or missing), then the C<encode> method will encode |
229 | the resulting JSON text as latin1 (or iso-8859-1), escaping any characters |
249 | the resulting JSON text as latin1 (or iso-8859-1), escaping any characters |
230 | outside the code range C<0..255>. The resulting string can be treated as a |
250 | outside the code range C<0..255>. The resulting string can be treated as a |
231 | latin1-encoded JSON text or a native Unicode string. The C<decode> method |
251 | latin1-encoded JSON text or a native Unicode string. The C<decode> method |
232 | will not be affected in any way by this flag, as C<decode> by default |
252 | will not be affected in any way by this flag, as C<decode> by default |
… | |
… | |
245 | |
265 | |
246 | JSON::XS->new->latin1->encode (["\x{89}\x{abc}"] |
266 | JSON::XS->new->latin1->encode (["\x{89}\x{abc}"] |
247 | => ["\x{89}\\u0abc"] # (perl syntax, U+abc escaped, U+89 not) |
267 | => ["\x{89}\\u0abc"] # (perl syntax, U+abc escaped, U+89 not) |
248 | |
268 | |
249 | =item $json = $json->utf8 ([$enable]) |
269 | =item $json = $json->utf8 ([$enable]) |
|
|
270 | |
|
|
271 | =item $enabled = $json->get_utf8 |
250 | |
272 | |
251 | If C<$enable> is true (or missing), then the C<encode> method will encode |
273 | If C<$enable> is true (or missing), then the C<encode> method will encode |
252 | the JSON result into UTF-8, as required by many protocols, while the |
274 | the JSON result into UTF-8, as required by many protocols, while the |
253 | C<decode> method expects to be handled an UTF-8-encoded string. Please |
275 | C<decode> method expects to be handled an UTF-8-encoded string. Please |
254 | note that UTF-8-encoded strings do not contain any characters outside the |
276 | note that UTF-8-encoded strings do not contain any characters outside the |
… | |
… | |
288 | ] |
310 | ] |
289 | } |
311 | } |
290 | |
312 | |
291 | =item $json = $json->indent ([$enable]) |
313 | =item $json = $json->indent ([$enable]) |
292 | |
314 | |
|
|
315 | =item $enabled = $json->get_indent |
|
|
316 | |
293 | If C<$enable> is true (or missing), then the C<encode> method will use a multiline |
317 | If C<$enable> is true (or missing), then the C<encode> method will use a multiline |
294 | format as output, putting every array member or object/hash key-value pair |
318 | format as output, putting every array member or object/hash key-value pair |
295 | into its own line, indenting them properly. |
319 | into its own line, indenting them properly. |
296 | |
320 | |
297 | If C<$enable> is false, no newlines or indenting will be produced, and the |
321 | If C<$enable> is false, no newlines or indenting will be produced, and the |
… | |
… | |
299 | |
323 | |
300 | This setting has no effect when decoding JSON texts. |
324 | This setting has no effect when decoding JSON texts. |
301 | |
325 | |
302 | =item $json = $json->space_before ([$enable]) |
326 | =item $json = $json->space_before ([$enable]) |
303 | |
327 | |
|
|
328 | =item $enabled = $json->get_space_before |
|
|
329 | |
304 | If C<$enable> is true (or missing), then the C<encode> method will add an extra |
330 | If C<$enable> is true (or missing), then the C<encode> method will add an extra |
305 | optional space before the C<:> separating keys from values in JSON objects. |
331 | optional space before the C<:> separating keys from values in JSON objects. |
306 | |
332 | |
307 | If C<$enable> is false, then the C<encode> method will not add any extra |
333 | If C<$enable> is false, then the C<encode> method will not add any extra |
308 | space at those places. |
334 | space at those places. |
… | |
… | |
313 | Example, space_before enabled, space_after and indent disabled: |
339 | Example, space_before enabled, space_after and indent disabled: |
314 | |
340 | |
315 | {"key" :"value"} |
341 | {"key" :"value"} |
316 | |
342 | |
317 | =item $json = $json->space_after ([$enable]) |
343 | =item $json = $json->space_after ([$enable]) |
|
|
344 | |
|
|
345 | =item $enabled = $json->get_space_after |
318 | |
346 | |
319 | If C<$enable> is true (or missing), then the C<encode> method will add an extra |
347 | If C<$enable> is true (or missing), then the C<encode> method will add an extra |
320 | optional space after the C<:> separating keys from values in JSON objects |
348 | optional space after the C<:> separating keys from values in JSON objects |
321 | and extra whitespace after the C<,> separating key-value pairs and array |
349 | and extra whitespace after the C<,> separating key-value pairs and array |
322 | members. |
350 | members. |
… | |
… | |
329 | Example, space_before and indent disabled, space_after enabled: |
357 | Example, space_before and indent disabled, space_after enabled: |
330 | |
358 | |
331 | {"key": "value"} |
359 | {"key": "value"} |
332 | |
360 | |
333 | =item $json = $json->relaxed ([$enable]) |
361 | =item $json = $json->relaxed ([$enable]) |
|
|
362 | |
|
|
363 | =item $enabled = $json->get_relaxed |
334 | |
364 | |
335 | If C<$enable> is true (or missing), then C<decode> will accept some |
365 | If C<$enable> is true (or missing), then C<decode> will accept some |
336 | extensions to normal JSON syntax (see below). C<encode> will not be |
366 | extensions to normal JSON syntax (see below). C<encode> will not be |
337 | affected in anyway. I<Be aware that this option makes you accept invalid |
367 | affected in anyway. I<Be aware that this option makes you accept invalid |
338 | JSON texts as if they were valid!>. I suggest only to use this option to |
368 | JSON texts as if they were valid!>. I suggest only to use this option to |
… | |
… | |
375 | |
405 | |
376 | =back |
406 | =back |
377 | |
407 | |
378 | =item $json = $json->canonical ([$enable]) |
408 | =item $json = $json->canonical ([$enable]) |
379 | |
409 | |
|
|
410 | =item $enabled = $json->get_canonical |
|
|
411 | |
380 | If C<$enable> is true (or missing), then the C<encode> method will output JSON objects |
412 | If C<$enable> is true (or missing), then the C<encode> method will output JSON objects |
381 | by sorting their keys. This is adding a comparatively high overhead. |
413 | by sorting their keys. This is adding a comparatively high overhead. |
382 | |
414 | |
383 | If C<$enable> is false, then the C<encode> method will output key-value |
415 | If C<$enable> is false, then the C<encode> method will output key-value |
384 | pairs in the order Perl stores them (which will likely change between runs |
416 | pairs in the order Perl stores them (which will likely change between runs |
… | |
… | |
391 | |
423 | |
392 | This setting has no effect when decoding JSON texts. |
424 | This setting has no effect when decoding JSON texts. |
393 | |
425 | |
394 | =item $json = $json->allow_nonref ([$enable]) |
426 | =item $json = $json->allow_nonref ([$enable]) |
395 | |
427 | |
|
|
428 | =item $enabled = $json->get_allow_nonref |
|
|
429 | |
396 | If C<$enable> is true (or missing), then the C<encode> method can convert a |
430 | If C<$enable> is true (or missing), then the C<encode> method can convert a |
397 | non-reference into its corresponding string, number or null JSON value, |
431 | non-reference into its corresponding string, number or null JSON value, |
398 | which is an extension to RFC4627. Likewise, C<decode> will accept those JSON |
432 | which is an extension to RFC4627. Likewise, C<decode> will accept those JSON |
399 | values instead of croaking. |
433 | values instead of croaking. |
400 | |
434 | |
… | |
… | |
409 | JSON::XS->new->allow_nonref->encode ("Hello, World!") |
443 | JSON::XS->new->allow_nonref->encode ("Hello, World!") |
410 | => "Hello, World!" |
444 | => "Hello, World!" |
411 | |
445 | |
412 | =item $json = $json->allow_blessed ([$enable]) |
446 | =item $json = $json->allow_blessed ([$enable]) |
413 | |
447 | |
|
|
448 | =item $enabled = $json->get_allow_blessed |
|
|
449 | |
414 | If C<$enable> is true (or missing), then the C<encode> method will not |
450 | If C<$enable> is true (or missing), then the C<encode> method will not |
415 | barf when it encounters a blessed reference. Instead, the value of the |
451 | barf when it encounters a blessed reference. Instead, the value of the |
416 | B<convert_blessed> option will decide whether C<null> (C<convert_blessed> |
452 | B<convert_blessed> option will decide whether C<null> (C<convert_blessed> |
417 | disabled or no C<to_json> method found) or a representation of the |
453 | disabled or no C<TO_JSON> method found) or a representation of the |
418 | object (C<convert_blessed> enabled and C<to_json> method found) is being |
454 | object (C<convert_blessed> enabled and C<TO_JSON> method found) is being |
419 | encoded. Has no effect on C<decode>. |
455 | encoded. Has no effect on C<decode>. |
420 | |
456 | |
421 | If C<$enable> is false (the default), then C<encode> will throw an |
457 | If C<$enable> is false (the default), then C<encode> will throw an |
422 | exception when it encounters a blessed object. |
458 | exception when it encounters a blessed object. |
423 | |
459 | |
424 | =item $json = $json->convert_blessed ([$enable]) |
460 | =item $json = $json->convert_blessed ([$enable]) |
|
|
461 | |
|
|
462 | =item $enabled = $json->get_convert_blessed |
425 | |
463 | |
426 | If C<$enable> is true (or missing), then C<encode>, upon encountering a |
464 | If C<$enable> is true (or missing), then C<encode>, upon encountering a |
427 | blessed object, will check for the availability of the C<TO_JSON> method |
465 | blessed object, will check for the availability of the C<TO_JSON> method |
428 | on the object's class. If found, it will be called in scalar context |
466 | on the object's class. If found, it will be called in scalar context |
429 | and the resulting scalar will be encoded instead of the object. If no |
467 | and the resulting scalar will be encoded instead of the object. If no |
… | |
… | |
520 | |
558 | |
521 | { __widget__ => $self->{id} } |
559 | { __widget__ => $self->{id} } |
522 | } |
560 | } |
523 | |
561 | |
524 | =item $json = $json->shrink ([$enable]) |
562 | =item $json = $json->shrink ([$enable]) |
|
|
563 | |
|
|
564 | =item $enabled = $json->get_shrink |
525 | |
565 | |
526 | Perl usually over-allocates memory a bit when allocating space for |
566 | Perl usually over-allocates memory a bit when allocating space for |
527 | strings. This flag optionally resizes strings generated by either |
567 | strings. This flag optionally resizes strings generated by either |
528 | C<encode> or C<decode> to their minimum size possible. This can save |
568 | C<encode> or C<decode> to their minimum size possible. This can save |
529 | memory when your JSON texts are either very very long or you have many |
569 | memory when your JSON texts are either very very long or you have many |
… | |
… | |
547 | strings that look like integers or floats into integers or floats |
587 | strings that look like integers or floats into integers or floats |
548 | internally (there is no difference on the Perl level), saving space. |
588 | internally (there is no difference on the Perl level), saving space. |
549 | |
589 | |
550 | =item $json = $json->max_depth ([$maximum_nesting_depth]) |
590 | =item $json = $json->max_depth ([$maximum_nesting_depth]) |
551 | |
591 | |
|
|
592 | =item $max_depth = $json->get_max_depth |
|
|
593 | |
552 | Sets the maximum nesting level (default C<512>) accepted while encoding |
594 | Sets the maximum nesting level (default C<512>) accepted while encoding |
553 | or decoding. If the JSON text or Perl data structure has an equal or |
595 | or decoding. If the JSON text or Perl data structure has an equal or |
554 | higher nesting level then this limit, then the encoder and decoder will |
596 | higher nesting level then this limit, then the encoder and decoder will |
555 | stop and croak at that point. |
597 | stop and croak at that point. |
556 | |
598 | |
… | |
… | |
567 | used, which is rarely useful. |
609 | used, which is rarely useful. |
568 | |
610 | |
569 | See SECURITY CONSIDERATIONS, below, for more info on why this is useful. |
611 | See SECURITY CONSIDERATIONS, below, for more info on why this is useful. |
570 | |
612 | |
571 | =item $json = $json->max_size ([$maximum_string_size]) |
613 | =item $json = $json->max_size ([$maximum_string_size]) |
|
|
614 | |
|
|
615 | =item $max_size = $json->get_max_size |
572 | |
616 | |
573 | Set the maximum length a JSON text may have (in bytes) where decoding is |
617 | Set the maximum length a JSON text may have (in bytes) where decoding is |
574 | being attempted. The default is C<0>, meaning no limit. When C<decode> |
618 | being attempted. The default is C<0>, meaning no limit. When C<decode> |
575 | is called on a string longer then this number of characters it will not |
619 | is called on a string longer then this number of characters it will not |
576 | attempt to decode the string but throw an exception. This setting has no |
620 | attempt to decode the string but throw an exception. This setting has no |
… | |
… | |
892 | with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables |
936 | with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables |
893 | shrink). Higher is better: |
937 | shrink). Higher is better: |
894 | |
938 | |
895 | module | encode | decode | |
939 | module | encode | decode | |
896 | -----------|------------|------------| |
940 | -----------|------------|------------| |
897 | JSON | 4990.842 | 4088.813 | |
941 | JSON 1.x | 4990.842 | 4088.813 | |
898 | JSON::DWIW | 51653.990 | 71575.154 | |
942 | JSON::DWIW | 51653.990 | 71575.154 | |
899 | JSON::PC | 65948.176 | 74631.744 | |
943 | JSON::PC | 65948.176 | 74631.744 | |
900 | JSON::PP | 8931.652 | 3817.168 | |
944 | JSON::PP | 8931.652 | 3817.168 | |
901 | JSON::Syck | 24877.248 | 27776.848 | |
945 | JSON::Syck | 24877.248 | 27776.848 | |
902 | JSON::XS | 388361.481 | 227951.304 | |
946 | JSON::XS | 388361.481 | 227951.304 | |
… | |
… | |
913 | Using a longer test string (roughly 18KB, generated from Yahoo! Locals |
957 | Using a longer test string (roughly 18KB, generated from Yahoo! Locals |
914 | search API (http://nanoref.com/yahooapis/mgPdGg): |
958 | search API (http://nanoref.com/yahooapis/mgPdGg): |
915 | |
959 | |
916 | module | encode | decode | |
960 | module | encode | decode | |
917 | -----------|------------|------------| |
961 | -----------|------------|------------| |
918 | JSON | 55.260 | 34.971 | |
962 | JSON 1.x | 55.260 | 34.971 | |
919 | JSON::DWIW | 825.228 | 1082.513 | |
963 | JSON::DWIW | 825.228 | 1082.513 | |
920 | JSON::PC | 3571.444 | 2394.829 | |
964 | JSON::PC | 3571.444 | 2394.829 | |
921 | JSON::PP | 210.987 | 32.574 | |
965 | JSON::PP | 210.987 | 32.574 | |
922 | JSON::Syck | 552.551 | 787.544 | |
966 | JSON::Syck | 552.551 | 787.544 | |
923 | JSON::XS | 5780.463 | 4854.519 | |
967 | JSON::XS | 5780.463 | 4854.519 | |