… | |
… | |
86 | package JSON::XS; |
86 | package JSON::XS; |
87 | |
87 | |
88 | use strict; |
88 | use strict; |
89 | |
89 | |
90 | BEGIN { |
90 | BEGIN { |
91 | our $VERSION = '0.8'; |
91 | our $VERSION = '1.01'; |
92 | our @ISA = qw(Exporter); |
92 | our @ISA = qw(Exporter); |
93 | |
93 | |
94 | our @EXPORT = qw(to_json from_json objToJson jsonToObj); |
94 | our @EXPORT = qw(to_json from_json objToJson jsonToObj); |
95 | require Exporter; |
95 | require Exporter; |
96 | |
96 | |
… | |
… | |
284 | => "Hello, World!" |
284 | => "Hello, World!" |
285 | |
285 | |
286 | =item $json = $json->shrink ([$enable]) |
286 | =item $json = $json->shrink ([$enable]) |
287 | |
287 | |
288 | Perl usually over-allocates memory a bit when allocating space for |
288 | Perl usually over-allocates memory a bit when allocating space for |
289 | strings. This flag optionally resizes strings generated by either |
289 | strings. This flag optionally resizes strings generated by either |
290 | C<encode> or C<decode> to their minimum size possible. This can save |
290 | C<encode> or C<decode> to their minimum size possible. This can save |
291 | memory when your JSON texts are either very very long or you have many |
291 | memory when your JSON texts are either very very long or you have many |
292 | short strings. It will also try to downgrade any strings to octet-form |
292 | short strings. It will also try to downgrade any strings to octet-form |
293 | if possible: perl stores strings internally either in an encoding called |
293 | if possible: perl stores strings internally either in an encoding called |
294 | UTF-X or in octet-form. The latter cannot store everything but uses less |
294 | UTF-X or in octet-form. The latter cannot store everything but uses less |
295 | space in general. |
295 | space in general (and some buggy Perl or C code might even rely on that |
|
|
296 | internal representation being used). |
296 | |
297 | |
|
|
298 | The actual definition of what shrink does might change in future versions, |
|
|
299 | but it will always try to save space at the expense of time. |
|
|
300 | |
297 | If C<$enable> is true (or missing), the string returned by C<encode> will be shrunk-to-fit, |
301 | If C<$enable> is true (or missing), the string returned by C<encode> will |
298 | while all strings generated by C<decode> will also be shrunk-to-fit. |
302 | be shrunk-to-fit, while all strings generated by C<decode> will also be |
|
|
303 | shrunk-to-fit. |
299 | |
304 | |
300 | If C<$enable> is false, then the normal perl allocation algorithms are used. |
305 | If C<$enable> is false, then the normal perl allocation algorithms are used. |
301 | If you work with your data, then this is likely to be faster. |
306 | If you work with your data, then this is likely to be faster. |
302 | |
307 | |
303 | In the future, this setting might control other things, such as converting |
308 | In the future, this setting might control other things, such as converting |
304 | strings that look like integers or floats into integers or floats |
309 | strings that look like integers or floats into integers or floats |
305 | internally (there is no difference on the Perl level), saving space. |
310 | internally (there is no difference on the Perl level), saving space. |
306 | |
311 | |
307 | =item $json = $json->max_depth ([$maximum_nesting_depth]) |
312 | =item $json = $json->max_depth ([$maximum_nesting_depth]) |
308 | |
313 | |
309 | Sets the maximum nesting level (default C<8192>) accepted while encoding |
314 | Sets the maximum nesting level (default C<4096>) accepted while encoding |
310 | or decoding. If the JSON text or Perl data structure has an equal or |
315 | or decoding. If the JSON text or Perl data structure has an equal or |
311 | higher nesting level then this limit, then the encoder and decoder will |
316 | higher nesting level then this limit, then the encoder and decoder will |
312 | stop and croak at that point. |
317 | stop and croak at that point. |
313 | |
318 | |
314 | Nesting level is defined by number of hash- or arrayrefs that the encoder |
319 | Nesting level is defined by number of hash- or arrayrefs that the encoder |
… | |
… | |
405 | =over 4 |
410 | =over 4 |
406 | |
411 | |
407 | =item hash references |
412 | =item hash references |
408 | |
413 | |
409 | Perl hash references become JSON objects. As there is no inherent ordering |
414 | Perl hash references become JSON objects. As there is no inherent ordering |
410 | in hash keys, they will usually be encoded in a pseudo-random order that |
415 | in hash keys (or JSON objects), they will usually be encoded in a |
411 | can change between runs of the same program but stays generally the same |
416 | pseudo-random order that can change between runs of the same program but |
412 | within a single run of a program. JSON::XS can optionally sort the hash |
417 | stays generally the same within a single run of a program. JSON::XS can |
413 | keys (determined by the I<canonical> flag), so the same datastructure |
418 | optionally sort the hash keys (determined by the I<canonical> flag), so |
414 | will serialise to the same JSON text (given same settings and version of |
419 | the same datastructure will serialise to the same JSON text (given same |
415 | JSON::XS), but this incurs a runtime overhead. |
420 | settings and version of JSON::XS), but this incurs a runtime overhead |
|
|
421 | and is only rarely useful, e.g. when you want to compare some JSON text |
|
|
422 | against another for equality. |
416 | |
423 | |
417 | =item array references |
424 | =item array references |
418 | |
425 | |
419 | Perl array references become JSON arrays. |
426 | Perl array references become JSON arrays. |
|
|
427 | |
|
|
428 | =item other references |
|
|
429 | |
|
|
430 | Other unblessed references are generally not allowed and will cause an |
|
|
431 | exception to be thrown, except for references to the integers C<0> and |
|
|
432 | C<1>, which get turned into C<false> and C<true> atoms in JSON. You can |
|
|
433 | also use C<JSON::XS::false> and C<JSON::XS::true> to improve readability. |
|
|
434 | |
|
|
435 | to_json [\0,JSON::XS::true] # yields [false,true] |
420 | |
436 | |
421 | =item blessed objects |
437 | =item blessed objects |
422 | |
438 | |
423 | Blessed objects are not allowed. JSON::XS currently tries to encode their |
439 | Blessed objects are not allowed. JSON::XS currently tries to encode their |
424 | underlying representation (hash- or arrayref), but this behaviour might |
440 | underlying representation (hash- or arrayref), but this behaviour might |
… | |
… | |
622 | |
638 | |
623 | Third, JSON::XS recurses using the C stack when decoding objects and |
639 | Third, JSON::XS recurses using the C stack when decoding objects and |
624 | arrays. The C stack is a limited resource: for instance, on my amd64 |
640 | arrays. The C stack is a limited resource: for instance, on my amd64 |
625 | machine with 8MB of stack size I can decode around 180k nested arrays |
641 | machine with 8MB of stack size I can decode around 180k nested arrays |
626 | but only 14k nested JSON objects. If that is exceeded, the program |
642 | but only 14k nested JSON objects. If that is exceeded, the program |
627 | crashes. Thats why the default nesting limit is set to 8192. If your |
643 | crashes. Thats why the default nesting limit is set to 4096. If your |
628 | process has a smaller stack, you should adjust this setting accordingly |
644 | process has a smaller stack, you should adjust this setting accordingly |
629 | with the C<max_depth> method. |
645 | with the C<max_depth> method. |
630 | |
646 | |
631 | And last but least, something else could bomb you that I forgot to think |
647 | And last but least, something else could bomb you that I forgot to think |
632 | of. In that case, you get to keep the pieces. I am alway sopen for hints, |
648 | of. In that case, you get to keep the pieces. I am alway sopen for hints, |
… | |
… | |
640 | still relatively early in its development. If you keep reporting bugs they |
656 | still relatively early in its development. If you keep reporting bugs they |
641 | will be fixed swiftly, though. |
657 | will be fixed swiftly, though. |
642 | |
658 | |
643 | =cut |
659 | =cut |
644 | |
660 | |
|
|
661 | sub true() { \1 } |
|
|
662 | sub false() { \0 } |
|
|
663 | |
645 | 1; |
664 | 1; |
646 | |
665 | |
647 | =head1 AUTHOR |
666 | =head1 AUTHOR |
648 | |
667 | |
649 | Marc Lehmann <schmorp@schmorp.de> |
668 | Marc Lehmann <schmorp@schmorp.de> |