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.100 by root, Sun Mar 30 09:27:16 2008 UTC vs.
Revision 1.105 by root, Sat May 24 21:55:43 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
… …
37primary goal is to be I<correct> and its secondary goal is to be 37primary goal is to be I<correct> and its secondary goal is to be
38I<fast>. To reach the latter goal it was written in C. 38I<fast>. To reach the latter goal it was written in C.
39 39
40Beginning with version 2.0 of the JSON module, when both JSON and 40Beginning with version 2.0 of the JSON module, when both JSON and
41JSON::XS are installed, then JSON will fall back on JSON::XS (this can be 41JSON::XS are installed, then JSON will fall back on JSON::XS (this can be
42overriden) with no overhead due to emulation (by inheritign constructor 42overridden) with no overhead due to emulation (by inheriting constructor
43and methods). If JSON::XS is not available, it will fall back to the 43and methods). If JSON::XS is not available, it will fall back to the
44compatible JSON::PP module as backend, so using JSON instead of JSON::XS 44compatible JSON::PP module as backend, so using JSON instead of JSON::XS
45gives you a portable JSON API that can be fast when you need and doesn't 45gives you a portable JSON API that can be fast when you need and doesn't
46require a C compiler when that is a problem. 46require a C compiler when that is a problem.
47 47
… …
65This module knows how to handle Unicode, documents how and when it does 65This module knows how to handle Unicode, documents how and when it does
66so, and even documents what "correct" means. 66so, and even documents what "correct" means.
67 67
68=item * round-trip integrity 68=item * round-trip integrity
69 69
70When you serialise a perl data structure using only datatypes supported 70When you serialise a perl data structure using only data types supported
71by JSON, the deserialised data structure is identical on the Perl level. 71by JSON, the deserialised data structure is identical on the Perl level.
72(e.g. the string "2.0" doesn't suddenly become "2" just because it looks 72(e.g. the string "2.0" doesn't suddenly become "2" just because it looks
73like a number). There minor I<are> exceptions to this, read the MAPPING 73like a number). There minor I<are> exceptions to this, read the MAPPING
74section below to learn about those. 74section below to learn about those.
75 75
… …
84Compared to other JSON modules and other serialisers such as Storable, 84Compared to other JSON modules and other serialisers such as Storable,
85this module usually compares favourably in terms of speed, too. 85this module usually compares favourably in terms of speed, too.
86 86
87=item * simple to use 87=item * simple to use
88 88
89This module has both a simple functional interface as well as an objetc 89This module has both a simple functional interface as well as an object
90oriented interface interface. 90oriented interface interface.
91 91
92=item * reasonably versatile output formats 92=item * reasonably versatile output formats
93 93
94You can choose between the most compact guaranteed-single-line format 94You can choose between the most compact guaranteed-single-line format
95possible (nice for simple line-based protocols), a pure-ascii format 95possible (nice for simple line-based protocols), a pure-ASCII format
96(for when your transport is not 8-bit clean, still supports the whole 96(for when your transport is not 8-bit clean, still supports the whole
97Unicode range), or a pretty-printed format (for when you want to read that 97Unicode range), or a pretty-printed format (for when you want to read that
98stuff). Or you can combine those features in whatever way you like. 98stuff). Or you can combine those features in whatever way you like.
99 99
100=back 100=back
… …
137 137
138This function call is functionally identical to: 138This function call is functionally identical to:
139 139
140 $json_text = JSON::XS->new->utf8->encode ($perl_scalar) 140 $json_text = JSON::XS->new->utf8->encode ($perl_scalar)
141 141
142except being faster. 142Except being faster.
143 143
144=item $perl_scalar = decode_json $json_text 144=item $perl_scalar = decode_json $json_text
145 145
146The opposite of C<encode_json>: expects an UTF-8 (binary) string and tries 146The opposite of C<encode_json>: expects an UTF-8 (binary) string and tries
147to parse that as an UTF-8 encoded JSON text, returning the resulting 147to parse that as an UTF-8 encoded JSON text, returning the resulting
… …
149 149
150This function call is functionally identical to: 150This function call is functionally identical to:
151 151
152 $perl_scalar = JSON::XS->new->utf8->decode ($json_text) 152 $perl_scalar = JSON::XS->new->utf8->decode ($json_text)
153 153
154except being faster. 154Except being faster.
155 155
156=item $is_boolean = JSON::XS::is_bool $scalar 156=item $is_boolean = JSON::XS::is_bool $scalar
157 157
158Returns true if the passed scalar represents either JSON::XS::true or 158Returns true if the passed scalar represents either JSON::XS::true or
159JSON::XS::false, two constants that act like C<1> and C<0>, respectively 159JSON::XS::false, two constants that act like C<1> and C<0>, respectively
… …
197 197
198If you didn't know about that flag, just the better, pretend it doesn't 198If you didn't know about that flag, just the better, pretend it doesn't
199exist. 199exist.
200 200
201=item 4. A "Unicode String" is simply a string where each character can be 201=item 4. A "Unicode String" is simply a string where each character can be
202validly interpreted as a Unicode codepoint. 202validly interpreted as a Unicode code point.
203 203
204If you have UTF-8 encoded data, it is no longer a Unicode string, but a 204If you have UTF-8 encoded data, it is no longer a Unicode string, but a
205Unicode string encoded in UTF-8, giving you a binary string. 205Unicode string encoded in UTF-8, giving you a binary string.
206 206
207=item 5. A string containing "high" (> 255) character values is I<not> a UTF-8 string. 207=item 5. A string containing "high" (> 255) character values is I<not> a UTF-8 string.
… …
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
… …
698 700
699=back 701=back
700 702
701 703
702=head1 INCREMENTAL PARSING 704=head1 INCREMENTAL PARSING
703
704[This section and the API it details is still EXPERIMENTAL]
705 705
706In some cases, there is the need for incremental parsing of JSON 706In some cases, there is the need for incremental parsing of JSON
707texts. While this module always has to keep both JSON text and resulting 707texts. While this module always has to keep both JSON text and resulting
708Perl data structure in memory at one time, it does allow you to parse a 708Perl data structure in memory at one time, it does allow you to parse a
709JSON stream incrementally. It does so by accumulating text until it has 709JSON stream incrementally. It does so by accumulating text until it has
… …
1013Other unblessed references are generally not allowed and will cause an 1013Other unblessed references are generally not allowed and will cause an
1014exception to be thrown, except for references to the integers C<0> and 1014exception 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 1015C<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. 1016also use C<JSON::XS::false> and C<JSON::XS::true> to improve readability.
1017 1017
1018 encode_json [\0,JSON::XS::true] # yields [false,true] 1018 encode_json [\0, JSON::XS::true] # yields [false,true]
1019 1019
1020=item JSON::XS::true, JSON::XS::false 1020=item JSON::XS::true, JSON::XS::false
1021 1021
1022These special values become JSON true and JSON false values, 1022These special values become JSON true and JSON false values,
1023respectively. You can also use C<\1> and C<\0> directly if you want. 1023respectively. You can also use C<\1> and C<\0> directly if you want.
… …
1340 1340
1341 1341
1342=head1 BUGS 1342=head1 BUGS
1343 1343
1344While the goal of this module is to be correct, that unfortunately does 1344While the goal of this module is to be correct, that unfortunately does
1345not mean it's bug-free, only that I think its design is bug-free. It is 1345not mean it's bug-free, only that I think its design is bug-free. If you
1346still relatively early in its development. If you keep reporting bugs they 1346keep reporting bugs they will be fixed swiftly, though.
1347will be fixed swiftly, though.
1348 1347
1349Please refrain from using rt.cpan.org or any other bug reporting 1348Please refrain from using rt.cpan.org or any other bug reporting
1350service. I put the contact address into my modules for a reason. 1349service. I put the contact address into my modules for a reason.
1351 1350
1352=cut 1351=cut

Diff Legend

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