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.94 by root, Tue Mar 25 07:46:15 2008 UTC vs.
Revision 1.103 by root, Tue Apr 29 16:07:56 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
… …
683=back 701=back
684 702
685 703
686=head1 INCREMENTAL PARSING 704=head1 INCREMENTAL PARSING
687 705
688[This section is still EXPERIMENTAL] 706[This section and the API it details is still EXPERIMENTAL]
689 707
690In some cases, there is the need for incremental parsing of JSON 708In some cases, there is the need for incremental parsing of JSON
691texts. While this module always has to keep both JSON text and resulting 709texts. While this module always has to keep both JSON text and resulting
692Perl data structure in memory at one time, it does allow you to parse a 710Perl data structure in memory at one time, it does allow you to parse a
693JSON stream incrementally. It does so by accumulating text until it has 711JSON stream incrementally. It does so by accumulating text until it has
… …
714return without doing anything further. This can be used to add more text 732return without doing anything further. This can be used to add more text
715in as many chunks as you want. 733in as many chunks as you want.
716 734
717If the method is called in scalar context, then it will try to extract 735If the method is called in scalar context, then it will try to extract
718exactly I<one> JSON object. If that is successful, it will return this 736exactly I<one> JSON object. If that is successful, it will return this
719object, otherwise it will return C<undef>. This is the most common way of 737object, otherwise it will return C<undef>. If there is a parse error,
738this method will croak just as C<decode> would do (one can then use
739C<incr_skip> to skip the errornous part). This is the most common way of
720using the method. 740using the method.
721 741
722And finally, in list context, it will try to extract as many objects 742And finally, in list context, it will try to extract as many objects
723from the stream as it can find and return them, or the empty list 743from the stream as it can find and return them, or the empty list
724otherwise. For this to work, there must be no separators between the JSON 744otherwise. For this to work, there must be no separators between the JSON
725objects or arrays, instead they must be concatenated back-to-back. 745objects or arrays, instead they must be concatenated back-to-back. If
746an error occurs, an exception will be raised as in the scalar context
747case. Note that in this case, any previously-parsed JSON texts will be
748lost.
726 749
727=item $lvalue_string = $json->incr_text 750=item $lvalue_string = $json->incr_text
728 751
729This method returns the currently stored JSON fragment as an lvalue, that 752This method returns the currently stored JSON fragment as an lvalue, that
730is, you can manipulate it. This I<only> works when a preceding call to 753is, you can manipulate it. This I<only> works when a preceding call to
… …
735method before having parsed anything. 758method before having parsed anything.
736 759
737This function is useful in two cases: a) finding the trailing text after a 760This function is useful in two cases: a) finding the trailing text after a
738JSON object or b) parsing multiple JSON objects separated by non-JSON text 761JSON object or b) parsing multiple JSON objects separated by non-JSON text
739(such as commas). 762(such as commas).
763
764=item $json->incr_skip
765
766This will reset the state of the incremental parser and will remove the
767parsed text from the input buffer. This is useful after C<incr_parse>
768died, in which case the input buffer and incremental parser state is left
769unchanged, to skip the text parsed so far and to reset the parse state.
740 770
741=back 771=back
742 772
743=head2 LIMITATIONS 773=head2 LIMITATIONS
744 774
… …
1137proper subset of most 8-bit and multibyte encodings in use in the world. 1167proper subset of most 8-bit and multibyte encodings in use in the world.
1138 1168
1139=back 1169=back
1140 1170
1141 1171
1142=head1 COMPARISON
1143
1144As already mentioned, this module was created because none of the existing
1145JSON modules could be made to work correctly. First I will describe the
1146problems (or pleasures) I encountered with various existing JSON modules,
1147followed by some benchmark values. JSON::XS was designed not to suffer
1148from any of these problems or limitations.
1149
1150=over 4
1151
1152=item JSON 2.xx
1153
1154A marvellous piece of engineering, this module either uses JSON::XS
1155directly when available (so will be 100% compatible with it, including
1156speed), or it uses JSON::PP, which is basically JSON::XS translated to
1157Pure Perl, which should be 100% compatible with JSON::XS, just a bit
1158slower.
1159
1160You cannot really lose by using this module, especially as it tries very
1161hard to work even with ancient Perl versions, while JSON::XS does not.
1162
1163=item JSON 1.07
1164
1165Slow (but very portable, as it is written in pure Perl).
1166
1167Undocumented/buggy Unicode handling (how JSON handles Unicode values is
1168undocumented. One can get far by feeding it Unicode strings and doing
1169en-/decoding oneself, but Unicode escapes are not working properly).
1170
1171No round-tripping (strings get clobbered if they look like numbers, e.g.
1172the string C<2.0> will encode to C<2.0> instead of C<"2.0">, and that will
1173decode into the number 2.
1174
1175=item JSON::PC 0.01
1176
1177Very fast.
1178
1179Undocumented/buggy Unicode handling.
1180
1181No round-tripping.
1182
1183Has problems handling many Perl values (e.g. regex results and other magic
1184values will make it croak).
1185
1186Does not even generate valid JSON (C<{1,2}> gets converted to C<{1:2}>
1187which is not a valid JSON text.
1188
1189Unmaintained (maintainer unresponsive for many months, bugs are not
1190getting fixed).
1191
1192=item JSON::Syck 0.21
1193
1194Very buggy (often crashes).
1195
1196Very inflexible (no human-readable format supported, format pretty much
1197undocumented. I need at least a format for easy reading by humans and a
1198single-line compact format for use in a protocol, and preferably a way to
1199generate ASCII-only JSON texts).
1200
1201Completely broken (and confusingly documented) Unicode handling (Unicode
1202escapes are not working properly, you need to set ImplicitUnicode to
1203I<different> values on en- and decoding to get symmetric behaviour).
1204
1205No round-tripping (simple cases work, but this depends on whether the scalar
1206value was used in a numeric context or not).
1207
1208Dumping hashes may skip hash values depending on iterator state.
1209
1210Unmaintained (maintainer unresponsive for many months, bugs are not
1211getting fixed).
1212
1213Does not check input for validity (i.e. will accept non-JSON input and
1214return "something" instead of raising an exception. This is a security
1215issue: imagine two banks transferring money between each other using
1216JSON. One bank might parse a given non-JSON request and deduct money,
1217while the other might reject the transaction with a syntax error. While a
1218good protocol will at least recover, that is extra unnecessary work and
1219the transaction will still not succeed).
1220
1221=item JSON::DWIW 0.04
1222
1223Very fast. Very natural. Very nice.
1224
1225Undocumented Unicode handling (but the best of the pack. Unicode escapes
1226still don't get parsed properly).
1227
1228Very inflexible.
1229
1230No round-tripping.
1231
1232Does not generate valid JSON texts (key strings are often unquoted, empty keys
1233result in nothing being output)
1234
1235Does not check input for validity.
1236
1237=back
1238
1239
1240=head2 JSON and YAML 1172=head2 JSON and YAML
1241 1173
1242You often hear that JSON is a subset of YAML. This is, however, a mass 1174You often hear that JSON is a subset of YAML. This is, however, a mass
1243hysteria(*) and very far from the truth (as of the time of this writing), 1175hysteria(*) and very far from the truth (as of the time of this writing),
1244so let me state it clearly: I<in general, there is no way to configure 1176so let me state it clearly: I<in general, there is no way to configure
… …
1300 1232
1301First comes a comparison between various modules using 1233First comes a comparison between various modules using
1302a very short single-line JSON string (also available at 1234a very short single-line JSON string (also available at
1303L<http://dist.schmorp.de/misc/json/short.json>). 1235L<http://dist.schmorp.de/misc/json/short.json>).
1304 1236
1305 {"method": "handleMessage", "params": ["user1", "we were just talking"], \ 1237 {"method": "handleMessage", "params": ["user1",
1306 "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]}
1307 1240
1308It shows the number of encodes/decodes per second (JSON::XS uses 1241It shows the number of encodes/decodes per second (JSON::XS uses
1309the functional interface, while JSON::XS/2 uses the OO interface 1242the functional interface, while JSON::XS/2 uses the OO interface
1310with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables 1243with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables
1311shrink). Higher is better: 1244shrink). Higher is better:
… …
1409 1342
1410 1343
1411=head1 BUGS 1344=head1 BUGS
1412 1345
1413While 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
1414not 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
1415still relatively early in its development. If you keep reporting bugs they 1348keep reporting bugs they will be fixed swiftly, though.
1416will be fixed swiftly, though.
1417 1349
1418Please refrain from using rt.cpan.org or any other bug reporting 1350Please refrain from using rt.cpan.org or any other bug reporting
1419service. I put the contact address into my modules for a reason. 1351service. I put the contact address into my modules for a reason.
1420 1352
1421=cut 1353=cut

Diff Legend

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