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.96 by root, Wed Mar 26 01:40:42 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
… …
727objects or arrays, instead they must be concatenated back-to-back. If 743objects or arrays, instead they must be concatenated back-to-back. If
728an error occurs, an exception will be raised as in the scalar context 744an error occurs, an exception will be raised as in the scalar context
729case. Note that in this case, any previously-parsed JSON texts will be 745case. Note that in this case, any previously-parsed JSON texts will be
730lost. 746lost.
731 747
732If there is a parse
733
734=item $lvalue_string = $json->incr_text 748=item $lvalue_string = $json->incr_text
735 749
736This method returns the currently stored JSON fragment as an lvalue, that 750This method returns the currently stored JSON fragment as an lvalue, that
737is, 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
738C<incr_parse> in I<scalar context> successfully returned an object. Under 752C<incr_parse> in I<scalar context> successfully returned an object. Under
… …
742method before having parsed anything. 756method before having parsed anything.
743 757
744This 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
745JSON 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
746(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.
747 768
748=back 769=back
749 770
750=head2 LIMITATIONS 771=head2 LIMITATIONS
751 772
… …
1209 1230
1210First comes a comparison between various modules using 1231First comes a comparison between various modules using
1211a very short single-line JSON string (also available at 1232a very short single-line JSON string (also available at
1212L<http://dist.schmorp.de/misc/json/short.json>). 1233L<http://dist.schmorp.de/misc/json/short.json>).
1213 1234
1214 {"method": "handleMessage", "params": ["user1", "we were just talking"], \ 1235 {"method": "handleMessage", "params": ["user1",
1215 "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]}
1216 1238
1217It shows the number of encodes/decodes per second (JSON::XS uses 1239It shows the number of encodes/decodes per second (JSON::XS uses
1218the functional interface, while JSON::XS/2 uses the OO interface 1240the functional interface, while JSON::XS/2 uses the OO interface
1219with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables 1241with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables
1220shrink). Higher is better: 1242shrink). Higher is better:

Diff Legend

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