--- JSON-XS/XS.pm	2007/11/25 14:23:57	1.71
+++ JSON-XS/XS.pm	2007/12/04 10:37:42	1.77
@@ -21,12 +21,28 @@
  $pretty_printed_unencoded = $coder->encode ($perl_scalar);
  $perl_scalar = $coder->decode ($unicode_json_text);
 
+ # Note that JSON version 2.0 and above will automatically use JSON::XS
+ # if available, at virtually no speed overhead either, so you should
+ # be able to just:
+ 
+ use JSON;
+
+ # and do the same things, except that you have a pure-perl fallback now.
+
 =head1 DESCRIPTION
 
 This module converts Perl data structures to JSON and vice versa. Its
 primary goal is to be I<correct> and its secondary goal is to be
 I<fast>. To reach the latter goal it was written in C.
 
+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
+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
+require a C compiler when that is a problem.
+
 As this is the n-th-something JSON module on CPAN, what was the reason
 to write yet another JSON module? While it seems there are many JSON
 modules, none of them correctly handle all corner cases, and in most cases
@@ -86,7 +102,7 @@
 
 use strict;
 
-our $VERSION = '1.53';
+our $VERSION = '2.0';
 our @ISA = qw(Exporter);
 
 our @EXPORT = qw(to_json from_json);
@@ -204,6 +220,8 @@
 
 =item $json = $json->ascii ([$enable])
 
+=item $enabled = $json->get_ascii
+
 If C<$enable> is true (or missing), then the C<encode> method will not
 generate characters outside the code range C<0..127> (which is ASCII). Any
 Unicode characters outside that range will be escaped using either a
@@ -225,6 +243,8 @@
 
 =item $json = $json->latin1 ([$enable])
 
+=item $enabled = $json->get_latin1
+
 If C<$enable> is true (or missing), then the C<encode> method will encode
 the resulting JSON text as latin1 (or iso-8859-1), escaping any characters
 outside the code range C<0..255>. The resulting string can be treated as a
@@ -248,6 +268,8 @@
 
 =item $json = $json->utf8 ([$enable])
 
+=item $enabled = $json->get_utf8
+
 If C<$enable> is true (or missing), then the C<encode> method will encode
 the JSON result into UTF-8, as required by many protocols, while the
 C<decode> method expects to be handled an UTF-8-encoded string.  Please
@@ -290,6 +312,8 @@
 
 =item $json = $json->indent ([$enable])
 
+=item $enabled = $json->get_indent
+
 If C<$enable> is true (or missing), then the C<encode> method will use a multiline
 format as output, putting every array member or object/hash key-value pair
 into its own line, indenting them properly.
@@ -301,6 +325,8 @@
 
 =item $json = $json->space_before ([$enable])
 
+=item $enabled = $json->get_space_before
+
 If C<$enable> is true (or missing), then the C<encode> method will add an extra
 optional space before the C<:> separating keys from values in JSON objects.
 
@@ -316,6 +342,8 @@
 
 =item $json = $json->space_after ([$enable])
 
+=item $enabled = $json->get_space_after
+
 If C<$enable> is true (or missing), then the C<encode> method will add an extra
 optional space after the C<:> separating keys from values in JSON objects
 and extra whitespace after the C<,> separating key-value pairs and array
@@ -332,6 +360,8 @@
 
 =item $json = $json->relaxed ([$enable])
 
+=item $enabled = $json->get_relaxed
+
 If C<$enable> is true (or missing), then C<decode> will accept some
 extensions to normal JSON syntax (see below). C<encode> will not be
 affected in anyway. I<Be aware that this option makes you accept invalid
@@ -377,6 +407,8 @@
 
 =item $json = $json->canonical ([$enable])
 
+=item $enabled = $json->get_canonical
+
 If C<$enable> is true (or missing), then the C<encode> method will output JSON objects
 by sorting their keys. This is adding a comparatively high overhead.
 
@@ -393,6 +425,8 @@
 
 =item $json = $json->allow_nonref ([$enable])
 
+=item $enabled = $json->get_allow_nonref
+
 If C<$enable> is true (or missing), then the C<encode> method can convert a
 non-reference into its corresponding string, number or null JSON value,
 which is an extension to RFC4627. Likewise, C<decode> will accept those JSON
@@ -411,11 +445,13 @@
 
 =item $json = $json->allow_blessed ([$enable])
 
+=item $enabled = $json->get_allow_blessed
+
 If C<$enable> is true (or missing), then the C<encode> method will not
 barf when it encounters a blessed reference. Instead, the value of the
 B<convert_blessed> option will decide whether C<null> (C<convert_blessed>
-disabled or no C<to_json> method found) or a representation of the
-object (C<convert_blessed> enabled and C<to_json> method found) is being
+disabled or no C<TO_JSON> method found) or a representation of the
+object (C<convert_blessed> enabled and C<TO_JSON> method found) is being
 encoded. Has no effect on C<decode>.
 
 If C<$enable> is false (the default), then C<encode> will throw an
@@ -423,6 +459,8 @@
 
 =item $json = $json->convert_blessed ([$enable])
 
+=item $enabled = $json->get_convert_blessed
+
 If C<$enable> is true (or missing), then C<encode>, upon encountering a
 blessed object, will check for the availability of the C<TO_JSON> method
 on the object's class. If found, it will be called in scalar context
@@ -523,6 +561,8 @@
 
 =item $json = $json->shrink ([$enable])
 
+=item $enabled = $json->get_shrink
+
 Perl usually over-allocates memory a bit when allocating space for
 strings. This flag optionally resizes strings generated by either
 C<encode> or C<decode> to their minimum size possible. This can save
@@ -549,6 +589,8 @@
 
 =item $json = $json->max_depth ([$maximum_nesting_depth])
 
+=item $max_depth = $json->get_max_depth
+
 Sets the maximum nesting level (default C<512>) accepted while encoding
 or decoding. If the JSON text or Perl data structure has an equal or
 higher nesting level then this limit, then the encoder and decoder will
@@ -570,6 +612,8 @@
 
 =item $json = $json->max_size ([$maximum_string_size])
 
+=item $max_size = $json->get_max_size
+
 Set the maximum length a JSON text may have (in bytes) where decoding is
 being attempted. The default is C<0>, meaning no limit. When C<decode>
 is called on a string longer then this number of characters it will not
@@ -894,7 +938,7 @@
 
    module     |     encode |     decode |
    -----------|------------|------------|
-   JSON       |   4990.842 |   4088.813 |
+   JSON 1.x   |   4990.842 |   4088.813 |
    JSON::DWIW |  51653.990 |  71575.154 |
    JSON::PC   |  65948.176 |  74631.744 |
    JSON::PP   |   8931.652 |   3817.168 |
@@ -915,7 +959,7 @@
 
    module     |     encode |     decode |
    -----------|------------|------------|
-   JSON       |     55.260 |     34.971 |
+   JSON 1.x   |     55.260 |     34.971 |
    JSON::DWIW |    825.228 |   1082.513 |
    JSON::PC   |   3571.444 |   2394.829 |
    JSON::PP   |    210.987 |     32.574 |