ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/JSON-XS/XS.pm
(Generate patch)

Comparing JSON-XS/XS.pm (file contents):
Revision 1.24 by root, Thu Mar 29 01:27:36 2007 UTC vs.
Revision 1.29 by root, Mon Apr 9 05:09:57 2007 UTC

… …
86package JSON::XS; 86package JSON::XS;
87 87
88use strict; 88use strict;
89 89
90BEGIN { 90BEGIN {
91 our $VERSION = '0.8'; 91 our $VERSION = '1.11';
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
… …
309strings that look like integers or floats into integers or floats 309strings that look like integers or floats into integers or floats
310internally (there is no difference on the Perl level), saving space. 310internally (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
314Sets the maximum nesting level (default C<8192>) accepted while encoding 314Sets the maximum nesting level (default C<512>) accepted while encoding
315or decoding. If the JSON text or Perl data structure has an equal or 315or decoding. If the JSON text or Perl data structure has an equal or
316higher nesting level then this limit, then the encoder and decoder will 316higher nesting level then this limit, then the encoder and decoder will
317stop and croak at that point. 317stop and croak at that point.
318 318
319Nesting level is defined by number of hash- or arrayrefs that the encoder 319Nesting 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
414Perl hash references become JSON objects. As there is no inherent ordering 414Perl hash references become JSON objects. As there is no inherent ordering
415in hash keys, they will usually be encoded in a pseudo-random order that 415in hash keys (or JSON objects), they will usually be encoded in a
416can change between runs of the same program but stays generally the same 416pseudo-random order that can change between runs of the same program but
417within a single run of a program. JSON::XS can optionally sort the hash 417stays generally the same within a single run of a program. JSON::XS can
418keys (determined by the I<canonical> flag), so the same datastructure 418optionally sort the hash keys (determined by the I<canonical> flag), so
419will serialise to the same JSON text (given same settings and version of 419the same datastructure will serialise to the same JSON text (given same
420JSON::XS), but this incurs a runtime overhead. 420settings and version of JSON::XS), but this incurs a runtime overhead
421and is only rarely useful, e.g. when you want to compare some JSON text
422against another for equality.
421 423
422=item array references 424=item array references
423 425
424Perl array references become JSON arrays. 426Perl array references become JSON arrays.
427
428=item other references
429
430Other unblessed references are generally not allowed and will cause an
431exception to be thrown, except for references to the integers C<0> and
432C<1>, which get turned into C<false> and C<true> atoms in JSON. You can
433also 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
428Blessed objects are not allowed. JSON::XS currently tries to encode their 439Blessed objects are not allowed. JSON::XS currently tries to encode their
429underlying representation (hash- or arrayref), but this behaviour might 440underlying 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
464You can not currently output JSON booleans or force the type in other, 475You can not currently output JSON booleans or force the type in other,
465less obscure, ways. Tell me if you need this capability. 476less obscure, ways. Tell me if you need this capability.
466
467=item circular data structures
468
469Those 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
… …
625usually a good indication of the size of the resources required to decode 632usually a good indication of the size of the resources required to decode
626it into a Perl structure. 633it into a Perl structure.
627 634
628Third, JSON::XS recurses using the C stack when decoding objects and 635Third, JSON::XS recurses using the C stack when decoding objects and
629arrays. The C stack is a limited resource: for instance, on my amd64 636arrays. The C stack is a limited resource: for instance, on my amd64
630machine with 8MB of stack size I can decode around 180k nested arrays 637machine with 8MB of stack size I can decode around 180k nested arrays but
631but only 14k nested JSON objects. If that is exceeded, the program 638only 14k nested JSON objects (due to perl itself recursing deeply on croak
639to free the temporary). If that is exceeded, the program crashes. to be
632crashes. Thats why the default nesting limit is set to 8192. If your 640conservative, the default nesting limit is set to 512. If your process
633process has a smaller stack, you should adjust this setting accordingly 641has a smaller stack, you should adjust this setting accordingly with the
634with the C<max_depth> method. 642C<max_depth> method.
635 643
636And last but least, something else could bomb you that I forgot to think 644And last but least, something else could bomb you that I forgot to think
637of. In that case, you get to keep the pieces. I am alway sopen for hints, 645of. In that case, you get to keep the pieces. I am alway sopen for hints,
638though... 646though...
639 647
… …
645still relatively early in its development. If you keep reporting bugs they 653still relatively early in its development. If you keep reporting bugs they
646will be fixed swiftly, though. 654will be fixed swiftly, though.
647 655
648=cut 656=cut
649 657
658sub true() { \1 }
659sub false() { \0 }
660
6501; 6611;
651 662
652=head1 AUTHOR 663=head1 AUTHOR
653 664
654 Marc Lehmann <schmorp@schmorp.de> 665 Marc Lehmann <schmorp@schmorp.de>

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines