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.95 by root, Tue Mar 25 16:56:09 2008 UTC vs.
Revision 1.100 by root, Sun Mar 30 09:27:16 2008 UTC

… …
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
… …
683=back 699=back
684 700
685 701
686=head1 INCREMENTAL PARSING 702=head1 INCREMENTAL PARSING
687 703
688[This section is still EXPERIMENTAL] 704[This section and the API it details is still EXPERIMENTAL]
689 705
690In some cases, there is the need for incremental parsing of JSON 706In some cases, there is the need for incremental parsing of JSON
691texts. 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
692Perl 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
693JSON stream incrementally. It does so by accumulating text until it has 709JSON stream incrementally. It does so by accumulating text until it has
… …
714return without doing anything further. This can be used to add more text 730return without doing anything further. This can be used to add more text
715in as many chunks as you want. 731in as many chunks as you want.
716 732
717If the method is called in scalar context, then it will try to extract 733If 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 734exactly 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 735object, otherwise it will return C<undef>. If there is a parse error,
736this method will croak just as C<decode> would do (one can then use
737C<incr_skip> to skip the errornous part). This is the most common way of
720using the method. 738using the method.
721 739
722And finally, in list context, it will try to extract as many objects 740And 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 741from 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 742otherwise. For this to work, there must be no separators between the JSON
725objects or arrays, instead they must be concatenated back-to-back. 743objects or arrays, instead they must be concatenated back-to-back. If
744an error occurs, an exception will be raised as in the scalar context
745case. Note that in this case, any previously-parsed JSON texts will be
746lost.
726 747
727=item $lvalue_string = $json->incr_text 748=item $lvalue_string = $json->incr_text
728 749
729This method returns the currently stored JSON fragment as an lvalue, that 750This 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 751is, you can manipulate it. This I<only> works when a preceding call to
… …
735method before having parsed anything. 756method before having parsed anything.
736 757
737This function is useful in two cases: a) finding the trailing text after a 758This 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 759JSON object or b) parsing multiple JSON objects separated by non-JSON text
739(such as commas). 760(such as commas).
761
762=item $json->incr_skip
763
764This will reset the state of the incremental parser and will remove the
765parsed text from the input buffer. This is useful after C<incr_parse>
766died, in which case the input buffer and incremental parser state is left
767unchanged, to skip the text parsed so far and to reset the parse state.
740 768
741=back 769=back
742 770
743=head2 LIMITATIONS 771=head2 LIMITATIONS
744 772
… …
1202 1230
1203First comes a comparison between various modules using 1231First comes a comparison between various modules using
1204a very short single-line JSON string (also available at 1232a very short single-line JSON string (also available at
1205L<http://dist.schmorp.de/misc/json/short.json>). 1233L<http://dist.schmorp.de/misc/json/short.json>).
1206 1234
1207 {"method": "handleMessage", "params": ["user1", "we were just talking"], \ 1235 {"method": "handleMessage", "params": ["user1",
1208 "id": null, "array":[1,11,234,-5,1e5,1e7, true, false]} 1236 "we were just talking"], "id": null, "array":[1,11,234,-5,1e5,1e7,
1237 true, false]}
1209 1238
1210It shows the number of encodes/decodes per second (JSON::XS uses 1239It shows the number of encodes/decodes per second (JSON::XS uses
1211the functional interface, while JSON::XS/2 uses the OO interface 1240the functional interface, while JSON::XS/2 uses the OO interface
1212with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables 1241with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables
1213shrink). Higher is better: 1242shrink). Higher is better:

Diff Legend

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