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.21 by root, Sun Mar 25 02:32:40 2007 UTC vs.
Revision 1.23 by root, Sun Mar 25 21:19:13 2007 UTC

… …
4 4
5=head1 SYNOPSIS 5=head1 SYNOPSIS
6 6
7 use JSON::XS; 7 use JSON::XS;
8 8
9 # exported functions, croak on error 9 # exported functions, they croak on error
10 # and expect/generate UTF-8
10 11
11 $utf8_encoded_json_text = to_json $perl_hash_or_arrayref; 12 $utf8_encoded_json_text = to_json $perl_hash_or_arrayref;
12 $perl_hash_or_arrayref = from_json $utf8_encoded_json_text; 13 $perl_hash_or_arrayref = from_json $utf8_encoded_json_text;
13 14
14 # objToJson and jsonToObj are exported for JSON 15 # objToJson and jsonToObj aliases to to_json and from_json
16 # are exported for compatibility to the JSON module,
15 # compatibility, but should not be used in new code. 17 # but should not be used in new code.
16 18
17 # oo-interface 19 # OO-interface
18 20
19 $coder = JSON::XS->new->ascii->pretty->allow_nonref; 21 $coder = JSON::XS->new->ascii->pretty->allow_nonref;
20 $pretty_printed_unencoded = $coder->encode ($perl_scalar); 22 $pretty_printed_unencoded = $coder->encode ($perl_scalar);
21 $perl_scalar = $coder->decode ($unicode_json_text); 23 $perl_scalar = $coder->decode ($unicode_json_text);
22 24
… …
126 $perl_scalar = JSON::XS->new->utf8->decode ($json_text) 128 $perl_scalar = JSON::XS->new->utf8->decode ($json_text)
127 129
128except being faster. 130except being faster.
129 131
130=back 132=back
133
131 134
132=head1 OBJECT-ORIENTED INTERFACE 135=head1 OBJECT-ORIENTED INTERFACE
133 136
134The object oriented interface lets you configure your own encoding or 137The object oriented interface lets you configure your own encoding or
135decoding style, within the limits of supported formats. 138decoding style, within the limits of supported formats.
… …
299 302
300In the future, this setting might control other things, such as converting 303In the future, this setting might control other things, such as converting
301strings that look like integers or floats into integers or floats 304strings that look like integers or floats into integers or floats
302internally (there is no difference on the Perl level), saving space. 305internally (there is no difference on the Perl level), saving space.
303 306
307=item $json = $json->max_depth ([$maximum_nesting_depth])
308
309Sets the maximum nesting level (default C<8192>) accepted while encoding
310or decoding. If the JSON text or Perl data structure has an equal or
311higher nesting level then this limit, then the encoder and decoder will
312stop and croak at that point.
313
314Nesting level is defined by number of hash- or arrayrefs that the encoder
315needs to traverse to reach a given point or the number of C<{> or C<[>
316characters without their matching closing parenthesis crossed to reach a
317given character in a string.
318
319Setting the maximum depth to one disallows any nesting, so that ensures
320that the object is only a single hash/object or array.
321
322The argument to C<max_depth> will be rounded up to the next nearest power
323of two.
324
325See SECURITY CONSIDERATIONS, below, for more info on why this is useful.
326
304=item $json_text = $json->encode ($perl_scalar) 327=item $json_text = $json->encode ($perl_scalar)
305 328
306Converts the given Perl data structure (a simple scalar or a reference 329Converts the given Perl data structure (a simple scalar or a reference
307to a hash or array) to its JSON representation. Simple scalars will be 330to a hash or array) to its JSON representation. Simple scalars will be
308converted into JSON string or number sequences, while references to arrays 331converted into JSON string or number sequences, while references to arrays
… …
318JSON numbers and strings become simple Perl scalars. JSON arrays become 341JSON numbers and strings become simple Perl scalars. JSON arrays become
319Perl arrayrefs and JSON objects become Perl hashrefs. C<true> becomes 342Perl arrayrefs and JSON objects become Perl hashrefs. C<true> becomes
320C<1>, C<false> becomes C<0> and C<null> becomes C<undef>. 343C<1>, C<false> becomes C<0> and C<null> becomes C<undef>.
321 344
322=back 345=back
346
323 347
324=head1 MAPPING 348=head1 MAPPING
325 349
326This section describes how JSON::XS maps Perl values to JSON values and 350This section describes how JSON::XS maps Perl values to JSON values and
327vice versa. These mappings are designed to "do the right thing" in most 351vice versa. These mappings are designed to "do the right thing" in most
… …
438=item circular data structures 462=item circular data structures
439 463
440Those will be encoded until memory or stackspace runs out. 464Those will be encoded until memory or stackspace runs out.
441 465
442=back 466=back
467
443 468
444=head1 COMPARISON 469=head1 COMPARISON
445 470
446As already mentioned, this module was created because none of the existing 471As already mentioned, this module was created because none of the existing
447JSON modules could be made to work correctly. First I will describe the 472JSON modules could be made to work correctly. First I will describe the
… …
576(such as JSON::PC) seem to decode faster than JSON::XS, but the result 601(such as JSON::PC) seem to decode faster than JSON::XS, but the result
577will be broken due to missing (or wrong) unicode handling. Others refuse 602will be broken due to missing (or wrong) unicode handling. Others refuse
578to decode or encode properly, so it was impossible to prepare a fair 603to decode or encode properly, so it was impossible to prepare a fair
579comparison table for that case. 604comparison table for that case.
580 605
581=head1 RESOURCE LIMITS
582 606
583JSON::XS does not impose any limits on the size of JSON texts or Perl 607=head1 SECURITY CONSIDERATIONS
584values they represent - if your machine can handle it, JSON::XS will 608
585encode or decode it. Future versions might optionally impose structure 609When you are using JSON in a protocol, talking to untrusted potentially
586depth and memory use resource limits. 610hostile creatures requires relatively few measures.
611
612First of all, your JSON decoder should be secure, that is, should not have
613any buffer overflows. Obviously, this module should ensure that and I am
614trying hard on making that true, but you never know.
615
616Second, you need to avoid resource-starving attacks. That means you should
617limit the size of JSON texts you accept, or make sure then when your
618resources run out, thats just fine (e.g. by using a separate process that
619can crash safely). The size of a JSON text in octets or characters is
620usually a good indication of the size of the resources required to decode
621it into a Perl structure.
622
623Third, JSON::XS recurses using the C stack when decoding objects and
624arrays. The C stack is a limited resource: for instance, on my amd64
625machine with 8MB of stack size I can decode around 180k nested arrays
626but only 14k nested JSON objects. If that is exceeded, the program
627crashes. Thats why the default nesting limit is set to 8192. If your
628process has a smaller stack, you should adjust this setting accordingly
629with the C<max_depth> method.
630
631And last but least, something else could bomb you that I forgot to think
632of. In that case, you get to keep the pieces. I am alway sopen for hints,
633though...
634
587 635
588=head1 BUGS 636=head1 BUGS
589 637
590While the goal of this module is to be correct, that unfortunately does 638While the goal of this module is to be correct, that unfortunately does
591not mean its bug-free, only that I think its design is bug-free. It is 639not mean its bug-free, only that I think its design is bug-free. It is
592still very young and not well-tested. If you keep reporting bugs they will 640still relatively early in its development. If you keep reporting bugs they
593be fixed swiftly, though. 641will be fixed swiftly, though.
594 642
595=cut 643=cut
596 644
5971; 6451;
598 646

Diff Legend

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