… | |
… | |
10 | use JSON::XS; |
10 | use JSON::XS; |
11 | |
11 | |
12 | # exported functions, they croak on error |
12 | # exported functions, they croak on error |
13 | # and expect/generate UTF-8 |
13 | # and expect/generate UTF-8 |
14 | |
14 | |
15 | $utf8_encoded_json_text = to_json $perl_hash_or_arrayref; |
15 | $utf8_encoded_json_text = encode_json $perl_hash_or_arrayref; |
16 | $perl_hash_or_arrayref = from_json $utf8_encoded_json_text; |
16 | $perl_hash_or_arrayref = decode_json $utf8_encoded_json_text; |
17 | |
17 | |
18 | # OO-interface |
18 | # OO-interface |
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.01'; |
90 | our @ISA = qw(Exporter); |
106 | our @ISA = qw(Exporter); |
91 | |
107 | |
92 | our @EXPORT = qw(to_json from_json); |
108 | our @EXPORT = qw(encode_json decode_json to_json from_json); |
|
|
109 | |
|
|
110 | sub to_json($) { |
|
|
111 | require Carp; |
|
|
112 | Carp::croak ("JSON::XS::to_json has been renamed to encode_json, either downgrade to pre-2.0 versions of JSON::XS or rename the call"); |
|
|
113 | } |
|
|
114 | |
|
|
115 | sub from_json($) { |
|
|
116 | require Carp; |
|
|
117 | Carp::croak ("JSON::XS::from_json has been renamed to decode_json, either downgrade to pre-2.0 versions of JSON::XS or rename the call"); |
|
|
118 | } |
93 | |
119 | |
94 | use Exporter; |
120 | use Exporter; |
95 | use XSLoader; |
121 | use XSLoader; |
96 | |
122 | |
97 | =head1 FUNCTIONAL INTERFACE |
123 | =head1 FUNCTIONAL INTERFACE |
… | |
… | |
99 | The following convenience methods are provided by this module. They are |
125 | The following convenience methods are provided by this module. They are |
100 | exported by default: |
126 | exported by default: |
101 | |
127 | |
102 | =over 4 |
128 | =over 4 |
103 | |
129 | |
104 | =item $json_text = to_json $perl_scalar |
130 | =item $json_text = encode_json $perl_scalar |
105 | |
131 | |
106 | Converts the given Perl data structure to a UTF-8 encoded, binary string |
132 | Converts the given Perl data structure to a UTF-8 encoded, binary string |
107 | (that is, the string contains octets only). Croaks on error. |
133 | (that is, the string contains octets only). Croaks on error. |
108 | |
134 | |
109 | This function call is functionally identical to: |
135 | This function call is functionally identical to: |
110 | |
136 | |
111 | $json_text = JSON::XS->new->utf8->encode ($perl_scalar) |
137 | $json_text = JSON::XS->new->utf8->encode ($perl_scalar) |
112 | |
138 | |
113 | except being faster. |
139 | except being faster. |
114 | |
140 | |
115 | =item $perl_scalar = from_json $json_text |
141 | =item $perl_scalar = decode_json $json_text |
116 | |
142 | |
117 | The opposite of C<to_json>: expects an UTF-8 (binary) string and tries |
143 | The opposite of C<encode_json>: expects an UTF-8 (binary) string and tries |
118 | to parse that as an UTF-8 encoded JSON text, returning the resulting |
144 | to parse that as an UTF-8 encoded JSON text, returning the resulting |
119 | reference. Croaks on error. |
145 | reference. Croaks on error. |
120 | |
146 | |
121 | This function call is functionally identical to: |
147 | This function call is functionally identical to: |
122 | |
148 | |
… | |
… | |
201 | |
227 | |
202 | my $json = JSON::XS->new->utf8->space_after->encode ({a => [1,2]}) |
228 | my $json = JSON::XS->new->utf8->space_after->encode ({a => [1,2]}) |
203 | => {"a": [1, 2]} |
229 | => {"a": [1, 2]} |
204 | |
230 | |
205 | =item $json = $json->ascii ([$enable]) |
231 | =item $json = $json->ascii ([$enable]) |
|
|
232 | |
|
|
233 | =item $enabled = $json->get_ascii |
206 | |
234 | |
207 | If C<$enable> is true (or missing), then the C<encode> method will not |
235 | 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 |
236 | 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 |
237 | Unicode characters outside that range will be escaped using either a |
210 | single \uXXXX (BMP characters) or a double \uHHHH\uLLLLL escape sequence, |
238 | single \uXXXX (BMP characters) or a double \uHHHH\uLLLLL escape sequence, |
… | |
… | |
223 | JSON::XS->new->ascii (1)->encode ([chr 0x10401]) |
251 | JSON::XS->new->ascii (1)->encode ([chr 0x10401]) |
224 | => ["\ud801\udc01"] |
252 | => ["\ud801\udc01"] |
225 | |
253 | |
226 | =item $json = $json->latin1 ([$enable]) |
254 | =item $json = $json->latin1 ([$enable]) |
227 | |
255 | |
|
|
256 | =item $enabled = $json->get_latin1 |
|
|
257 | |
228 | If C<$enable> is true (or missing), then the C<encode> method will encode |
258 | 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 |
259 | 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 |
260 | 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 |
261 | 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 |
262 | will not be affected in any way by this flag, as C<decode> by default |
… | |
… | |
245 | |
275 | |
246 | JSON::XS->new->latin1->encode (["\x{89}\x{abc}"] |
276 | JSON::XS->new->latin1->encode (["\x{89}\x{abc}"] |
247 | => ["\x{89}\\u0abc"] # (perl syntax, U+abc escaped, U+89 not) |
277 | => ["\x{89}\\u0abc"] # (perl syntax, U+abc escaped, U+89 not) |
248 | |
278 | |
249 | =item $json = $json->utf8 ([$enable]) |
279 | =item $json = $json->utf8 ([$enable]) |
|
|
280 | |
|
|
281 | =item $enabled = $json->get_utf8 |
250 | |
282 | |
251 | If C<$enable> is true (or missing), then the C<encode> method will encode |
283 | 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 |
284 | 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 |
285 | 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 |
286 | note that UTF-8-encoded strings do not contain any characters outside the |
… | |
… | |
288 | ] |
320 | ] |
289 | } |
321 | } |
290 | |
322 | |
291 | =item $json = $json->indent ([$enable]) |
323 | =item $json = $json->indent ([$enable]) |
292 | |
324 | |
|
|
325 | =item $enabled = $json->get_indent |
|
|
326 | |
293 | If C<$enable> is true (or missing), then the C<encode> method will use a multiline |
327 | 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 |
328 | format as output, putting every array member or object/hash key-value pair |
295 | into its own line, indenting them properly. |
329 | into its own line, indenting them properly. |
296 | |
330 | |
297 | If C<$enable> is false, no newlines or indenting will be produced, and the |
331 | If C<$enable> is false, no newlines or indenting will be produced, and the |
… | |
… | |
299 | |
333 | |
300 | This setting has no effect when decoding JSON texts. |
334 | This setting has no effect when decoding JSON texts. |
301 | |
335 | |
302 | =item $json = $json->space_before ([$enable]) |
336 | =item $json = $json->space_before ([$enable]) |
303 | |
337 | |
|
|
338 | =item $enabled = $json->get_space_before |
|
|
339 | |
304 | If C<$enable> is true (or missing), then the C<encode> method will add an extra |
340 | 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. |
341 | optional space before the C<:> separating keys from values in JSON objects. |
306 | |
342 | |
307 | If C<$enable> is false, then the C<encode> method will not add any extra |
343 | If C<$enable> is false, then the C<encode> method will not add any extra |
308 | space at those places. |
344 | space at those places. |
… | |
… | |
313 | Example, space_before enabled, space_after and indent disabled: |
349 | Example, space_before enabled, space_after and indent disabled: |
314 | |
350 | |
315 | {"key" :"value"} |
351 | {"key" :"value"} |
316 | |
352 | |
317 | =item $json = $json->space_after ([$enable]) |
353 | =item $json = $json->space_after ([$enable]) |
|
|
354 | |
|
|
355 | =item $enabled = $json->get_space_after |
318 | |
356 | |
319 | If C<$enable> is true (or missing), then the C<encode> method will add an extra |
357 | 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 |
358 | 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 |
359 | and extra whitespace after the C<,> separating key-value pairs and array |
322 | members. |
360 | members. |
… | |
… | |
329 | Example, space_before and indent disabled, space_after enabled: |
367 | Example, space_before and indent disabled, space_after enabled: |
330 | |
368 | |
331 | {"key": "value"} |
369 | {"key": "value"} |
332 | |
370 | |
333 | =item $json = $json->relaxed ([$enable]) |
371 | =item $json = $json->relaxed ([$enable]) |
|
|
372 | |
|
|
373 | =item $enabled = $json->get_relaxed |
334 | |
374 | |
335 | If C<$enable> is true (or missing), then C<decode> will accept some |
375 | 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 |
376 | 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 |
377 | 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 |
378 | JSON texts as if they were valid!>. I suggest only to use this option to |
… | |
… | |
375 | |
415 | |
376 | =back |
416 | =back |
377 | |
417 | |
378 | =item $json = $json->canonical ([$enable]) |
418 | =item $json = $json->canonical ([$enable]) |
379 | |
419 | |
|
|
420 | =item $enabled = $json->get_canonical |
|
|
421 | |
380 | If C<$enable> is true (or missing), then the C<encode> method will output JSON objects |
422 | 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. |
423 | by sorting their keys. This is adding a comparatively high overhead. |
382 | |
424 | |
383 | If C<$enable> is false, then the C<encode> method will output key-value |
425 | 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 |
426 | pairs in the order Perl stores them (which will likely change between runs |
… | |
… | |
391 | |
433 | |
392 | This setting has no effect when decoding JSON texts. |
434 | This setting has no effect when decoding JSON texts. |
393 | |
435 | |
394 | =item $json = $json->allow_nonref ([$enable]) |
436 | =item $json = $json->allow_nonref ([$enable]) |
395 | |
437 | |
|
|
438 | =item $enabled = $json->get_allow_nonref |
|
|
439 | |
396 | If C<$enable> is true (or missing), then the C<encode> method can convert a |
440 | 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, |
441 | 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 |
442 | which is an extension to RFC4627. Likewise, C<decode> will accept those JSON |
399 | values instead of croaking. |
443 | values instead of croaking. |
400 | |
444 | |
… | |
… | |
409 | JSON::XS->new->allow_nonref->encode ("Hello, World!") |
453 | JSON::XS->new->allow_nonref->encode ("Hello, World!") |
410 | => "Hello, World!" |
454 | => "Hello, World!" |
411 | |
455 | |
412 | =item $json = $json->allow_blessed ([$enable]) |
456 | =item $json = $json->allow_blessed ([$enable]) |
413 | |
457 | |
|
|
458 | =item $enabled = $json->get_allow_blessed |
|
|
459 | |
414 | If C<$enable> is true (or missing), then the C<encode> method will not |
460 | 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 |
461 | 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> |
462 | 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 |
463 | 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 |
464 | object (C<convert_blessed> enabled and C<TO_JSON> method found) is being |
419 | encoded. Has no effect on C<decode>. |
465 | encoded. Has no effect on C<decode>. |
420 | |
466 | |
421 | If C<$enable> is false (the default), then C<encode> will throw an |
467 | If C<$enable> is false (the default), then C<encode> will throw an |
422 | exception when it encounters a blessed object. |
468 | exception when it encounters a blessed object. |
423 | |
469 | |
424 | =item $json = $json->convert_blessed ([$enable]) |
470 | =item $json = $json->convert_blessed ([$enable]) |
|
|
471 | |
|
|
472 | =item $enabled = $json->get_convert_blessed |
425 | |
473 | |
426 | If C<$enable> is true (or missing), then C<encode>, upon encountering a |
474 | 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 |
475 | 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 |
476 | 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 |
477 | and the resulting scalar will be encoded instead of the object. If no |
… | |
… | |
433 | The C<TO_JSON> method may safely call die if it wants. If C<TO_JSON> |
481 | The C<TO_JSON> method may safely call die if it wants. If C<TO_JSON> |
434 | returns other blessed objects, those will be handled in the same |
482 | returns other blessed objects, those will be handled in the same |
435 | way. C<TO_JSON> must take care of not causing an endless recursion cycle |
483 | way. C<TO_JSON> must take care of not causing an endless recursion cycle |
436 | (== crash) in this case. The name of C<TO_JSON> was chosen because other |
484 | (== crash) in this case. The name of C<TO_JSON> was chosen because other |
437 | methods called by the Perl core (== not by the user of the object) are |
485 | methods called by the Perl core (== not by the user of the object) are |
438 | usually in upper case letters and to avoid collisions with the C<to_json> |
486 | usually in upper case letters and to avoid collisions with any C<to_json> |
439 | function. |
487 | function or method. |
440 | |
488 | |
441 | This setting does not yet influence C<decode> in any way, but in the |
489 | This setting does not yet influence C<decode> in any way, but in the |
442 | future, global hooks might get installed that influence C<decode> and are |
490 | future, global hooks might get installed that influence C<decode> and are |
443 | enabled by this setting. |
491 | enabled by this setting. |
444 | |
492 | |
… | |
… | |
520 | |
568 | |
521 | { __widget__ => $self->{id} } |
569 | { __widget__ => $self->{id} } |
522 | } |
570 | } |
523 | |
571 | |
524 | =item $json = $json->shrink ([$enable]) |
572 | =item $json = $json->shrink ([$enable]) |
|
|
573 | |
|
|
574 | =item $enabled = $json->get_shrink |
525 | |
575 | |
526 | Perl usually over-allocates memory a bit when allocating space for |
576 | Perl usually over-allocates memory a bit when allocating space for |
527 | strings. This flag optionally resizes strings generated by either |
577 | strings. This flag optionally resizes strings generated by either |
528 | C<encode> or C<decode> to their minimum size possible. This can save |
578 | 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 |
579 | 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 |
597 | strings that look like integers or floats into integers or floats |
548 | internally (there is no difference on the Perl level), saving space. |
598 | internally (there is no difference on the Perl level), saving space. |
549 | |
599 | |
550 | =item $json = $json->max_depth ([$maximum_nesting_depth]) |
600 | =item $json = $json->max_depth ([$maximum_nesting_depth]) |
551 | |
601 | |
|
|
602 | =item $max_depth = $json->get_max_depth |
|
|
603 | |
552 | Sets the maximum nesting level (default C<512>) accepted while encoding |
604 | 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 |
605 | 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 |
606 | higher nesting level then this limit, then the encoder and decoder will |
555 | stop and croak at that point. |
607 | stop and croak at that point. |
556 | |
608 | |
… | |
… | |
567 | used, which is rarely useful. |
619 | used, which is rarely useful. |
568 | |
620 | |
569 | See SECURITY CONSIDERATIONS, below, for more info on why this is useful. |
621 | See SECURITY CONSIDERATIONS, below, for more info on why this is useful. |
570 | |
622 | |
571 | =item $json = $json->max_size ([$maximum_string_size]) |
623 | =item $json = $json->max_size ([$maximum_string_size]) |
|
|
624 | |
|
|
625 | =item $max_size = $json->get_max_size |
572 | |
626 | |
573 | Set the maximum length a JSON text may have (in bytes) where decoding is |
627 | 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> |
628 | 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 |
629 | 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 |
630 | attempt to decode the string but throw an exception. This setting has no |
… | |
… | |
711 | Other unblessed references are generally not allowed and will cause an |
765 | Other unblessed references are generally not allowed and will cause an |
712 | exception to be thrown, except for references to the integers C<0> and |
766 | exception to be thrown, except for references to the integers C<0> and |
713 | C<1>, which get turned into C<false> and C<true> atoms in JSON. You can |
767 | C<1>, which get turned into C<false> and C<true> atoms in JSON. You can |
714 | also use C<JSON::XS::false> and C<JSON::XS::true> to improve readability. |
768 | also use C<JSON::XS::false> and C<JSON::XS::true> to improve readability. |
715 | |
769 | |
716 | to_json [\0,JSON::XS::true] # yields [false,true] |
770 | encode_json [\0,JSON::XS::true] # yields [false,true] |
717 | |
771 | |
718 | =item JSON::XS::true, JSON::XS::false |
772 | =item JSON::XS::true, JSON::XS::false |
719 | |
773 | |
720 | These special values become JSON true and JSON false values, |
774 | These special values become JSON true and JSON false values, |
721 | respectively. You can also use C<\1> and C<\0> directly if you want. |
775 | respectively. You can also use C<\1> and C<\0> directly if you want. |
… | |
… | |
732 | difficult objects to encode: JSON::XS will encode undefined scalars as |
786 | difficult objects to encode: JSON::XS will encode undefined scalars as |
733 | JSON null value, scalars that have last been used in a string context |
787 | JSON null value, scalars that have last been used in a string context |
734 | before encoding as JSON strings and anything else as number value: |
788 | before encoding as JSON strings and anything else as number value: |
735 | |
789 | |
736 | # dump as number |
790 | # dump as number |
737 | to_json [2] # yields [2] |
791 | encode_json [2] # yields [2] |
738 | to_json [-3.0e17] # yields [-3e+17] |
792 | encode_json [-3.0e17] # yields [-3e+17] |
739 | my $value = 5; to_json [$value] # yields [5] |
793 | my $value = 5; encode_json [$value] # yields [5] |
740 | |
794 | |
741 | # used as string, so dump as string |
795 | # used as string, so dump as string |
742 | print $value; |
796 | print $value; |
743 | to_json [$value] # yields ["5"] |
797 | encode_json [$value] # yields ["5"] |
744 | |
798 | |
745 | # undef becomes null |
799 | # undef becomes null |
746 | to_json [undef] # yields [null] |
800 | encode_json [undef] # yields [null] |
747 | |
801 | |
748 | You can force the type to be a JSON string by stringifying it: |
802 | You can force the type to be a JSON string by stringifying it: |
749 | |
803 | |
750 | my $x = 3.1; # some variable containing a number |
804 | my $x = 3.1; # some variable containing a number |
751 | "$x"; # stringified |
805 | "$x"; # stringified |
… | |
… | |
851 | =back |
905 | =back |
852 | |
906 | |
853 | |
907 | |
854 | =head2 JSON and YAML |
908 | =head2 JSON and YAML |
855 | |
909 | |
856 | You often hear that JSON is a subset (or a close subset) of YAML. This is, |
910 | You often hear that JSON is a subset of YAML. This is, however, a mass |
857 | however, a mass hysteria and very far from the truth. In general, there is |
911 | hysteria(*) and very far from the truth. In general, there is no way to |
858 | no way to configure JSON::XS to output a data structure as valid YAML. |
912 | configure JSON::XS to output a data structure as valid YAML that works for |
|
|
913 | all cases. |
859 | |
914 | |
860 | If you really must use JSON::XS to generate YAML, you should use this |
915 | If you really must use JSON::XS to generate YAML, you should use this |
861 | algorithm (subject to change in future versions): |
916 | algorithm (subject to change in future versions): |
862 | |
917 | |
863 | my $to_yaml = JSON::XS->new->utf8->space_after (1); |
918 | my $to_yaml = JSON::XS->new->utf8->space_after (1); |
864 | my $yaml = $to_yaml->encode ($ref) . "\n"; |
919 | my $yaml = $to_yaml->encode ($ref) . "\n"; |
865 | |
920 | |
866 | This will usually generate JSON texts that also parse as valid |
921 | This will usually generate JSON texts that also parse as valid |
867 | YAML. Please note that YAML has hardcoded limits on (simple) object key |
922 | YAML. Please note that YAML has hardcoded limits on (simple) object key |
868 | lengths that JSON doesn't have, so you should make sure that your hash |
923 | lengths that JSON doesn't have and also has different and incompatible |
|
|
924 | unicode handling, so you should make sure that your hash keys are |
869 | keys are noticeably shorter than the 1024 characters YAML allows. |
925 | noticeably shorter than the 1024 "stream characters" YAML allows and that |
|
|
926 | you do not have codepoints with values outside the Unicode BMP (basic |
|
|
927 | multilingual page). YAML also does not allow C<\/> sequences in strings |
|
|
928 | (which JSON::XS does not I<currently> generate). |
870 | |
929 | |
871 | There might be other incompatibilities that I am not aware of. In general |
930 | There might be other incompatibilities that I am not aware of. In general |
872 | you should not try to generate YAML with a JSON generator or vice versa, |
931 | you should not try to generate YAML with a JSON generator or vice versa, |
873 | or try to parse JSON with a YAML parser or vice versa: chances are high |
932 | or try to parse JSON with a YAML parser or vice versa: chances are high |
874 | that you will run into severe interoperability problems. |
933 | that you will run into severe interoperability problems when you least |
|
|
934 | expect it. |
|
|
935 | |
|
|
936 | =over 4 |
|
|
937 | |
|
|
938 | =item (*) |
|
|
939 | |
|
|
940 | This is spread actively by the YAML team, however. For many years now they |
|
|
941 | claim YAML were a superset of JSON, even when proven otherwise. |
|
|
942 | |
|
|
943 | Even the author of this manpage was at some point accused of providing |
|
|
944 | "incorrect" information, despite the evidence presented (claims ranged |
|
|
945 | from "your documentation contains inaccurate and negative statements about |
|
|
946 | YAML" (the only negative comment is this footnote, and it didn't exist |
|
|
947 | back then; the question on which claims were inaccurate was never answered |
|
|
948 | etc.) to "the YAML spec is not up-to-date" (the *real* and suppsedly |
|
|
949 | JSON-compatible spec is apparently not currently publicly available) |
|
|
950 | to actual requests to replace this section by *incorrect* information, |
|
|
951 | suppressing information about the real problem). |
|
|
952 | |
|
|
953 | So whenever you are told that YAML was a superset of JSON, first check |
|
|
954 | wether it is really true (it might be when you check it, but it cetrainly |
|
|
955 | is not true when this was written). I would much prefer if the YAML team |
|
|
956 | would spent their time on actually making JSON compatibility a truth |
|
|
957 | (JSON, after all, has a very small and simple specification) instead of |
|
|
958 | trying to lobby/force people into reporting untruths. |
|
|
959 | |
|
|
960 | =back |
875 | |
961 | |
876 | |
962 | |
877 | =head2 SPEED |
963 | =head2 SPEED |
878 | |
964 | |
879 | It seems that JSON::XS is surprisingly fast, as shown in the following |
965 | It seems that JSON::XS is surprisingly fast, as shown in the following |
… | |
… | |
890 | It shows the number of encodes/decodes per second (JSON::XS uses |
976 | It shows the number of encodes/decodes per second (JSON::XS uses |
891 | the functional interface, while JSON::XS/2 uses the OO interface |
977 | the functional interface, while JSON::XS/2 uses the OO interface |
892 | with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables |
978 | with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables |
893 | shrink). Higher is better: |
979 | shrink). Higher is better: |
894 | |
980 | |
895 | Storable | 15779.925 | 14169.946 | |
|
|
896 | -----------+------------+------------+ |
|
|
897 | module | encode | decode | |
981 | module | encode | decode | |
898 | -----------|------------|------------| |
982 | -----------|------------|------------| |
899 | JSON | 4990.842 | 4088.813 | |
983 | JSON 1.x | 4990.842 | 4088.813 | |
900 | JSON::DWIW | 51653.990 | 71575.154 | |
984 | JSON::DWIW | 51653.990 | 71575.154 | |
901 | JSON::PC | 65948.176 | 74631.744 | |
985 | JSON::PC | 65948.176 | 74631.744 | |
902 | JSON::PP | 8931.652 | 3817.168 | |
986 | JSON::PP | 8931.652 | 3817.168 | |
903 | JSON::Syck | 24877.248 | 27776.848 | |
987 | JSON::Syck | 24877.248 | 27776.848 | |
904 | JSON::XS | 388361.481 | 227951.304 | |
988 | JSON::XS | 388361.481 | 227951.304 | |
… | |
… | |
915 | Using a longer test string (roughly 18KB, generated from Yahoo! Locals |
999 | Using a longer test string (roughly 18KB, generated from Yahoo! Locals |
916 | search API (http://nanoref.com/yahooapis/mgPdGg): |
1000 | search API (http://nanoref.com/yahooapis/mgPdGg): |
917 | |
1001 | |
918 | module | encode | decode | |
1002 | module | encode | decode | |
919 | -----------|------------|------------| |
1003 | -----------|------------|------------| |
920 | JSON | 55.260 | 34.971 | |
1004 | JSON 1.x | 55.260 | 34.971 | |
921 | JSON::DWIW | 825.228 | 1082.513 | |
1005 | JSON::DWIW | 825.228 | 1082.513 | |
922 | JSON::PC | 3571.444 | 2394.829 | |
1006 | JSON::PC | 3571.444 | 2394.829 | |
923 | JSON::PP | 210.987 | 32.574 | |
1007 | JSON::PP | 210.987 | 32.574 | |
924 | JSON::Syck | 552.551 | 787.544 | |
1008 | JSON::Syck | 552.551 | 787.544 | |
925 | JSON::XS | 5780.463 | 4854.519 | |
1009 | JSON::XS | 5780.463 | 4854.519 | |
… | |
… | |
958 | |
1042 | |
959 | Third, JSON::XS recurses using the C stack when decoding objects and |
1043 | Third, JSON::XS recurses using the C stack when decoding objects and |
960 | arrays. The C stack is a limited resource: for instance, on my amd64 |
1044 | arrays. The C stack is a limited resource: for instance, on my amd64 |
961 | machine with 8MB of stack size I can decode around 180k nested arrays but |
1045 | machine with 8MB of stack size I can decode around 180k nested arrays but |
962 | only 14k nested JSON objects (due to perl itself recursing deeply on croak |
1046 | only 14k nested JSON objects (due to perl itself recursing deeply on croak |
963 | to free the temporary). If that is exceeded, the program crashes. to be |
1047 | to free the temporary). If that is exceeded, the program crashes. To be |
964 | conservative, the default nesting limit is set to 512. If your process |
1048 | conservative, the default nesting limit is set to 512. If your process |
965 | has a smaller stack, you should adjust this setting accordingly with the |
1049 | has a smaller stack, you should adjust this setting accordingly with the |
966 | C<max_depth> method. |
1050 | C<max_depth> method. |
967 | |
1051 | |
968 | And last but least, something else could bomb you that I forgot to think |
1052 | And last but least, something else could bomb you that I forgot to think |
… | |
… | |
972 | If you are using JSON::XS to return packets to consumption |
1056 | If you are using JSON::XS to return packets to consumption |
973 | by JavaScript scripts in a browser you should have a look at |
1057 | by JavaScript scripts in a browser you should have a look at |
974 | L<http://jpsykes.com/47/practical-csrf-and-json-security> to see whether |
1058 | L<http://jpsykes.com/47/practical-csrf-and-json-security> to see whether |
975 | you are vulnerable to some common attack vectors (which really are browser |
1059 | you are vulnerable to some common attack vectors (which really are browser |
976 | design bugs, but it is still you who will have to deal with it, as major |
1060 | design bugs, but it is still you who will have to deal with it, as major |
977 | browser developers care only for features, not about doing security |
1061 | browser developers care only for features, not about getting security |
978 | right). |
1062 | right). |
979 | |
1063 | |
980 | |
1064 | |
981 | =head1 THREADS |
1065 | =head1 THREADS |
982 | |
1066 | |