… | |
… | |
84 | |
84 | |
85 | package JSON::XS; |
85 | package JSON::XS; |
86 | |
86 | |
87 | use strict; |
87 | use strict; |
88 | |
88 | |
89 | our $VERSION = '1.52'; |
89 | our $VERSION = '2.0'; |
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 |
… | |
… | |
245 | |
249 | |
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]) |
|
|
254 | |
|
|
255 | =item $enabled = $json->get_utf8 |
250 | |
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 |
… | |
… | |
288 | ] |
294 | ] |
289 | } |
295 | } |
290 | |
296 | |
291 | =item $json = $json->indent ([$enable]) |
297 | =item $json = $json->indent ([$enable]) |
292 | |
298 | |
|
|
299 | =item $enabled = $json->get_indent |
|
|
300 | |
293 | If C<$enable> is true (or missing), then the C<encode> method will use a multiline |
301 | 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 |
302 | format as output, putting every array member or object/hash key-value pair |
295 | into its own line, indenting them properly. |
303 | into its own line, indenting them properly. |
296 | |
304 | |
297 | If C<$enable> is false, no newlines or indenting will be produced, and the |
305 | If C<$enable> is false, no newlines or indenting will be produced, and the |
… | |
… | |
299 | |
307 | |
300 | This setting has no effect when decoding JSON texts. |
308 | This setting has no effect when decoding JSON texts. |
301 | |
309 | |
302 | =item $json = $json->space_before ([$enable]) |
310 | =item $json = $json->space_before ([$enable]) |
303 | |
311 | |
|
|
312 | =item $enabled = $json->get_space_before |
|
|
313 | |
304 | If C<$enable> is true (or missing), then the C<encode> method will add an extra |
314 | 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. |
315 | optional space before the C<:> separating keys from values in JSON objects. |
306 | |
316 | |
307 | If C<$enable> is false, then the C<encode> method will not add any extra |
317 | If C<$enable> is false, then the C<encode> method will not add any extra |
308 | space at those places. |
318 | space at those places. |
… | |
… | |
313 | Example, space_before enabled, space_after and indent disabled: |
323 | Example, space_before enabled, space_after and indent disabled: |
314 | |
324 | |
315 | {"key" :"value"} |
325 | {"key" :"value"} |
316 | |
326 | |
317 | =item $json = $json->space_after ([$enable]) |
327 | =item $json = $json->space_after ([$enable]) |
|
|
328 | |
|
|
329 | =item $enabled = $json->get_space_after |
318 | |
330 | |
319 | If C<$enable> is true (or missing), then the C<encode> method will add an extra |
331 | 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 |
332 | 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 |
333 | and extra whitespace after the C<,> separating key-value pairs and array |
322 | members. |
334 | members. |
… | |
… | |
329 | Example, space_before and indent disabled, space_after enabled: |
341 | Example, space_before and indent disabled, space_after enabled: |
330 | |
342 | |
331 | {"key": "value"} |
343 | {"key": "value"} |
332 | |
344 | |
333 | =item $json = $json->relaxed ([$enable]) |
345 | =item $json = $json->relaxed ([$enable]) |
|
|
346 | |
|
|
347 | =item $enabled = $json->get_relaxed |
334 | |
348 | |
335 | If C<$enable> is true (or missing), then C<decode> will accept some |
349 | 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 |
350 | 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 |
351 | 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 |
352 | JSON texts as if they were valid!>. I suggest only to use this option to |
… | |
… | |
375 | |
389 | |
376 | =back |
390 | =back |
377 | |
391 | |
378 | =item $json = $json->canonical ([$enable]) |
392 | =item $json = $json->canonical ([$enable]) |
379 | |
393 | |
|
|
394 | =item $enabled = $json->get_canonical |
|
|
395 | |
380 | If C<$enable> is true (or missing), then the C<encode> method will output JSON objects |
396 | 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. |
397 | by sorting their keys. This is adding a comparatively high overhead. |
382 | |
398 | |
383 | If C<$enable> is false, then the C<encode> method will output key-value |
399 | 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 |
400 | pairs in the order Perl stores them (which will likely change between runs |
… | |
… | |
391 | |
407 | |
392 | This setting has no effect when decoding JSON texts. |
408 | This setting has no effect when decoding JSON texts. |
393 | |
409 | |
394 | =item $json = $json->allow_nonref ([$enable]) |
410 | =item $json = $json->allow_nonref ([$enable]) |
395 | |
411 | |
|
|
412 | =item $enabled = $json->get_allow_nonref |
|
|
413 | |
396 | If C<$enable> is true (or missing), then the C<encode> method can convert a |
414 | 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, |
415 | 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 |
416 | which is an extension to RFC4627. Likewise, C<decode> will accept those JSON |
399 | values instead of croaking. |
417 | values instead of croaking. |
400 | |
418 | |
… | |
… | |
408 | |
426 | |
409 | JSON::XS->new->allow_nonref->encode ("Hello, World!") |
427 | JSON::XS->new->allow_nonref->encode ("Hello, World!") |
410 | => "Hello, World!" |
428 | => "Hello, World!" |
411 | |
429 | |
412 | =item $json = $json->allow_blessed ([$enable]) |
430 | =item $json = $json->allow_blessed ([$enable]) |
|
|
431 | |
|
|
432 | =item $enabled = $json->get_allow_bless |
413 | |
433 | |
414 | If C<$enable> is true (or missing), then the C<encode> method will not |
434 | 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 |
435 | 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> |
436 | 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 |
437 | disabled or no C<to_json> method found) or a representation of the |
… | |
… | |
420 | |
440 | |
421 | If C<$enable> is false (the default), then C<encode> will throw an |
441 | If C<$enable> is false (the default), then C<encode> will throw an |
422 | exception when it encounters a blessed object. |
442 | exception when it encounters a blessed object. |
423 | |
443 | |
424 | =item $json = $json->convert_blessed ([$enable]) |
444 | =item $json = $json->convert_blessed ([$enable]) |
|
|
445 | |
|
|
446 | =item $enabled = $json->get_convert_blessed |
425 | |
447 | |
426 | If C<$enable> is true (or missing), then C<encode>, upon encountering a |
448 | 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 |
449 | 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 |
450 | 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 |
451 | and the resulting scalar will be encoded instead of the object. If no |
… | |
… | |
520 | |
542 | |
521 | { __widget__ => $self->{id} } |
543 | { __widget__ => $self->{id} } |
522 | } |
544 | } |
523 | |
545 | |
524 | =item $json = $json->shrink ([$enable]) |
546 | =item $json = $json->shrink ([$enable]) |
|
|
547 | |
|
|
548 | =item $enabled = $json->get_shrink |
525 | |
549 | |
526 | Perl usually over-allocates memory a bit when allocating space for |
550 | Perl usually over-allocates memory a bit when allocating space for |
527 | strings. This flag optionally resizes strings generated by either |
551 | strings. This flag optionally resizes strings generated by either |
528 | C<encode> or C<decode> to their minimum size possible. This can save |
552 | 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 |
553 | 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 |
571 | strings that look like integers or floats into integers or floats |
548 | internally (there is no difference on the Perl level), saving space. |
572 | internally (there is no difference on the Perl level), saving space. |
549 | |
573 | |
550 | =item $json = $json->max_depth ([$maximum_nesting_depth]) |
574 | =item $json = $json->max_depth ([$maximum_nesting_depth]) |
551 | |
575 | |
|
|
576 | =item $max_depth = $json->get_max_depth |
|
|
577 | |
552 | Sets the maximum nesting level (default C<512>) accepted while encoding |
578 | 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 |
579 | 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 |
580 | higher nesting level then this limit, then the encoder and decoder will |
555 | stop and croak at that point. |
581 | stop and croak at that point. |
556 | |
582 | |
… | |
… | |
567 | used, which is rarely useful. |
593 | used, which is rarely useful. |
568 | |
594 | |
569 | See SECURITY CONSIDERATIONS, below, for more info on why this is useful. |
595 | See SECURITY CONSIDERATIONS, below, for more info on why this is useful. |
570 | |
596 | |
571 | =item $json = $json->max_size ([$maximum_string_size]) |
597 | =item $json = $json->max_size ([$maximum_string_size]) |
|
|
598 | |
|
|
599 | =item $max_size = $json->get_max_size |
572 | |
600 | |
573 | Set the maximum length a JSON text may have (in bytes) where decoding is |
601 | 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> |
602 | 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 |
603 | 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 |
604 | attempt to decode the string but throw an exception. This setting has no |
… | |
… | |
890 | It shows the number of encodes/decodes per second (JSON::XS uses |
918 | It shows the number of encodes/decodes per second (JSON::XS uses |
891 | the functional interface, while JSON::XS/2 uses the OO interface |
919 | the functional interface, while JSON::XS/2 uses the OO interface |
892 | with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables |
920 | with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables |
893 | shrink). Higher is better: |
921 | shrink). Higher is better: |
894 | |
922 | |
895 | Storable | 15779.925 | 14169.946 | |
|
|
896 | -----------+------------+------------+ |
|
|
897 | module | encode | decode | |
923 | module | encode | decode | |
898 | -----------|------------|------------| |
924 | -----------|------------|------------| |
899 | JSON | 4990.842 | 4088.813 | |
925 | JSON 1.x | 4990.842 | 4088.813 | |
900 | JSON::DWIW | 51653.990 | 71575.154 | |
926 | JSON::DWIW | 51653.990 | 71575.154 | |
901 | JSON::PC | 65948.176 | 74631.744 | |
927 | JSON::PC | 65948.176 | 74631.744 | |
902 | JSON::PP | 8931.652 | 3817.168 | |
928 | JSON::PP | 8931.652 | 3817.168 | |
903 | JSON::Syck | 24877.248 | 27776.848 | |
929 | JSON::Syck | 24877.248 | 27776.848 | |
904 | JSON::XS | 388361.481 | 227951.304 | |
930 | JSON::XS | 388361.481 | 227951.304 | |
… | |
… | |
915 | Using a longer test string (roughly 18KB, generated from Yahoo! Locals |
941 | Using a longer test string (roughly 18KB, generated from Yahoo! Locals |
916 | search API (http://nanoref.com/yahooapis/mgPdGg): |
942 | search API (http://nanoref.com/yahooapis/mgPdGg): |
917 | |
943 | |
918 | module | encode | decode | |
944 | module | encode | decode | |
919 | -----------|------------|------------| |
945 | -----------|------------|------------| |
920 | JSON | 55.260 | 34.971 | |
946 | JSON 1.x | 55.260 | 34.971 | |
921 | JSON::DWIW | 825.228 | 1082.513 | |
947 | JSON::DWIW | 825.228 | 1082.513 | |
922 | JSON::PC | 3571.444 | 2394.829 | |
948 | JSON::PC | 3571.444 | 2394.829 | |
923 | JSON::PP | 210.987 | 32.574 | |
949 | JSON::PP | 210.987 | 32.574 | |
924 | JSON::Syck | 552.551 | 787.544 | |
950 | JSON::Syck | 552.551 | 787.544 | |
925 | JSON::XS | 5780.463 | 4854.519 | |
951 | JSON::XS | 5780.463 | 4854.519 | |