--- JSON-XS/README 2007/05/09 16:35:21 1.11 +++ JSON-XS/README 2007/06/23 23:50:03 1.14 @@ -94,6 +94,15 @@ except being faster. + $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 1 and 0, + respectively and are used to represent JSON "true" and "false" + values in Perl. + + See MAPPING, below, for more information on how JSON values are + mapped to Perl. + OBJECT-ORIENTED INTERFACE The object oriented interface lets you configure your own encoding or decoding style, within the limits of supported formats. @@ -381,10 +390,10 @@ numbers. true, false - These JSON atoms become 0, 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 "JSON::XS::true" and "JSON::XS::false", + respectively. They are overloaded to act almost exactly like the + numbers 1 and 0. You can check wether a scalar is a JSON boolean by + using the "JSON::XS::is_bool" function. null A JSON null atom becomes "undef" in Perl. @@ -418,6 +427,10 @@ to_json [\0,JSON::XS::true] # yields [false,true] + JSON::XS::true, JSON::XS::false + These special values become JSON true and JSON false values, + respectively. You cna alos use "\1" and "\0" directly if you want. + blessed objects Blessed objects are not allowed. JSON::XS currently tries to encode their underlying representation (hash- or arrayref), but this @@ -537,49 +550,80 @@ Does not check input for validity. + 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. + SPEED It seems that JSON::XS is surprisingly fast, as shown in the following tables. They have been generated with the help of the "eg/bench" program 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: + 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 @@ -615,6 +659,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 + 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). + BUGS While the goal of this module is to be correct, that unfortunately does not mean its bug-free, only that I think its design is bug-free. It is