--- JSON-XS/XS.pm 2007/04/11 12:23:02 1.31 +++ JSON-XS/XS.pm 2007/06/11 02:58:10 1.39 @@ -88,7 +88,7 @@ use strict; BEGIN { - our $VERSION = '1.12'; + our $VERSION = '1.23'; our @ISA = qw(Exporter); our @EXPORT = qw(to_json from_json objToJson jsonToObj); @@ -156,15 +156,44 @@ generate characters outside the code range C<0..127> (which is ASCII). Any unicode characters outside that range will be escaped using either a single \uXXXX (BMP characters) or a double \uHHHH\uLLLLL escape sequence, -as per RFC4627. +as per RFC4627. The resulting encoded JSON text can be treated as a native +unicode string, an ascii-encoded, latin1-encoded or UTF-8 encoded string, +or any other superset of ASCII. If C<$enable> is false, then the C method will not escape Unicode -characters unless required by the JSON syntax. This results in a faster -and more compact format. +characters unless required by the JSON syntax or other flags. This results +in a faster and more compact format. + +The main use for this flag is to produce JSON texts that can be +transmitted over a 7-bit channel, as the encoded JSON texts will not +contain any 8 bit characters. JSON::XS->new->ascii (1)->encode ([chr 0x10401]) => ["\ud801\udc01"] +=item $json = $json->latin1 ([$enable]) + +If C<$enable> is true (or missing), then the C method will encode +the resulting JSON text as latin1 (or iso-8859-1), escaping any characters +outside the code range C<0..255>. The resulting string can be treated as a +latin1-encoded JSON text or a native unicode string. The C method +will not be affected in any way by this flag, as C by default +expects unicode, which is a strict superset of latin1. + +If C<$enable> is false, then the C method will not escape Unicode +characters unless required by the JSON syntax or other flags. + +The main use for this flag is efficiently encoding binary data as JSON +text, as most octets will not be escaped, resulting in a smaller encoded +size. The disadvantage is that the resulting JSON text is encoded +in latin1 (and must correctly be treated as such when storing and +transfering), a rare encoding for JSON. It is therefore most useful when +you want to store data structures known to contain binary data efficiently +in files or databases, not when talking to other JSON encoders/decoders. + + JSON::XS->new->latin1->encode (["\x{89}\x{abc}"] + => ["\x{89}\\u0abc"] # (perl syntax, U+abc escaped, U+89 not) + =item $json = $json->utf8 ([$enable]) If C<$enable> is true (or missing), then the C method will encode @@ -347,6 +376,20 @@ Perl arrayrefs and JSON objects become Perl hashrefs. C becomes C<1>, C becomes C<0> and C becomes C. +=item ($perl_scalar, $characters) = $json->decode_prefix ($json_text) + +This works like the C method, but instead of raising an exception +when there is trailing garbage after the first JSON object, it will +silently stop parsing there and return the number of characters consumed +so far. + +This is useful if your JSON texts are not delimited by an outer protocol +(which is not the brightest thing to do in the first place) and you need +to know where the JSON text ends. + + JSON::XS->new->decode_prefix ("[1] the tail") + => ([], 3) + =back @@ -361,6 +404,7 @@ lowercase I refers to the Perl interpreter, while uppcercase I refers to the abstract Perl language itself. + =head2 JSON -> PERL =over 4 @@ -401,6 +445,7 @@ =back + =head2 PERL -> JSON The mapping from Perl to JSON is slightly more difficult, as Perl is a @@ -564,6 +609,29 @@ =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 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. + +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. + + =head2 SPEED It seems that JSON::XS is surprisingly fast, as shown in the following @@ -571,40 +639,47 @@ 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 | 68534.379 | 79437.576 | + JSON::PC | 65948.176 | 78251.940 | + JSON::Syck | 23379.621 | 28416.694 | + 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 | -----------+------------+------------+ -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 | 1014.244 | 1087.678 | + 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 | -----------+------------+------------+ Again, JSON::XS leads by far.