--- JSON-XS/XS.pm	2007/11/25 19:36:54	1.73
+++ JSON-XS/XS.pm	2007/12/05 10:59:28	1.78
@@ -12,8 +12,8 @@
  # exported functions, they croak on error
  # and expect/generate UTF-8
 
- $utf8_encoded_json_text = to_json $perl_hash_or_arrayref;
- $perl_hash_or_arrayref  = from_json $utf8_encoded_json_text;
+ $utf8_encoded_json_text = encode_json $perl_hash_or_arrayref;
+ $perl_hash_or_arrayref  = decode_json $utf8_encoded_json_text;
 
  # OO-interface
 
@@ -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,10 +102,20 @@
 
 use strict;
 
-our $VERSION = '1.6';
+our $VERSION = '2.01';
 our @ISA = qw(Exporter);
 
-our @EXPORT = qw(to_json from_json);
+our @EXPORT = qw(encode_json decode_json to_json from_json);
+
+sub to_json($) {
+   require Carp;
+   Carp::croak ("JSON::XS::to_json has been renamed to encode_json, either downgrade to pre-2.0 versions of JSON::XS or rename the call");
+}
+
+sub from_json($) {
+   require Carp;
+   Carp::croak ("JSON::XS::from_json has been renamed to decode_json, either downgrade to pre-2.0 versions of JSON::XS or rename the call");
+}
 
 use Exporter;
 use XSLoader;
@@ -101,7 +127,7 @@
 
 =over 4
 
-=item $json_text = to_json $perl_scalar
+=item $json_text = encode_json $perl_scalar
 
 Converts the given Perl data structure to a UTF-8 encoded, binary string
 (that is, the string contains octets only). Croaks on error.
@@ -112,9 +138,9 @@
 
 except being faster.
 
-=item $perl_scalar = from_json $json_text
+=item $perl_scalar = decode_json $json_text
 
-The opposite of C<to_json>: expects an UTF-8 (binary) string and tries
+The opposite of C<encode_json>: expects an UTF-8 (binary) string and tries
 to parse that as an UTF-8 encoded JSON text, returning the resulting
 reference. Croaks on error.
 
@@ -279,8 +305,6 @@
 
 =item $json = $json->pretty ([$enable])
 
-=item $enabled = $json->get_pretty
-
 This enables (or disables) all of the C<indent>, C<space_before> and
 C<space_after> (and in the future possibly more) flags in one call to
 generate the most readable (or most compact) form possible.
@@ -431,13 +455,13 @@
 
 =item $json = $json->allow_blessed ([$enable])
 
-=item $enabled = $json->get_allow_bless
+=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
@@ -459,8 +483,8 @@
 way. C<TO_JSON> must take care of not causing an endless recursion cycle
 (== crash) in this case. The name of C<TO_JSON> was chosen because other
 methods called by the Perl core (== not by the user of the object) are
-usually in upper case letters and to avoid collisions with the C<to_json>
-function.
+usually in upper case letters and to avoid collisions with any C<to_json>
+function or method.
 
 This setting does not yet influence C<decode> in any way, but in the
 future, global hooks might get installed that influence C<decode> and are
@@ -743,7 +767,7 @@
 C<1>, which get turned into C<false> and C<true> atoms in JSON. You can
 also use C<JSON::XS::false> and C<JSON::XS::true> to improve readability.
 
-   to_json [\0,JSON::XS::true]      # yields [false,true]
+   encode_json [\0,JSON::XS::true]      # yields [false,true]
 
 =item JSON::XS::true, JSON::XS::false
 
@@ -764,16 +788,16 @@
 before encoding as JSON strings and anything else as number value:
 
    # dump as number
-   to_json [2]                      # yields [2]
-   to_json [-3.0e17]                # yields [-3e+17]
-   my $value = 5; to_json [$value]  # yields [5]
+   encode_json [2]                      # yields [2]
+   encode_json [-3.0e17]                # yields [-3e+17]
+   my $value = 5; encode_json [$value]  # yields [5]
 
    # used as string, so dump as string
    print $value;
-   to_json [$value]                 # yields ["5"]
+   encode_json [$value]                 # yields ["5"]
 
    # undef becomes null
-   to_json [undef]                  # yields [null]
+   encode_json [undef]                  # yields [null]
 
 You can force the type to be a JSON string by stringifying it: