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.99 by root, Thu Mar 27 06:37:35 2008 UTC vs.
Revision 1.104 by root, Thu May 8 15:33:06 2008 UTC

1=head1 NAME 1=head1 NAME
2 2
3JSON::XS - JSON serialising/deserialising, done correctly and fast
4
3=encoding utf-8 5=encoding utf-8
4
5JSON::XS - JSON serialising/deserialising, done correctly and fast
6 6
7JSON::XS - 正しくて高速な JSON シリアライザ/デシリアライザ 7JSON::XS - 正しくて高速な JSON シリアライザ/デシリアライザ
8 (http://fleur.hio.jp/perldoc/mix/lib/JSON/XS.html) 8 (http://fleur.hio.jp/perldoc/mix/lib/JSON/XS.html)
9 9
10=head1 SYNOPSIS 10=head1 SYNOPSIS
… …
628=item $json = $json->max_depth ([$maximum_nesting_depth]) 628=item $json = $json->max_depth ([$maximum_nesting_depth])
629 629
630=item $max_depth = $json->get_max_depth 630=item $max_depth = $json->get_max_depth
631 631
632Sets the maximum nesting level (default C<512>) accepted while encoding 632Sets the maximum nesting level (default C<512>) accepted while encoding
633or decoding. If the JSON text or Perl data structure has an equal or 633or decoding. If a higher nesting level is detected in JSON text or a Perl
634higher nesting level then this limit, then the encoder and decoder will 634data structure, then the encoder and decoder will stop and croak at that
635stop and croak at that point. 635point.
636 636
637Nesting level is defined by number of hash- or arrayrefs that the encoder 637Nesting level is defined by number of hash- or arrayrefs that the encoder
638needs to traverse to reach a given point or the number of C<{> or C<[> 638needs to traverse to reach a given point or the number of C<{> or C<[>
639characters without their matching closing parenthesis crossed to reach a 639characters without their matching closing parenthesis crossed to reach a
640given character in a string. 640given character in a string.
641 641
642Setting the maximum depth to one disallows any nesting, so that ensures 642Setting the maximum depth to one disallows any nesting, so that ensures
643that the object is only a single hash/object or array. 643that the object is only a single hash/object or array.
644 644
645The argument to C<max_depth> will be rounded up to the next highest power
646of two. If no argument is given, the highest possible setting will be 645If no argument is given, the highest possible setting will be used, which
647used, which is rarely useful. 646is rarely useful.
647
648Note that nesting is implemented by recursion in C. The default value has
649been chosen to be as large as typical operating systems allow without
650crashing.
648 651
649See SECURITY CONSIDERATIONS, below, for more info on why this is useful. 652See SECURITY CONSIDERATIONS, below, for more info on why this is useful.
650 653
651=item $json = $json->max_size ([$maximum_string_size]) 654=item $json = $json->max_size ([$maximum_string_size])
652 655
653=item $max_size = $json->get_max_size 656=item $max_size = $json->get_max_size
654 657
655Set the maximum length a JSON text may have (in bytes) where decoding is 658Set the maximum length a JSON text may have (in bytes) where decoding is
656being attempted. The default is C<0>, meaning no limit. When C<decode> 659being attempted. The default is C<0>, meaning no limit. When C<decode>
657is called on a string longer then this number of characters it will not 660is called on a string that is longer then this many bytes, it will not
658attempt to decode the string but throw an exception. This setting has no 661attempt to decode the string but throw an exception. This setting has no
659effect on C<encode> (yet). 662effect on C<encode> (yet).
660 663
661The argument to C<max_size> will be rounded up to the next B<highest> 664If no argument is given, the limit check will be deactivated (same as when
662power of two (so may be more than requested). If no argument is given, the 665C<0> is specified).
663limit check will be deactivated (same as when C<0> is specified).
664 666
665See SECURITY CONSIDERATIONS, below, for more info on why this is useful. 667See SECURITY CONSIDERATIONS, below, for more info on why this is useful.
666 668
667=item $json_text = $json->encode ($perl_scalar) 669=item $json_text = $json->encode ($perl_scalar)
668 670
… …
1013Other unblessed references are generally not allowed and will cause an 1015Other unblessed references are generally not allowed and will cause an
1014exception to be thrown, except for references to the integers C<0> and 1016exception to be thrown, except for references to the integers C<0> and
1015C<1>, which get turned into C<false> and C<true> atoms in JSON. You can 1017C<1>, which get turned into C<false> and C<true> atoms in JSON. You can
1016also use C<JSON::XS::false> and C<JSON::XS::true> to improve readability. 1018also use C<JSON::XS::false> and C<JSON::XS::true> to improve readability.
1017 1019
1018 encode_json [\0,JSON::XS::true] # yields [false,true] 1020 encode_json [\0, JSON::XS::true] # yields [false,true]
1019 1021
1020=item JSON::XS::true, JSON::XS::false 1022=item JSON::XS::true, JSON::XS::false
1021 1023
1022These special values become JSON true and JSON false values, 1024These special values become JSON true and JSON false values,
1023respectively. You can also use C<\1> and C<\0> directly if you want. 1025respectively. You can also use C<\1> and C<\0> directly if you want.
… …
1230 1232
1231First comes a comparison between various modules using 1233First comes a comparison between various modules using
1232a very short single-line JSON string (also available at 1234a very short single-line JSON string (also available at
1233L<http://dist.schmorp.de/misc/json/short.json>). 1235L<http://dist.schmorp.de/misc/json/short.json>).
1234 1236
1235 {"method": "handleMessage", "params": ["user1", "we were just talking"], \ 1237 {"method": "handleMessage", "params": ["user1",
1236 "id": null, "array":[1,11,234,-5,1e5,1e7, true, false]} 1238 "we were just talking"], "id": null, "array":[1,11,234,-5,1e5,1e7,
1239 true, false]}
1237 1240
1238It shows the number of encodes/decodes per second (JSON::XS uses 1241It shows the number of encodes/decodes per second (JSON::XS uses
1239the functional interface, while JSON::XS/2 uses the OO interface 1242the functional interface, while JSON::XS/2 uses the OO interface
1240with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables 1243with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables
1241shrink). Higher is better: 1244shrink). Higher is better:
… …
1339 1342
1340 1343
1341=head1 BUGS 1344=head1 BUGS
1342 1345
1343While the goal of this module is to be correct, that unfortunately does 1346While the goal of this module is to be correct, that unfortunately does
1344not mean it's bug-free, only that I think its design is bug-free. It is 1347not mean it's bug-free, only that I think its design is bug-free. If you
1345still relatively early in its development. If you keep reporting bugs they 1348keep reporting bugs they will be fixed swiftly, though.
1346will be fixed swiftly, though.
1347 1349
1348Please refrain from using rt.cpan.org or any other bug reporting 1350Please refrain from using rt.cpan.org or any other bug reporting
1349service. I put the contact address into my modules for a reason. 1351service. I put the contact address into my modules for a reason.
1350 1352
1351=cut 1353=cut

Diff Legend

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