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.98 by root, Wed Mar 26 02:36:18 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
… …
103 103
104package JSON::XS; 104package JSON::XS;
105 105
106use strict; 106use strict;
107 107
108our $VERSION = '2.1'; 108our $VERSION = '2.2';
109our @ISA = qw(Exporter); 109our @ISA = qw(Exporter);
110 110
111our @EXPORT = qw(encode_json decode_json to_json from_json); 111our @EXPORT = qw(encode_json decode_json to_json from_json);
112 112
113sub to_json($) { 113sub to_json($) {
… …
462Example, encode a Perl scalar as JSON value with enabled C<allow_nonref>, 462Example, encode a Perl scalar as JSON value with enabled C<allow_nonref>,
463resulting in an invalid JSON text: 463resulting in an invalid JSON text:
464 464
465 JSON::XS->new->allow_nonref->encode ("Hello, World!") 465 JSON::XS->new->allow_nonref->encode ("Hello, World!")
466 => "Hello, World!" 466 => "Hello, World!"
467
468=item $json = $json->allow_unknown ([$enable])
469
470=item $enabled = $json->get_allow_unknown
471
472If C<$enable> is true (or missing), then C<encode> will I<not> throw an
473exception when it encounters values it cannot represent in JSON (for
474example, filehandles) but instead will encode a JSON C<null> value. Note
475that blessed objects are not included here and are handled separately by
476c<allow_nonref>.
477
478If C<$enable> is false (the default), then C<encode> will throw an
479exception when it encounters anything it cannot encode as JSON.
480
481This option does not affect C<decode> in any way, and it is recommended to
482leave it off unless you know your communications partner.
467 483
468=item $json = $json->allow_blessed ([$enable]) 484=item $json = $json->allow_blessed ([$enable])
469 485
470=item $enabled = $json->get_allow_blessed 486=item $enabled = $json->get_allow_blessed
471 487
… …
612=item $json = $json->max_depth ([$maximum_nesting_depth]) 628=item $json = $json->max_depth ([$maximum_nesting_depth])
613 629
614=item $max_depth = $json->get_max_depth 630=item $max_depth = $json->get_max_depth
615 631
616Sets the maximum nesting level (default C<512>) accepted while encoding 632Sets the maximum nesting level (default C<512>) accepted while encoding
617or 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
618higher nesting level then this limit, then the encoder and decoder will 634data structure, then the encoder and decoder will stop and croak at that
619stop and croak at that point. 635point.
620 636
621Nesting 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
622needs 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<[>
623characters without their matching closing parenthesis crossed to reach a 639characters without their matching closing parenthesis crossed to reach a
624given character in a string. 640given character in a string.
625 641
626Setting the maximum depth to one disallows any nesting, so that ensures 642Setting the maximum depth to one disallows any nesting, so that ensures
627that the object is only a single hash/object or array. 643that the object is only a single hash/object or array.
628 644
629The argument to C<max_depth> will be rounded up to the next highest power
630of 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
631used, 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.
632 651
633See SECURITY CONSIDERATIONS, below, for more info on why this is useful. 652See SECURITY CONSIDERATIONS, below, for more info on why this is useful.
634 653
635=item $json = $json->max_size ([$maximum_string_size]) 654=item $json = $json->max_size ([$maximum_string_size])
636 655
637=item $max_size = $json->get_max_size 656=item $max_size = $json->get_max_size
638 657
639Set 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
640being 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>
641is 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
642attempt 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
643effect on C<encode> (yet). 662effect on C<encode> (yet).
644 663
645The 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
646power of two (so may be more than requested). If no argument is given, the 665C<0> is specified).
647limit check will be deactivated (same as when C<0> is specified).
648 666
649See SECURITY CONSIDERATIONS, below, for more info on why this is useful. 667See SECURITY CONSIDERATIONS, below, for more info on why this is useful.
650 668
651=item $json_text = $json->encode ($perl_scalar) 669=item $json_text = $json->encode ($perl_scalar)
652 670
… …
997Other unblessed references are generally not allowed and will cause an 1015Other unblessed references are generally not allowed and will cause an
998exception 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
999C<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
1000also 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.
1001 1019
1002 encode_json [\0,JSON::XS::true] # yields [false,true] 1020 encode_json [\0, JSON::XS::true] # yields [false,true]
1003 1021
1004=item JSON::XS::true, JSON::XS::false 1022=item JSON::XS::true, JSON::XS::false
1005 1023
1006These special values become JSON true and JSON false values, 1024These special values become JSON true and JSON false values,
1007respectively. 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.
… …
1214 1232
1215First comes a comparison between various modules using 1233First comes a comparison between various modules using
1216a very short single-line JSON string (also available at 1234a very short single-line JSON string (also available at
1217L<http://dist.schmorp.de/misc/json/short.json>). 1235L<http://dist.schmorp.de/misc/json/short.json>).
1218 1236
1219 {"method": "handleMessage", "params": ["user1", "we were just talking"], \ 1237 {"method": "handleMessage", "params": ["user1",
1220 "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]}
1221 1240
1222It shows the number of encodes/decodes per second (JSON::XS uses 1241It shows the number of encodes/decodes per second (JSON::XS uses
1223the functional interface, while JSON::XS/2 uses the OO interface 1242the functional interface, while JSON::XS/2 uses the OO interface
1224with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables 1243with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables
1225shrink). Higher is better: 1244shrink). Higher is better:
… …
1323 1342
1324 1343
1325=head1 BUGS 1344=head1 BUGS
1326 1345
1327While 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
1328not 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
1329still relatively early in its development. If you keep reporting bugs they 1348keep reporting bugs they will be fixed swiftly, though.
1330will be fixed swiftly, though.
1331 1349
1332Please refrain from using rt.cpan.org or any other bug reporting 1350Please refrain from using rt.cpan.org or any other bug reporting
1333service. I put the contact address into my modules for a reason. 1351service. I put the contact address into my modules for a reason.
1334 1352
1335=cut 1353=cut

Diff Legend

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