--- JSON-XS/XS.pm	2007/06/11 02:58:10	1.39
+++ JSON-XS/XS.pm	2007/06/25 04:21:14	1.46
@@ -87,16 +87,13 @@
 
 use strict;
 
-BEGIN {
-   our $VERSION = '1.23';
-   our @ISA = qw(Exporter);
+our $VERSION = '1.4';
+our @ISA = qw(Exporter);
 
-   our @EXPORT = qw(to_json from_json objToJson jsonToObj);
-   require Exporter;
+our @EXPORT = qw(to_json from_json objToJson jsonToObj);
 
-   require XSLoader;
-   XSLoader::load JSON::XS::, $VERSION;
-}
+use Exporter;
+use XSLoader;
 
 =head1 FUNCTIONAL INTERFACE
 
@@ -129,6 +126,15 @@
 
 except being faster.
 
+=item $is_boolean = JSON::XS::is_bool $scalar
+
+Returns true if the passed scalar represents either JSON::XS::true or
+JSON::XS::false, two constants that act like C<1> and C<0>, respectively
+and are used to represent JSON C<true> and C<false> values in Perl.
+
+See MAPPING, below, for more information on how JSON values are mapped to
+Perl.
+
 =back
 
 
@@ -312,6 +318,42 @@
    JSON::XS->new->allow_nonref->encode ("Hello, World!")
    => "Hello, World!"
 
+=item $json = $json->allow_blessed ([$enable])
+
+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 wether 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
+encoded. Has no effect on C<decode>.
+
+If C<$enable> is false (the default), then C<encode> will throw an
+exception when it encounters a blessed object.
+
+=item $json = $json->convert_blessed ([$enable])
+
+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
+and the resulting scalar will be encoded instead of the object. If no
+C<TO_JSON> method is found, the value of C<allow_blessed> will decide what
+to do.
+
+The C<TO_JSON> method may safely call die if it wants. If C<TO_JSON>
+returns other blessed objects, those will be handled in the same
+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.
+
+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
+enabled by this setting.
+
+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->shrink ([$enable])
 
 Perl usually over-allocates memory a bit when allocating space for
@@ -434,10 +476,10 @@
 
 =item true, false
 
-These JSON atoms become C<0>, C<1>, respectively. Information is lost in
-this process. Future versions might represent those values differently,
-but they will be guarenteed to act like these integers would normally in
-Perl.
+These JSON atoms become C<JSON::XS::true> and C<JSON::XS::false>,
+respectively. They are overloaded to act almost exactly like the numbers
+C<1> and C<0>. You can check wether a scalar is a JSON boolean by using
+the C<JSON::XS::is_bool> function.
 
 =item null
 
@@ -479,6 +521,11 @@
 
    to_json [\0,JSON::XS::true]      # yields [false,true]
 
+=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.
+
 =item blessed objects
 
 Blessed objects are not allowed. JSON::XS currently tries to encode their
@@ -616,20 +663,21 @@
 however, a mass hysteria and very far from the truth. In general, there is
 no way to configure JSON::XS to output a data structure as valid YAML.
 
-If you really must use JSON::XS to generate YAML, you should this
+If you really must use JSON::XS to generate YAML, you should use this
 algorithm (subject to change in future versions):
 
    my $to_yaml = JSON::XS->new->utf8->space_after (1);
    my $yaml = $to_yaml->encode ($ref) . "\n";
 
 This will usually generate JSON texts that also parse as valid
-YAML. Please note that YAML has hardcoded limits on object key lengths
-that JSON doesn't have, so you should make sure that your hash keys are
-noticably shorter than 1024 characters.
+YAML. Please note that YAML has hardcoded limits on (simple) object key
+lengths that JSON doesn't have, so you should make sure that your hash
+keys are noticably shorter than the 1024 characters YAML allows.
 
 There might be other incompatibilities that I am not aware of. In general
 you should not try to generate YAML with a JSON generator or vice versa,
-or try to parse JSON with a YAML parser or vice versa.
+or try to parse JSON with a YAML parser or vice versa: chances are high
+that you will run into severe interoperability problems.
 
 
 =head2 SPEED
@@ -653,13 +701,13 @@
    module     |     encode |     decode |
    -----------|------------|------------|
    JSON       |   7645.468 |   4208.613 |
-   JSON::DWIW |  68534.379 |  79437.576 |
+   JSON::DWIW |  40721.398 |  77101.176 |
    JSON::PC   |  65948.176 |  78251.940 |
-   JSON::Syck |  23379.621 |  28416.694 |
+   JSON::Syck |  22844.793 |  26479.192 |
    JSON::XS   | 388361.481 | 199728.762 |
    JSON::XS/2 | 218453.333 | 192399.266 |
    JSON::XS/3 | 338250.323 | 192399.266 |
-   Storable   |  15732.573 |  28571.553 |
+   Storable   |  15779.925 |  14169.946 |
    -----------+------------+------------+
 
 That is, JSON::XS is about five times faster than JSON::DWIW on encoding,
@@ -673,16 +721,17 @@
    module     |     encode |     decode |
    -----------|------------|------------|
    JSON       |    254.685 |     37.665 |
-   JSON::DWIW |   1014.244 |   1087.678 |
+   JSON::DWIW |    843.343 |   1049.731 |
    JSON::PC   |   3602.116 |   2307.352 |
-   JSON::Syck |    558.035 |    776.263 |
-   JSON::XS   |   5747.196 |   3543.684 |
-   JSON::XS/2 |   3968.121 |   3589.170 |
-   JSON::XS/3 |   6105.246 |   3561.134 |
-   Storable   |   4456.337 |   5320.020 |
+   JSON::Syck |    505.107 |    787.899 |
+   JSON::XS   |   5747.196 |   3690.220 |
+   JSON::XS/2 |   3968.121 |   3676.634 |
+   JSON::XS/3 |   6105.246 |   3662.508 |
+   Storable   |   4417.337 |   5285.161 |
    -----------+------------+------------+
 
-Again, JSON::XS leads by far.
+Again, JSON::XS leads by far (except for Storable which non-surprisingly
+decodes faster).
 
 On large strings containing lots of high unicode characters, some modules
 (such as JSON::PC) seem to decode faster than JSON::XS, but the result
@@ -720,6 +769,14 @@
 of. In that case, you get to keep the pieces. I am always open for hints,
 though...
 
+If you are using JSON::XS to return packets to consumption
+by javascript scripts in a browser you should have a look at
+L<http://jpsykes.com/47/practical-csrf-and-json-security> to see wether
+you are vulnerable to some common attack vectors (which really are browser
+design bugs, but it is still you who will have to deal with it, as major
+browser developers care only for features, not about doing security
+right).
+
 
 =head1 BUGS
 
@@ -730,8 +787,26 @@
 
 =cut
 
-sub true()  { \1 }
-sub false() { \0 }
+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 }
+
+sub is_bool($) {
+   UNIVERSAL::isa $_[0], "JSON::XS::Boolean"
+#      or UNIVERSAL::isa $_[0], "JSON::Literal"
+}
+
+XSLoader::load "JSON::XS", $VERSION;
+
+package JSON::XS::Boolean;
+
+use overload
+   "0+"     => sub { ${$_[0]} },
+   "++"     => sub { $_[0] = ${$_[0]} + 1 },
+   "--"     => sub { $_[0] = ${$_[0]} - 1 },
+   fallback => 1;
 
 1;