… | |
… | |
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.0'; |
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 | |
… | |
… | |
309 | strings that look like integers or floats into integers or floats |
309 | strings that look like integers or floats into integers or floats |
310 | internally (there is no difference on the Perl level), saving space. |
310 | internally (there is no difference on the Perl level), saving space. |
311 | |
311 | |
312 | =item $json = $json->max_depth ([$maximum_nesting_depth]) |
312 | =item $json = $json->max_depth ([$maximum_nesting_depth]) |
313 | |
313 | |
314 | Sets the maximum nesting level (default C<8192>) accepted while encoding |
314 | Sets the maximum nesting level (default C<4096>) accepted while encoding |
315 | 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 |
316 | 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 |
317 | stop and croak at that point. |
317 | stop and croak at that point. |
318 | |
318 | |
319 | 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 |
… | |
… | |
410 | =over 4 |
410 | =over 4 |
411 | |
411 | |
412 | =item hash references |
412 | =item hash references |
413 | |
413 | |
414 | 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 |
415 | 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 |
416 | 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 |
417 | 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 |
418 | keys (determined by the I<canonical> flag), so the same datastructure |
418 | optionally sort the hash keys (determined by the I<canonical> flag), so |
419 | 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 |
420 | 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. |
421 | |
423 | |
422 | =item array references |
424 | =item array references |
423 | |
425 | |
424 | 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] |
425 | |
436 | |
426 | =item blessed objects |
437 | =item blessed objects |
427 | |
438 | |
428 | 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 |
429 | underlying representation (hash- or arrayref), but this behaviour might |
440 | underlying representation (hash- or arrayref), but this behaviour might |
… | |
… | |
627 | |
638 | |
628 | 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 |
629 | 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 |
630 | 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 |
631 | 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 |
632 | 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 |
633 | process has a smaller stack, you should adjust this setting accordingly |
644 | process has a smaller stack, you should adjust this setting accordingly |
634 | with the C<max_depth> method. |
645 | with the C<max_depth> method. |
635 | |
646 | |
636 | 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 |
637 | 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, |
… | |
… | |
645 | 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 |
646 | will be fixed swiftly, though. |
657 | will be fixed swiftly, though. |
647 | |
658 | |
648 | =cut |
659 | =cut |
649 | |
660 | |
|
|
661 | sub true() { \1 } |
|
|
662 | sub false() { \0 } |
|
|
663 | |
650 | 1; |
664 | 1; |
651 | |
665 | |
652 | =head1 AUTHOR |
666 | =head1 AUTHOR |
653 | |
667 | |
654 | Marc Lehmann <schmorp@schmorp.de> |
668 | Marc Lehmann <schmorp@schmorp.de> |