--- JSON-XS/XS.pm	2007/03/22 17:28:50	1.2
+++ JSON-XS/XS.pm	2007/03/22 18:10:29	1.3
@@ -113,8 +113,8 @@
 The mutators for flags all return the JSON object again and thus calls can
 be chained:
 
-   my $json = JSON::XS->new->utf8(1)->pretty(1)->encode ({a => [1,2]})
-   => {"a" : [1, 2]}
+   my $json = JSON::XS->new->utf8(1)->space_after(1)->encode ({a => [1,2]})
+   => {"a": [1, 2]}
 
 =item $json = $json->ascii ($enable)
 
@@ -126,6 +126,9 @@
 If C<$enable> is false, then the C<encode> method will not escape Unicode
 characters unless necessary.
 
+  JSON::XS->new->ascii (1)->encode (chr 0x10401)
+  => \ud801\udc01
+
 =item $json = $json->utf8 ($enable)
 
 If C<$enable> is true, then the C<encode> method will encode the JSON
@@ -139,12 +142,21 @@
 unicode string.  Any decoding or encoding (e.g. to UTF-8 or UTF-16) needs
 to be done yourself, e.g. using the Encode module.
 
-=item $json = $json->pretty ($enabla)
+=item $json = $json->pretty ($enable)
 
 This enables (or disables) all of the C<indent>, C<space_before> and
-C<space_after> (and in the future possibly more) settings in one call to
+C<space_after> (and in the future possibly more) flags in one call to
 generate the most readable (or most compact) form possible.
 
+   my $json = JSON::XS->new->pretty(1)->encode ({a => [1,2]})
+   =>
+   {
+      "a" : [
+         1,
+         2
+      ]
+   }
+
 =item $json = $json->indent ($enable)
 
 If C<$enable> is true, then the C<encode> method will use a multiline
@@ -195,6 +207,18 @@
 
 This setting has no effect when decoding JSON strings.
 
+=item $json = $json->allow_nonref ($enable)
+
+If C<$enable> is true, 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
+values instead of croaking.
+
+If C<$enable> is false, then the C<encode> method will croak if it isn't
+passed an arrayref or hashref, as JSON strings must either be an object
+or array. Likewise, C<decode> will croak if given something that is not a
+JSON object or array.
+
 =item $json_string = $json->encode ($perl_scalar)
 
 Converts the given Perl data structure (a simple scalar or a reference
@@ -215,6 +239,91 @@
 
 =back
 
+=head1 COMPARISON
+
+As already mentioned, this module was created because none of the existing
+JSON modules could be made to work correctly. First I will describe the
+problems (or pleasures) I encountered with various existing JSON modules,
+followed by some benchmark values.
+
+=over 4
+
+=item JSON
+
+Slow (but very portable, as it is written in pure Perl).
+
+Undocumented/buggy Unicode handling (how JSON handles unicode values is
+undocumented. One can get far by feeding it unicode strings and doing
+en-/decoding oneself, but unicode escapes are not working properly).
+
+No roundtripping (strings get clobbered if they look like numbers, e.g.
+the string C<2.0> will encode to C<2.0> instead of C<"2.0">, and that will
+decode into the number 2.
+
+=item JSON::PC
+
+Very fast.
+
+Very inflexible (no human-readable format supported, format pretty much
+undocumented. I need at least a format for easy reading by humans and a
+single-line compact format for use in a protocol, and preferably a way to
+generate ASCII-only JSON strings).
+
+Undocumented/buggy Unicode handling.
+
+No roundtripping.
+
+Has problems handling many Perl values.
+
+Does not even generate valid JSON (C<{1,2}> gets converted to C<{1:2}>
+which is not a valid JSON string.
+
+Unmaintained (maintainer unresponsive for many months, bugs are not
+getting fixed).
+
+=item JSON::Syck
+
+Very buggy (often crashes).
+
+Very inflexible.
+
+Completely broken (and confusingly documented) Unicode handling (unicode
+escapes are not working properly, you need to set ImplicitUnicode to
+I<different> values on en- and decoding to get symmetric behaviour).
+
+No roundtripping (simple cases work, but this depends on wether the scalar
+value was used in a numeric context or not).
+
+Dumping hashes may skip hash values depending on iterator state.
+
+Unmaintained (maintainer unresponsive for many months, bugs are not
+getting fixed).
+
+Does not check input for validity (i.e. will accept non-JSON input and
+return "something" instead of raising an exception. This is a security
+issue: imagine two banks transfering money between each other using
+JSON. One bank might parse a given non-JSON request and deduct money,
+while the other might reject the transaction with a syntax error. While a
+good protocol will at least recover, that is extra unnecessary work and
+the transaction will still not succeed).
+
+=item JSON::DWIW
+
+Very fast. Very natural. Very nice.
+
+Undocumented unicode handling (but the best of the pack. Unicode escapes
+still don't get parsed properly).
+
+Very inflexible.
+
+No roundtripping.
+
+Does not check input for validity.
+
+=back
+
+=head2 SPEED
+
 =cut
 
 1;