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.105 by root, Sat May 24 21:55:43 2008 UTC vs.
Revision 1.111 by root, Mon Jul 21 02:45:17 2008 UTC

… …
49to write yet another JSON module? While it seems there are many JSON 49to write yet another JSON module? While it seems there are many JSON
50modules, none of them correctly handle all corner cases, and in most cases 50modules, none of them correctly handle all corner cases, and in most cases
51their maintainers are unresponsive, gone missing, or not listening to bug 51their maintainers are unresponsive, gone missing, or not listening to bug
52reports for other reasons. 52reports for other reasons.
53 53
54See COMPARISON, below, for a comparison to some other JSON modules.
55
56See MAPPING, below, on how JSON::XS maps perl values to JSON values and 54See MAPPING, below, on how JSON::XS maps perl values to JSON values and
57vice versa. 55vice versa.
58 56
59=head2 FEATURES 57=head2 FEATURES
60 58
… …
101 99
102=cut 100=cut
103 101
104package JSON::XS; 102package JSON::XS;
105 103
104no warnings;
106use strict; 105use strict;
107 106
108our $VERSION = '2.2'; 107our $VERSION = '2.2222';
109our @ISA = qw(Exporter); 108our @ISA = qw(Exporter);
110 109
111our @EXPORT = qw(encode_json decode_json to_json from_json); 110our @EXPORT = qw(encode_json decode_json to_json from_json);
112 111
113sub to_json($) { 112sub to_json($) {
… …
706In some cases, there is the need for incremental parsing of JSON 705In some cases, there is the need for incremental parsing of JSON
707texts. While this module always has to keep both JSON text and resulting 706texts. 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 707Perl 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 708JSON stream incrementally. It does so by accumulating text until it has
710a full JSON object, which it then can decode. This process is similar to 709a full JSON object, which it then can decode. This process is similar to
711using C<decode_prefix> to see if a full JSON object is available, but is 710using C<decode_prefix> to see if a full JSON object is available, but
712much more efficient (JSON::XS will only attempt to parse the JSON text 711is much more efficient (and can be implemented with a minimum of method
712calls).
713
714JSON::XS will only attempt to parse the JSON text once it is sure it
713once it is sure it has enough text to get a decisive result, using a very 715has enough text to get a decisive result, using a very simple but
714simple but truly incremental parser). 716truly incremental parser. This means that it sometimes won't stop as
717early as the full parser, for example, it doesn't detect parenthese
718mismatches. The only thing it guarantees is that it starts decoding as
719soon as a syntactically valid JSON text has been seen. This means you need
720to set resource limits (e.g. C<max_size>) to ensure the parser will stop
721parsing in the presence if syntax errors.
715 722
716The following two methods deal with this. 723The following methods implement this incremental parser.
717 724
718=over 4 725=over 4
719 726
720=item [void, scalar or list context] = $json->incr_parse ([$string]) 727=item [void, scalar or list context] = $json->incr_parse ([$string])
721 728
… …
763 770
764This will reset the state of the incremental parser and will remove the 771This 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> 772parsed 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 773died, 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. 774unchanged, to skip the text parsed so far and to reset the parse state.
775
776=item $json->incr_reset
777
778This completely resets the incremental parser, that is, after this call,
779it will be as if the parser had never parsed anything.
780
781This is useful if you want ot repeatedly parse JSON objects and want to
782ignore any trailing data, which means you have to reset the parser after
783each successful decode.
768 784
769=back 785=back
770 786
771=head2 LIMITATIONS 787=head2 LIMITATIONS
772 788

Diff Legend

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