--- JSON-XS/XS.pm	2008/05/08 15:33:06	1.104
+++ JSON-XS/XS.pm	2008/07/21 02:45:17	1.111
@@ -39,7 +39,7 @@
 
 Beginning with version 2.0 of the JSON module, when both JSON and
 JSON::XS are installed, then JSON will fall back on JSON::XS (this can be
-overriden) with no overhead due to emulation (by inheritign constructor
+overridden) with no overhead due to emulation (by inheriting constructor
 and methods). If JSON::XS is not available, it will fall back to the
 compatible JSON::PP module as backend, so using JSON instead of JSON::XS
 gives you a portable JSON API that can be fast when you need and doesn't
@@ -51,8 +51,6 @@
 their maintainers are unresponsive, gone missing, or not listening to bug
 reports for other reasons.
 
-See COMPARISON, below, for a comparison to some other JSON modules.
-
 See MAPPING, below, on how JSON::XS maps perl values to JSON values and
 vice versa.
 
@@ -67,7 +65,7 @@
 
 =item * round-trip integrity
 
-When you serialise a perl data structure using only datatypes supported
+When you serialise a perl data structure using only data types supported
 by JSON, the deserialised data structure is identical on the Perl level.
 (e.g. the string "2.0" doesn't suddenly become "2" just because it looks
 like a number). There minor I<are> exceptions to this, read the MAPPING
@@ -86,13 +84,13 @@
 
 =item * simple to use
 
-This module has both a simple functional interface as well as an objetc
+This module has both a simple functional interface as well as an object
 oriented interface interface.
 
 =item * reasonably versatile output formats
 
 You can choose between the most compact guaranteed-single-line format
-possible (nice for simple line-based protocols), a pure-ascii format
+possible (nice for simple line-based protocols), a pure-ASCII format
 (for when your transport is not 8-bit clean, still supports the whole
 Unicode range), or a pretty-printed format (for when you want to read that
 stuff). Or you can combine those features in whatever way you like.
@@ -103,9 +101,10 @@
 
 package JSON::XS;
 
+no warnings;
 use strict;
 
-our $VERSION = '2.2';
+our $VERSION = '2.2222';
 our @ISA = qw(Exporter);
 
 our @EXPORT = qw(encode_json decode_json to_json from_json);
@@ -139,7 +138,7 @@
 
    $json_text = JSON::XS->new->utf8->encode ($perl_scalar)
 
-except being faster.
+Except being faster.
 
 =item $perl_scalar = decode_json $json_text
 
@@ -151,7 +150,7 @@
 
    $perl_scalar = JSON::XS->new->utf8->decode ($json_text)
 
-except being faster.
+Except being faster.
 
 =item $is_boolean = JSON::XS::is_bool $scalar
 
@@ -199,7 +198,7 @@
 exist.
 
 =item 4. A "Unicode String" is simply a string where each character can be
-validly interpreted as a Unicode codepoint.
+validly interpreted as a Unicode code point.
 
 If you have UTF-8 encoded data, it is no longer a Unicode string, but a
 Unicode string encoded in UTF-8, giving you a binary string.
@@ -703,19 +702,25 @@
 
 =head1 INCREMENTAL PARSING
 
-[This section and the API it details is still EXPERIMENTAL]
-
 In some cases, there is the need for incremental parsing of JSON
 texts. While this module always has to keep both JSON text and resulting
 Perl data structure in memory at one time, it does allow you to parse a
 JSON stream incrementally. It does so by accumulating text until it has
 a full JSON object, which it then can decode. This process is similar to
-using C<decode_prefix> to see if a full JSON object is available, but is
-much more efficient (JSON::XS will only attempt to parse the JSON text
-once it is sure it has enough text to get a decisive result, using a very
-simple but truly incremental parser).
+using C<decode_prefix> to see if a full JSON object is available, but
+is much more efficient (and can be implemented with a minimum of method
+calls).
+
+JSON::XS will only attempt to parse the JSON text once it is sure it
+has enough text to get a decisive result, using a very simple but
+truly incremental parser. This means that it sometimes won't stop as
+early as the full parser, for example, it doesn't detect parenthese
+mismatches. The only thing it guarantees is that it starts decoding as
+soon as a syntactically valid JSON text has been seen. This means you need
+to set resource limits (e.g. C<max_size>) to ensure the parser will stop
+parsing in the presence if syntax errors.
 
-The following two methods deal with this.
+The following methods implement this incremental parser.
 
 =over 4
 
@@ -768,6 +773,15 @@
 died, in which case the input buffer and incremental parser state is left
 unchanged, to skip the text parsed so far and to reset the parse state.
 
+=item $json->incr_reset
+
+This completely resets the incremental parser, that is, after this call,
+it will be as if the parser had never parsed anything.
+
+This is useful if you want ot repeatedly parse JSON objects and want to
+ignore any trailing data, which means you have to reset the parser after
+each successful decode.
+
 =back
 
 =head2 LIMITATIONS