… | |
… | |
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.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 | |
155 | If C<$enable> is true (or missing), then the C<encode> method will not |
155 | If C<$enable> is true (or missing), then the C<encode> method will not |
156 | generate characters outside the code range C<0..127> (which is ASCII). Any |
156 | generate characters outside the code range C<0..127> (which is ASCII). Any |
157 | unicode characters outside that range will be escaped using either a |
157 | unicode characters outside that range will be escaped using either a |
158 | single \uXXXX (BMP characters) or a double \uHHHH\uLLLLL escape sequence, |
158 | single \uXXXX (BMP characters) or a double \uHHHH\uLLLLL escape sequence, |
159 | as per RFC4627. |
159 | as per RFC4627. The resulting encoded JSON text can be treated as a native |
|
|
160 | unicode string, an ascii-encoded, latin1-encoded or UTF-8 encoded string, |
|
|
161 | or any other superset of ASCII. |
160 | |
162 | |
161 | If C<$enable> is false, then the C<encode> method will not escape Unicode |
163 | If C<$enable> is false, then the C<encode> method will not escape Unicode |
162 | characters unless required by the JSON syntax. This results in a faster |
164 | characters unless required by the JSON syntax or other flags. This results |
163 | and more compact format. |
165 | in a faster and more compact format. |
|
|
166 | |
|
|
167 | The main use for this flag is to produce JSON texts that can be |
|
|
168 | transmitted over a 7-bit channel, as the encoded JSON texts will not |
|
|
169 | contain any 8 bit characters. |
164 | |
170 | |
165 | JSON::XS->new->ascii (1)->encode ([chr 0x10401]) |
171 | JSON::XS->new->ascii (1)->encode ([chr 0x10401]) |
166 | => ["\ud801\udc01"] |
172 | => ["\ud801\udc01"] |
|
|
173 | |
|
|
174 | =item $json = $json->latin1 ([$enable]) |
|
|
175 | |
|
|
176 | If C<$enable> is true (or missing), then the C<encode> method will encode |
|
|
177 | the resulting JSON text as latin1 (or iso-8859-1), escaping any characters |
|
|
178 | outside the code range C<0..255>. The resulting string can be treated as a |
|
|
179 | latin1-encoded JSON text or a native unicode string. The C<decode> method |
|
|
180 | will not be affected in any way by this flag, as C<decode> by default |
|
|
181 | expects unicode, which is a strict superset of latin1. |
|
|
182 | |
|
|
183 | If C<$enable> is false, then the C<encode> method will not escape Unicode |
|
|
184 | characters unless required by the JSON syntax or other flags. |
|
|
185 | |
|
|
186 | The main use for this flag is efficiently encoding binary data as JSON |
|
|
187 | text, as most octets will not be escaped, resulting in a smaller encoded |
|
|
188 | size. The disadvantage is that the resulting JSON text is encoded |
|
|
189 | in latin1 (and must correctly be treated as such when storing and |
|
|
190 | transfering), a rare encoding for JSON. It is therefore most useful when |
|
|
191 | you want to store data structures known to contain binary data efficiently |
|
|
192 | in files or databases, not when talking to other JSON encoders/decoders. |
|
|
193 | |
|
|
194 | JSON::XS->new->latin1->encode (["\x{89}\x{abc}"] |
|
|
195 | => ["\x{89}\\u0abc"] # (perl syntax, U+abc escaped, U+89 not) |
167 | |
196 | |
168 | =item $json = $json->utf8 ([$enable]) |
197 | =item $json = $json->utf8 ([$enable]) |
169 | |
198 | |
170 | If C<$enable> is true (or missing), then the C<encode> method will encode |
199 | If C<$enable> is true (or missing), then the C<encode> method will encode |
171 | the JSON result into UTF-8, as required by many protocols, while the |
200 | the JSON result into UTF-8, as required by many protocols, while the |
… | |
… | |
309 | strings that look like integers or floats into integers or floats |
338 | strings that look like integers or floats into integers or floats |
310 | internally (there is no difference on the Perl level), saving space. |
339 | internally (there is no difference on the Perl level), saving space. |
311 | |
340 | |
312 | =item $json = $json->max_depth ([$maximum_nesting_depth]) |
341 | =item $json = $json->max_depth ([$maximum_nesting_depth]) |
313 | |
342 | |
314 | Sets the maximum nesting level (default C<8192>) accepted while encoding |
343 | Sets the maximum nesting level (default C<512>) accepted while encoding |
315 | or decoding. If the JSON text or Perl data structure has an equal or |
344 | 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 |
345 | higher nesting level then this limit, then the encoder and decoder will |
317 | stop and croak at that point. |
346 | stop and croak at that point. |
318 | |
347 | |
319 | Nesting level is defined by number of hash- or arrayrefs that the encoder |
348 | Nesting level is defined by number of hash- or arrayrefs that the encoder |
… | |
… | |
410 | =over 4 |
439 | =over 4 |
411 | |
440 | |
412 | =item hash references |
441 | =item hash references |
413 | |
442 | |
414 | Perl hash references become JSON objects. As there is no inherent ordering |
443 | 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 |
444 | 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 |
445 | 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 |
446 | 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 |
447 | 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 |
448 | the same datastructure will serialise to the same JSON text (given same |
420 | JSON::XS), but this incurs a runtime overhead. |
449 | settings and version of JSON::XS), but this incurs a runtime overhead |
|
|
450 | and is only rarely useful, e.g. when you want to compare some JSON text |
|
|
451 | against another for equality. |
421 | |
452 | |
422 | =item array references |
453 | =item array references |
423 | |
454 | |
424 | Perl array references become JSON arrays. |
455 | Perl array references become JSON arrays. |
|
|
456 | |
|
|
457 | =item other references |
|
|
458 | |
|
|
459 | Other unblessed references are generally not allowed and will cause an |
|
|
460 | exception to be thrown, except for references to the integers C<0> and |
|
|
461 | C<1>, which get turned into C<false> and C<true> atoms in JSON. You can |
|
|
462 | also use C<JSON::XS::false> and C<JSON::XS::true> to improve readability. |
|
|
463 | |
|
|
464 | to_json [\0,JSON::XS::true] # yields [false,true] |
425 | |
465 | |
426 | =item blessed objects |
466 | =item blessed objects |
427 | |
467 | |
428 | Blessed objects are not allowed. JSON::XS currently tries to encode their |
468 | Blessed objects are not allowed. JSON::XS currently tries to encode their |
429 | underlying representation (hash- or arrayref), but this behaviour might |
469 | underlying representation (hash- or arrayref), but this behaviour might |
… | |
… | |
461 | $x += 0; # numify it, ensuring it will be dumped as a number |
501 | $x += 0; # numify it, ensuring it will be dumped as a number |
462 | $x *= 1; # same thing, the choise is yours. |
502 | $x *= 1; # same thing, the choise is yours. |
463 | |
503 | |
464 | You can not currently output JSON booleans or force the type in other, |
504 | You can not currently output JSON booleans or force the type in other, |
465 | less obscure, ways. Tell me if you need this capability. |
505 | 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 | |
506 | |
471 | =back |
507 | =back |
472 | |
508 | |
473 | |
509 | |
474 | =head1 COMPARISON |
510 | =head1 COMPARISON |
… | |
… | |
625 | usually a good indication of the size of the resources required to decode |
661 | usually a good indication of the size of the resources required to decode |
626 | it into a Perl structure. |
662 | it into a Perl structure. |
627 | |
663 | |
628 | Third, JSON::XS recurses using the C stack when decoding objects and |
664 | 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 |
665 | 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 |
666 | machine with 8MB of stack size I can decode around 180k nested arrays but |
631 | but only 14k nested JSON objects. If that is exceeded, the program |
667 | only 14k nested JSON objects (due to perl itself recursing deeply on croak |
|
|
668 | to free the temporary). If that is exceeded, the program crashes. to be |
632 | crashes. Thats why the default nesting limit is set to 8192. If your |
669 | conservative, the default nesting limit is set to 512. If your process |
633 | process has a smaller stack, you should adjust this setting accordingly |
670 | has a smaller stack, you should adjust this setting accordingly with the |
634 | with the C<max_depth> method. |
671 | C<max_depth> method. |
635 | |
672 | |
636 | And last but least, something else could bomb you that I forgot to think |
673 | 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, |
674 | of. In that case, you get to keep the pieces. I am always open for hints, |
638 | though... |
675 | though... |
639 | |
676 | |
640 | |
677 | |
641 | =head1 BUGS |
678 | =head1 BUGS |
642 | |
679 | |
… | |
… | |
645 | still relatively early in its development. If you keep reporting bugs they |
682 | still relatively early in its development. If you keep reporting bugs they |
646 | will be fixed swiftly, though. |
683 | will be fixed swiftly, though. |
647 | |
684 | |
648 | =cut |
685 | =cut |
649 | |
686 | |
|
|
687 | sub true() { \1 } |
|
|
688 | sub false() { \0 } |
|
|
689 | |
650 | 1; |
690 | 1; |
651 | |
691 | |
652 | =head1 AUTHOR |
692 | =head1 AUTHOR |
653 | |
693 | |
654 | Marc Lehmann <schmorp@schmorp.de> |
694 | Marc Lehmann <schmorp@schmorp.de> |