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.32 by root, Thu Apr 12 07:25:29 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.12';
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
… …
154 154
155If C<$enable> is true (or missing), then the C<encode> method will not 155If C<$enable> is true (or missing), then the C<encode> method will not
156generate characters outside the code range C<0..127> (which is ASCII). Any 156generate characters outside the code range C<0..127> (which is ASCII). Any
157unicode characters outside that range will be escaped using either a 157unicode characters outside that range will be escaped using either a
158single \uXXXX (BMP characters) or a double \uHHHH\uLLLLL escape sequence, 158single \uXXXX (BMP characters) or a double \uHHHH\uLLLLL escape sequence,
159as per RFC4627. 159as per RFC4627. The resulting encoded JSON text can be treated as a native
160unicode string, an ascii-encoded, latin1-encoded or UTF-8 encoded string,
161or any other superset of ASCII.
160 162
161If C<$enable> is false, then the C<encode> method will not escape Unicode 163If C<$enable> is false, then the C<encode> method will not escape Unicode
162characters unless required by the JSON syntax. This results in a faster 164characters unless required by the JSON syntax. This results in a faster
163and more compact format. 165and more compact format.
164 166
… …
309strings that look like integers or floats into integers or floats 311strings that look like integers or floats into integers or floats
310internally (there is no difference on the Perl level), saving space. 312internally (there is no difference on the Perl level), saving space.
311 313
312=item $json = $json->max_depth ([$maximum_nesting_depth]) 314=item $json = $json->max_depth ([$maximum_nesting_depth])
313 315
314Sets the maximum nesting level (default C<8192>) accepted while encoding 316Sets the maximum nesting level (default C<512>) accepted while encoding
315or decoding. If the JSON text or Perl data structure has an equal or 317or 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 318higher nesting level then this limit, then the encoder and decoder will
317stop and croak at that point. 319stop and croak at that point.
318 320
319Nesting level is defined by number of hash- or arrayrefs that the encoder 321Nesting level is defined by number of hash- or arrayrefs that the encoder
… …
410=over 4 412=over 4
411 413
412=item hash references 414=item hash references
413 415
414Perl hash references become JSON objects. As there is no inherent ordering 416Perl 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 417in 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 418pseudo-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 419stays generally the same within a single run of a program. JSON::XS can
418keys (determined by the I<canonical> flag), so the same datastructure 420optionally sort the hash keys (determined by the I<canonical> flag), so
419will serialise to the same JSON text (given same settings and version of 421the same datastructure will serialise to the same JSON text (given same
420JSON::XS), but this incurs a runtime overhead. 422settings and version of JSON::XS), but this incurs a runtime overhead
423and is only rarely useful, e.g. when you want to compare some JSON text
424against another for equality.
421 425
422=item array references 426=item array references
423 427
424Perl array references become JSON arrays. 428Perl array references become JSON arrays.
429
430=item other references
431
432Other unblessed references are generally not allowed and will cause an
433exception to be thrown, except for references to the integers C<0> and
434C<1>, which get turned into C<false> and C<true> atoms in JSON. You can
435also use C<JSON::XS::false> and C<JSON::XS::true> to improve readability.
436
437 to_json [\0,JSON::XS::true] # yields [false,true]
425 438
426=item blessed objects 439=item blessed objects
427 440
428Blessed objects are not allowed. JSON::XS currently tries to encode their 441Blessed objects are not allowed. JSON::XS currently tries to encode their
429underlying representation (hash- or arrayref), but this behaviour might 442underlying representation (hash- or arrayref), but this behaviour might
… …
461 $x += 0; # numify it, ensuring it will be dumped as a number 474 $x += 0; # numify it, ensuring it will be dumped as a number
462 $x *= 1; # same thing, the choise is yours. 475 $x *= 1; # same thing, the choise is yours.
463 476
464You can not currently output JSON booleans or force the type in other, 477You can not currently output JSON booleans or force the type in other,
465less obscure, ways. Tell me if you need this capability. 478less 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 479
471=back 480=back
472 481
473 482
474=head1 COMPARISON 483=head1 COMPARISON
… …
625usually a good indication of the size of the resources required to decode 634usually a good indication of the size of the resources required to decode
626it into a Perl structure. 635it into a Perl structure.
627 636
628Third, JSON::XS recurses using the C stack when decoding objects and 637Third, JSON::XS recurses using the C stack when decoding objects and
629arrays. The C stack is a limited resource: for instance, on my amd64 638arrays. 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 639machine 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 640only 14k nested JSON objects (due to perl itself recursing deeply on croak
641to 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 642conservative, the default nesting limit is set to 512. If your process
633process has a smaller stack, you should adjust this setting accordingly 643has a smaller stack, you should adjust this setting accordingly with the
634with the C<max_depth> method. 644C<max_depth> method.
635 645
636And last but least, something else could bomb you that I forgot to think 646And 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, 647of. In that case, you get to keep the pieces. I am always open for hints,
638though... 648though...
639 649
640 650
641=head1 BUGS 651=head1 BUGS
642 652
… …
645still relatively early in its development. If you keep reporting bugs they 655still relatively early in its development. If you keep reporting bugs they
646will be fixed swiftly, though. 656will be fixed swiftly, though.
647 657
648=cut 658=cut
649 659
660sub true() { \1 }
661sub false() { \0 }
662
6501; 6631;
651 664
652=head1 AUTHOR 665=head1 AUTHOR
653 666
654 Marc Lehmann <schmorp@schmorp.de> 667 Marc Lehmann <schmorp@schmorp.de>

Diff Legend

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