--- JSON-XS/XS.pm	2007/05/23 22:07:43	1.36
+++ JSON-XS/XS.pm	2007/06/14 23:58:57	1.42
@@ -88,7 +88,7 @@
 use strict;
 
 BEGIN {
-   our $VERSION = '1.22';
+   our $VERSION = '1.24';
    our @ISA = qw(Exporter);
 
    our @EXPORT = qw(to_json from_json objToJson jsonToObj);
@@ -404,6 +404,7 @@
 lowercase I<perl> refers to the Perl interpreter, while uppcercase I<Perl>
 refers to the abstract Perl language itself.
 
+
 =head2 JSON -> PERL
 
 =over 4
@@ -444,6 +445,7 @@
 
 =back
 
+
 =head2 PERL -> JSON
 
 The mapping from Perl to JSON is slightly more difficult, as Perl is a
@@ -607,6 +609,30 @@
 
 =back
 
+
+=head2 JSON and YAML
+
+You often hear that JSON is a subset (or a close subset) of YAML. This is,
+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 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 (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: chances are high
+that you will run into severe interoperability problems.
+
+
 =head2 SPEED
 
 It seems that JSON::XS is surprisingly fast, as shown in the following
@@ -614,43 +640,51 @@
 in the JSON::XS distribution, to make it easy to compare on your own
 system.
 
-First comes a comparison between various modules using a very short JSON
-string:
+First comes a comparison between various modules using a very short
+single-line JSON string:
 
-   {"method": "handleMessage", "params": ["user1", "we were just talking"], "id": null}
+   {"method": "handleMessage", "params": ["user1", "we were just talking"], \
+   "id": null, "array":[1,11,234,-5,1e5,1e7, true,  false]}
 
-It shows the number of encodes/decodes per second (JSON::XS uses the
-functional interface, while JSON::XS/2 uses the OO interface with
-pretty-printing and hashkey sorting enabled). Higher is better:
+It shows the number of encodes/decodes per second (JSON::XS uses
+the functional interface, while JSON::XS/2 uses the OO interface
+with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables
+shrink). Higher is better:
 
    module     |     encode |     decode |
    -----------|------------|------------|
-   JSON       |  11488.516 |   7823.035 |
-   JSON::DWIW |  94708.054 | 129094.260 |
-   JSON::PC   |  63884.157 | 128528.212 |
-   JSON::Syck |  34898.677 |  42096.911 |
-   JSON::XS   | 654027.064 | 396423.669 |
-   JSON::XS/2 | 371564.190 | 371725.613 |
+   JSON       |   7645.468 |   4208.613 |
+   JSON::DWIW |  40721.398 |  77101.176 |
+   JSON::PC   |  65948.176 |  78251.940 |
+   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   |  15779.925 |  14169.946 |
    -----------+------------+------------+
 
-That is, JSON::XS is more than six times faster than JSON::DWIW on
-encoding, more than three times faster on decoding, and about thirty times
-faster than JSON, even with pretty-printing and key sorting.
+That is, JSON::XS is about five times faster than JSON::DWIW on encoding,
+about three times faster on decoding, and over fourty times faster
+than JSON, even with pretty-printing and key sorting. It also compares
+favourably to Storable for small amounts of data.
 
 Using a longer test string (roughly 18KB, generated from Yahoo! Locals
 search API (http://nanoref.com/yahooapis/mgPdGg):
 
    module     |     encode |     decode |
    -----------|------------|------------|
-   JSON       |    273.023 |     44.674 |
-   JSON::DWIW |   1089.383 |   1145.704 |
-   JSON::PC   |   3097.419 |   2393.921 |
-   JSON::Syck |    514.060 |    843.053 |
-   JSON::XS   |   6479.668 |   3636.364 |
-   JSON::XS/2 |   3774.221 |   3599.124 |
+   JSON       |    254.685 |     37.665 |
+   JSON::DWIW |    843.343 |   1049.731 |
+   JSON::PC   |   3602.116 |   2307.352 |
+   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
@@ -688,6 +722,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