… | |
… | |
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.02'; |
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 |
… | |
… | |
461 | $x += 0; # numify it, ensuring it will be dumped as a number |
472 | $x += 0; # numify it, ensuring it will be dumped as a number |
462 | $x *= 1; # same thing, the choise is yours. |
473 | $x *= 1; # same thing, the choise is yours. |
463 | |
474 | |
464 | You can not currently output JSON booleans or force the type in other, |
475 | You can not currently output JSON booleans or force the type in other, |
465 | less obscure, ways. Tell me if you need this capability. |
476 | less obscure, ways. Tell me if you need this capability. |
466 | |
|
|
467 | =item circular data structures |
|
|
468 | |
|
|
469 | Those will be encoded until memory or stackspace runs out. |
|
|
470 | |
477 | |
471 | =back |
478 | =back |
472 | |
479 | |
473 | |
480 | |
474 | =head1 COMPARISON |
481 | =head1 COMPARISON |
… | |
… | |
627 | |
634 | |
628 | Third, JSON::XS recurses using the C stack when decoding objects and |
635 | 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 |
636 | 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 |
637 | 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 |
638 | 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 |
639 | 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 |
640 | process has a smaller stack, you should adjust this setting accordingly |
634 | with the C<max_depth> method. |
641 | with the C<max_depth> method. |
635 | |
642 | |
636 | And last but least, something else could bomb you that I forgot to think |
643 | 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, |
644 | 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 |
652 | still relatively early in its development. If you keep reporting bugs they |
646 | will be fixed swiftly, though. |
653 | will be fixed swiftly, though. |
647 | |
654 | |
648 | =cut |
655 | =cut |
649 | |
656 | |
|
|
657 | sub true() { \1 } |
|
|
658 | sub false() { \0 } |
|
|
659 | |
650 | 1; |
660 | 1; |
651 | |
661 | |
652 | =head1 AUTHOR |
662 | =head1 AUTHOR |
653 | |
663 | |
654 | Marc Lehmann <schmorp@schmorp.de> |
664 | Marc Lehmann <schmorp@schmorp.de> |