… | |
… | |
84 | |
84 | |
85 | package JSON::XS; |
85 | package JSON::XS; |
86 | |
86 | |
87 | use strict; |
87 | use strict; |
88 | |
88 | |
89 | our $VERSION = '1.53'; |
89 | our $VERSION = '1.6'; |
90 | our @ISA = qw(Exporter); |
90 | our @ISA = qw(Exporter); |
91 | |
91 | |
92 | our @EXPORT = qw(to_json from_json); |
92 | our @EXPORT = qw(to_json from_json); |
93 | |
93 | |
94 | use Exporter; |
94 | use Exporter; |
… | |
… | |
201 | |
201 | |
202 | my $json = JSON::XS->new->utf8->space_after->encode ({a => [1,2]}) |
202 | my $json = JSON::XS->new->utf8->space_after->encode ({a => [1,2]}) |
203 | => {"a": [1, 2]} |
203 | => {"a": [1, 2]} |
204 | |
204 | |
205 | =item $json = $json->ascii ([$enable]) |
205 | =item $json = $json->ascii ([$enable]) |
|
|
206 | |
|
|
207 | =item $enabled = $json->get_ascii |
206 | |
208 | |
207 | If C<$enable> is true (or missing), then the C<encode> method will not |
209 | 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 |
210 | 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 |
211 | Unicode characters outside that range will be escaped using either a |
210 | single \uXXXX (BMP characters) or a double \uHHHH\uLLLLL escape sequence, |
212 | single \uXXXX (BMP characters) or a double \uHHHH\uLLLLL escape sequence, |
… | |
… | |
223 | JSON::XS->new->ascii (1)->encode ([chr 0x10401]) |
225 | JSON::XS->new->ascii (1)->encode ([chr 0x10401]) |
224 | => ["\ud801\udc01"] |
226 | => ["\ud801\udc01"] |
225 | |
227 | |
226 | =item $json = $json->latin1 ([$enable]) |
228 | =item $json = $json->latin1 ([$enable]) |
227 | |
229 | |
|
|
230 | =item $enabled = $json->get_latin1 |
|
|
231 | |
228 | If C<$enable> is true (or missing), then the C<encode> method will encode |
232 | 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 |
233 | 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 |
234 | 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 |
235 | 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 |
236 | will not be affected in any way by this flag, as C<decode> by default |
… | |
… | |
246 | JSON::XS->new->latin1->encode (["\x{89}\x{abc}"] |
250 | JSON::XS->new->latin1->encode (["\x{89}\x{abc}"] |
247 | => ["\x{89}\\u0abc"] # (perl syntax, U+abc escaped, U+89 not) |
251 | => ["\x{89}\\u0abc"] # (perl syntax, U+abc escaped, U+89 not) |
248 | |
252 | |
249 | =item $json = $json->utf8 ([$enable]) |
253 | =item $json = $json->utf8 ([$enable]) |
250 | |
254 | |
|
|
255 | =item $enabled = $json->get_utf8 |
|
|
256 | |
251 | If C<$enable> is true (or missing), then the C<encode> method will encode |
257 | 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 |
258 | 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 |
259 | 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 |
260 | note that UTF-8-encoded strings do not contain any characters outside the |
255 | range C<0..255>, they are thus useful for bytewise/binary I/O. In future |
261 | range C<0..255>, they are thus useful for bytewise/binary I/O. In future |
… | |
… | |
270 | |
276 | |
271 | use Encode; |
277 | use Encode; |
272 | $object = JSON::XS->new->decode (decode "UTF-32LE", $jsontext); |
278 | $object = JSON::XS->new->decode (decode "UTF-32LE", $jsontext); |
273 | |
279 | |
274 | =item $json = $json->pretty ([$enable]) |
280 | =item $json = $json->pretty ([$enable]) |
|
|
281 | |
|
|
282 | =item $enabled = $json->get_pretty |
275 | |
283 | |
276 | This enables (or disables) all of the C<indent>, C<space_before> and |
284 | This enables (or disables) all of the C<indent>, C<space_before> and |
277 | C<space_after> (and in the future possibly more) flags in one call to |
285 | C<space_after> (and in the future possibly more) flags in one call to |
278 | generate the most readable (or most compact) form possible. |
286 | generate the most readable (or most compact) form possible. |
279 | |
287 | |
… | |
… | |
288 | ] |
296 | ] |
289 | } |
297 | } |
290 | |
298 | |
291 | =item $json = $json->indent ([$enable]) |
299 | =item $json = $json->indent ([$enable]) |
292 | |
300 | |
|
|
301 | =item $enabled = $json->get_indent |
|
|
302 | |
293 | If C<$enable> is true (or missing), then the C<encode> method will use a multiline |
303 | 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 |
304 | format as output, putting every array member or object/hash key-value pair |
295 | into its own line, indenting them properly. |
305 | into its own line, indenting them properly. |
296 | |
306 | |
297 | If C<$enable> is false, no newlines or indenting will be produced, and the |
307 | If C<$enable> is false, no newlines or indenting will be produced, and the |
… | |
… | |
299 | |
309 | |
300 | This setting has no effect when decoding JSON texts. |
310 | This setting has no effect when decoding JSON texts. |
301 | |
311 | |
302 | =item $json = $json->space_before ([$enable]) |
312 | =item $json = $json->space_before ([$enable]) |
303 | |
313 | |
|
|
314 | =item $enabled = $json->get_space_before |
|
|
315 | |
304 | If C<$enable> is true (or missing), then the C<encode> method will add an extra |
316 | 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. |
317 | optional space before the C<:> separating keys from values in JSON objects. |
306 | |
318 | |
307 | If C<$enable> is false, then the C<encode> method will not add any extra |
319 | If C<$enable> is false, then the C<encode> method will not add any extra |
308 | space at those places. |
320 | space at those places. |
… | |
… | |
313 | Example, space_before enabled, space_after and indent disabled: |
325 | Example, space_before enabled, space_after and indent disabled: |
314 | |
326 | |
315 | {"key" :"value"} |
327 | {"key" :"value"} |
316 | |
328 | |
317 | =item $json = $json->space_after ([$enable]) |
329 | =item $json = $json->space_after ([$enable]) |
|
|
330 | |
|
|
331 | =item $enabled = $json->get_space_after |
318 | |
332 | |
319 | If C<$enable> is true (or missing), then the C<encode> method will add an extra |
333 | 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 |
334 | 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 |
335 | and extra whitespace after the C<,> separating key-value pairs and array |
322 | members. |
336 | members. |
… | |
… | |
329 | Example, space_before and indent disabled, space_after enabled: |
343 | Example, space_before and indent disabled, space_after enabled: |
330 | |
344 | |
331 | {"key": "value"} |
345 | {"key": "value"} |
332 | |
346 | |
333 | =item $json = $json->relaxed ([$enable]) |
347 | =item $json = $json->relaxed ([$enable]) |
|
|
348 | |
|
|
349 | =item $enabled = $json->get_relaxed |
334 | |
350 | |
335 | If C<$enable> is true (or missing), then C<decode> will accept some |
351 | 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 |
352 | 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 |
353 | 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 |
354 | JSON texts as if they were valid!>. I suggest only to use this option to |
… | |
… | |
375 | |
391 | |
376 | =back |
392 | =back |
377 | |
393 | |
378 | =item $json = $json->canonical ([$enable]) |
394 | =item $json = $json->canonical ([$enable]) |
379 | |
395 | |
|
|
396 | =item $enabled = $json->get_canonical |
|
|
397 | |
380 | If C<$enable> is true (or missing), then the C<encode> method will output JSON objects |
398 | 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. |
399 | by sorting their keys. This is adding a comparatively high overhead. |
382 | |
400 | |
383 | If C<$enable> is false, then the C<encode> method will output key-value |
401 | 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 |
402 | pairs in the order Perl stores them (which will likely change between runs |
… | |
… | |
391 | |
409 | |
392 | This setting has no effect when decoding JSON texts. |
410 | This setting has no effect when decoding JSON texts. |
393 | |
411 | |
394 | =item $json = $json->allow_nonref ([$enable]) |
412 | =item $json = $json->allow_nonref ([$enable]) |
395 | |
413 | |
|
|
414 | =item $enabled = $json->get_allow_nonref |
|
|
415 | |
396 | If C<$enable> is true (or missing), then the C<encode> method can convert a |
416 | 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, |
417 | 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 |
418 | which is an extension to RFC4627. Likewise, C<decode> will accept those JSON |
399 | values instead of croaking. |
419 | values instead of croaking. |
400 | |
420 | |
… | |
… | |
408 | |
428 | |
409 | JSON::XS->new->allow_nonref->encode ("Hello, World!") |
429 | JSON::XS->new->allow_nonref->encode ("Hello, World!") |
410 | => "Hello, World!" |
430 | => "Hello, World!" |
411 | |
431 | |
412 | =item $json = $json->allow_blessed ([$enable]) |
432 | =item $json = $json->allow_blessed ([$enable]) |
|
|
433 | |
|
|
434 | =item $enabled = $json->get_allow_bless |
413 | |
435 | |
414 | If C<$enable> is true (or missing), then the C<encode> method will not |
436 | 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 |
437 | 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> |
438 | 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 |
439 | disabled or no C<to_json> method found) or a representation of the |
… | |
… | |
420 | |
442 | |
421 | If C<$enable> is false (the default), then C<encode> will throw an |
443 | If C<$enable> is false (the default), then C<encode> will throw an |
422 | exception when it encounters a blessed object. |
444 | exception when it encounters a blessed object. |
423 | |
445 | |
424 | =item $json = $json->convert_blessed ([$enable]) |
446 | =item $json = $json->convert_blessed ([$enable]) |
|
|
447 | |
|
|
448 | =item $enabled = $json->get_convert_blessed |
425 | |
449 | |
426 | If C<$enable> is true (or missing), then C<encode>, upon encountering a |
450 | 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 |
451 | 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 |
452 | 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 |
453 | and the resulting scalar will be encoded instead of the object. If no |
… | |
… | |
520 | |
544 | |
521 | { __widget__ => $self->{id} } |
545 | { __widget__ => $self->{id} } |
522 | } |
546 | } |
523 | |
547 | |
524 | =item $json = $json->shrink ([$enable]) |
548 | =item $json = $json->shrink ([$enable]) |
|
|
549 | |
|
|
550 | =item $enabled = $json->get_shrink |
525 | |
551 | |
526 | Perl usually over-allocates memory a bit when allocating space for |
552 | Perl usually over-allocates memory a bit when allocating space for |
527 | strings. This flag optionally resizes strings generated by either |
553 | strings. This flag optionally resizes strings generated by either |
528 | C<encode> or C<decode> to their minimum size possible. This can save |
554 | 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 |
555 | 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 |
573 | strings that look like integers or floats into integers or floats |
548 | internally (there is no difference on the Perl level), saving space. |
574 | internally (there is no difference on the Perl level), saving space. |
549 | |
575 | |
550 | =item $json = $json->max_depth ([$maximum_nesting_depth]) |
576 | =item $json = $json->max_depth ([$maximum_nesting_depth]) |
551 | |
577 | |
|
|
578 | =item $max_depth = $json->get_max_depth |
|
|
579 | |
552 | Sets the maximum nesting level (default C<512>) accepted while encoding |
580 | 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 |
581 | 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 |
582 | higher nesting level then this limit, then the encoder and decoder will |
555 | stop and croak at that point. |
583 | stop and croak at that point. |
556 | |
584 | |
… | |
… | |
567 | used, which is rarely useful. |
595 | used, which is rarely useful. |
568 | |
596 | |
569 | See SECURITY CONSIDERATIONS, below, for more info on why this is useful. |
597 | See SECURITY CONSIDERATIONS, below, for more info on why this is useful. |
570 | |
598 | |
571 | =item $json = $json->max_size ([$maximum_string_size]) |
599 | =item $json = $json->max_size ([$maximum_string_size]) |
|
|
600 | |
|
|
601 | =item $max_size = $json->get_max_size |
572 | |
602 | |
573 | Set the maximum length a JSON text may have (in bytes) where decoding is |
603 | 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> |
604 | 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 |
605 | 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 |
606 | 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 |
922 | with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables |
893 | shrink). Higher is better: |
923 | shrink). Higher is better: |
894 | |
924 | |
895 | module | encode | decode | |
925 | module | encode | decode | |
896 | -----------|------------|------------| |
926 | -----------|------------|------------| |
897 | JSON | 4990.842 | 4088.813 | |
927 | JSON 1.x | 4990.842 | 4088.813 | |
898 | JSON::DWIW | 51653.990 | 71575.154 | |
928 | JSON::DWIW | 51653.990 | 71575.154 | |
899 | JSON::PC | 65948.176 | 74631.744 | |
929 | JSON::PC | 65948.176 | 74631.744 | |
900 | JSON::PP | 8931.652 | 3817.168 | |
930 | JSON::PP | 8931.652 | 3817.168 | |
901 | JSON::Syck | 24877.248 | 27776.848 | |
931 | JSON::Syck | 24877.248 | 27776.848 | |
902 | JSON::XS | 388361.481 | 227951.304 | |
932 | JSON::XS | 388361.481 | 227951.304 | |
… | |
… | |
913 | Using a longer test string (roughly 18KB, generated from Yahoo! Locals |
943 | Using a longer test string (roughly 18KB, generated from Yahoo! Locals |
914 | search API (http://nanoref.com/yahooapis/mgPdGg): |
944 | search API (http://nanoref.com/yahooapis/mgPdGg): |
915 | |
945 | |
916 | module | encode | decode | |
946 | module | encode | decode | |
917 | -----------|------------|------------| |
947 | -----------|------------|------------| |
918 | JSON | 55.260 | 34.971 | |
948 | JSON 1.x | 55.260 | 34.971 | |
919 | JSON::DWIW | 825.228 | 1082.513 | |
949 | JSON::DWIW | 825.228 | 1082.513 | |
920 | JSON::PC | 3571.444 | 2394.829 | |
950 | JSON::PC | 3571.444 | 2394.829 | |
921 | JSON::PP | 210.987 | 32.574 | |
951 | JSON::PP | 210.987 | 32.574 | |
922 | JSON::Syck | 552.551 | 787.544 | |
952 | JSON::Syck | 552.551 | 787.544 | |
923 | JSON::XS | 5780.463 | 4854.519 | |
953 | JSON::XS | 5780.463 | 4854.519 | |