--- JSON-XS/XS.pm	2007/07/02 01:12:27	1.51
+++ JSON-XS/XS.pm	2007/10/11 22:52:52	1.62
@@ -1,7 +1,12 @@
+=encoding utf-8
+
 =head1 NAME
 
 JSON::XS - JSON serialising/deserialising, done correctly and fast
 
+JSON::XS - 正しくて高速な JSON シリアライザ/デシリアライザ
+           (http://fleur.hio.jp/perldoc/mix/lib/JSON/XS.html)
+
 =head1 SYNOPSIS
 
  use JSON::XS;
@@ -83,7 +88,7 @@
 
 use strict;
 
-our $VERSION = '1.4';
+our $VERSION = '1.5';
 our @ISA = qw(Exporter);
 
 our @EXPORT = qw(to_json from_json);
@@ -280,6 +285,51 @@
 
    {"key": "value"}
 
+=item $json = $json->relaxed ([$enable])
+
+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
+JSON texts as if they were valid!>. I suggest only to use this option to
+parse application-specific files written by humans (configuration files,
+resource files etc.)
+
+If C<$enable> is false (the default), then C<decode> will only accept
+valid JSON texts.
+
+Currently accepted extensions are:
+
+=over 4
+
+=item * list items can have an end-comma
+
+JSON I<separates> array elements and key-value pairs with commas. This
+can be annoying if you write JSON texts manually and want to be able to
+quickly append elements, so this extension accepts comma at the end of
+such items not just between them:
+
+   [
+      1,
+      2, <- this comma not normally allowed
+   ]
+   {
+      "k1": "v1",
+      "k2": "v2", <- this comma not normally allowed
+   }
+
+=item * shell-style '#'-comments
+
+Whenever JSON allows whitespace, shell-style comments are additionally
+allowed. They are terminated by the first carriage-return or line-feed
+character, after which more white-space and comments are allowed.
+
+  [
+     1, # this comment not allowed in JSON
+        # neither this one...
+  ]
+
+=back
+
 =item $json = $json->canonical ([$enable])
 
 If C<$enable> is true (or missing), then the C<encode> method will output JSON objects
@@ -350,7 +400,7 @@
 If C<$enable> is false, then the C<allow_blessed> setting will decide what
 to do when a blessed object is found.
 
-=item $json = $json->filter_json_object ([$coderef])
+=item $json = $json->filter_json_object ([$coderef->($hashref)])
 
 When C<$coderef> is specified, it will be called from C<decode> each
 time it decodes a JSON object. The only argument is a reference to the
@@ -361,28 +411,33 @@
 original deserialised hash will be inserted. This setting can slow down
 decoding considerably.
 
-When C<$coderef> is omitted or undefined, C<decode> will not change the
-deserialised hash in any way. This is maximally fast.
+When C<$coderef> is omitted or undefined, any existing callback will
+be removed and C<decode> will not change the deserialised hash in any
+way.
 
 Example, convert all JSON objects into the integer 5:
 
    my $js = JSON::XS->new->filter_json_object (sub { 5 });
    # returns [5]
    $js->decode ('[{}]')
-   # throw an exception because allow_nonref is not enabled:
+   # throw an exception because allow_nonref is not enabled
+   # so a lone 5 is not allowed.
    $js->decode ('{"a":1, "b":2}');
 
-=item $json = $json->filter_json_single_key_object ([$coderef])
+=item $json = $json->filter_json_single_key_object ($key [=> $coderef->($value)])
 
-Works like C<filter_json_object>, but is only called for JSON objects
-having only a single key.
+Works remotely similar to C<filter_json_object>, but is only called for
+JSON objects having a single key named C<$key>.
 
 This C<$coderef> is called before the one specified via
-C<filter_json_object>, if any. If it returns something, that will be
-inserted into the data structure. If it returns nothing, the callback
-from C<filter_json_object> will be called next. If you want to force
-insertion of single-key objects even in the presence of a mutating
-C<filter_json_object> callback, simply return the passed hash.
+C<filter_json_object>, if any. It gets passed the single value in the JSON
+object. If it returns a single value, it will be inserted into the data
+structure. If it returns nothing (not even C<undef> but the empty list),
+the callback from C<filter_json_object> will be called next, as if no
+single-key callback were specified.
+
+If C<$coderef> is omitted or undefined, the corresponding callback will be
+disabled. There can only ever be one callback for a given key.
 
 As this callback gets called less often then the C<filter_json_object>
 one, decoding speed will not usually suffer as much. Therefore, single-key
@@ -403,10 +458,8 @@
    # return whatever is in $WIDGET{5}:
    JSON::XS
       ->new
-      ->filter_json_single_key_object (sub {
-         exists $_[0]{__widget__}
-            ? $WIDGET{ $_[0]{__widget__} }
-            : ()
+      ->filter_json_single_key_object (__widget__ => sub {
+            $WIDGET{ $_[0] }
          })
       ->decode ('{"__widget__": 5')
 
@@ -552,11 +605,23 @@
 
 =item number
 
-A JSON number becomes either an integer or numeric (floating point)
-scalar in perl, depending on its range and any fractional parts. On the
-Perl level, there is no difference between those as Perl handles all the
-conversion details, but an integer may take slightly less memory and might
-represent more values exactly than (floating point) numbers.
+A JSON number becomes either an integer, numeric (floating point) or
+string scalar in perl, depending on its range and any fractional parts. On
+the Perl level, there is no difference between those as Perl handles all
+the conversion details, but an integer may take slightly less memory and
+might represent more values exactly than (floating point) numbers.
+
+If the number consists of digits only, JSON::XS will try to represent
+it as an integer value. If that fails, it will try to represent it as
+a numeric (floating point) value if that is possible without loss of
+precision. Otherwise it will preserve the number as a string value.
+
+Numbers containing a fractional or exponential part will always be
+represented as numeric (floating point) values, possibly at a loss of
+precision.
+
+This might create round-tripping problems as numbers might become strings,
+but as Perl is typeless there is no other way to do it.
 
 =item true, false
 
@@ -608,7 +673,7 @@
 =item JSON::XS::true, JSON::XS::false
 
 These special values become JSON true and JSON false values,
-respectively. You cna alos use C<\1> and C<\0> directly if you want.
+respectively. You can also use C<\1> and C<\0> directly if you want.
 
 =item blessed objects
 
@@ -877,8 +942,8 @@
 
 =cut
 
-our $true  = do { bless \(my $dummy = "1"), "JSON::XS::Boolean" };
-our $false = do { bless \(my $dummy = "0"), "JSON::XS::Boolean" };
+our $true  = do { bless \(my $dummy = 1), "JSON::XS::Boolean" };
+our $false = do { bless \(my $dummy = 0), "JSON::XS::Boolean" };
 
 sub true()  { $true  }
 sub false() { $false }