ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/JSON-XS/XS.pm
(Generate patch)

Comparing JSON-XS/XS.pm (file contents):
Revision 1.121 by root, Mon Jul 13 22:13:17 2009 UTC vs.
Revision 1.130 by root, Thu Mar 11 17:36:09 2010 UTC

… …
101 101
102package JSON::XS; 102package JSON::XS;
103 103
104use common::sense; 104use common::sense;
105 105
106our $VERSION = '2.24'; 106our $VERSION = '2.28';
107our @ISA = qw(Exporter); 107our @ISA = qw(Exporter);
108 108
109our @EXPORT = qw(encode_json decode_json to_json from_json); 109our @EXPORT = qw(encode_json decode_json to_json from_json);
110 110
111sub to_json($) { 111sub to_json($) {
… …
440the same JSON text (given the same overall settings). If it is disabled, 440the same JSON text (given the same overall settings). If it is disabled,
441the same hash might be encoded differently even if contains the same data, 441the same hash might be encoded differently even if contains the same data,
442as key-value pairs have no inherent ordering in Perl. 442as key-value pairs have no inherent ordering in Perl.
443 443
444This setting has no effect when decoding JSON texts. 444This setting has no effect when decoding JSON texts.
445
446This setting has currently no effect on tied hashes.
445 447
446=item $json = $json->allow_nonref ([$enable]) 448=item $json = $json->allow_nonref ([$enable])
447 449
448=item $enabled = $json->get_allow_nonref 450=item $enabled = $json->get_allow_nonref
449 451
… …
749objects or arrays, instead they must be concatenated back-to-back. If 751objects or arrays, instead they must be concatenated back-to-back. If
750an error occurs, an exception will be raised as in the scalar context 752an error occurs, an exception will be raised as in the scalar context
751case. Note that in this case, any previously-parsed JSON texts will be 753case. Note that in this case, any previously-parsed JSON texts will be
752lost. 754lost.
753 755
756Example: Parse some JSON arrays/objects in a given string and return
757them.
758
759 my @objs = JSON::XS->new->incr_parse ("[5][7][1,2]");
760
754=item $lvalue_string = $json->incr_text 761=item $lvalue_string = $json->incr_text
755 762
756This method returns the currently stored JSON fragment as an lvalue, that 763This method returns the currently stored JSON fragment as an lvalue, that
757is, you can manipulate it. This I<only> works when a preceding call to 764is, you can manipulate it. This I<only> works when a preceding call to
758C<incr_parse> in I<scalar context> successfully returned an object. Under 765C<incr_parse> in I<scalar context> successfully returned an object. Under
… …
1266 my $yaml = $to_yaml->encode ($ref) . "\n"; 1273 my $yaml = $to_yaml->encode ($ref) . "\n";
1267 1274
1268This will I<usually> generate JSON texts that also parse as valid 1275This will I<usually> generate JSON texts that also parse as valid
1269YAML. Please note that YAML has hardcoded limits on (simple) object key 1276YAML. Please note that YAML has hardcoded limits on (simple) object key
1270lengths that JSON doesn't have and also has different and incompatible 1277lengths that JSON doesn't have and also has different and incompatible
1271unicode handling, so you should make sure that your hash keys are 1278unicode character escape syntax, so you should make sure that your hash
1272noticeably shorter than the 1024 "stream characters" YAML allows and that 1279keys are noticeably shorter than the 1024 "stream characters" YAML allows
1273you do not have characters with codepoint values outside the Unicode BMP 1280and that you do not have characters with codepoint values outside the
1274(basic multilingual page). YAML also does not allow C<\/> sequences in 1281Unicode BMP (basic multilingual page). YAML also does not allow C<\/>
1275strings (which JSON::XS does not I<currently> generate, but other JSON 1282sequences in strings (which JSON::XS does not I<currently> generate, but
1276generators might). 1283other JSON generators might).
1277 1284
1278There might be other incompatibilities that I am not aware of (or the YAML 1285There might be other incompatibilities that I am not aware of (or the YAML
1279specification has been changed yet again - it does so quite often). In 1286specification has been changed yet again - it does so quite often). In
1280general you should not try to generate YAML with a JSON generator or vice 1287general you should not try to generate YAML with a JSON generator or vice
1281versa, or try to parse JSON with a YAML parser or vice versa: chances are 1288versa, or try to parse JSON with a YAML parser or vice versa: chances are
… …
1300that difficult or long) and finally make YAML compatible to it, and 1307that difficult or long) and finally make YAML compatible to it, and
1301educating users about the changes, instead of spreading lies about the 1308educating users about the changes, instead of spreading lies about the
1302real compatibility for many I<years> and trying to silence people who 1309real compatibility for many I<years> and trying to silence people who
1303point out that it isn't true. 1310point out that it isn't true.
1304 1311
1312Addendum/2009: the YAML 1.2 spec is still incomaptible with JSON, even
1313though the incompatibilities have been documented (and are known to
1314Brian) for many years and the spec makes explicit claims that YAML is a
1315superset of JSON. It would be so easy to fix, but apparently, bullying and
1316corrupting userdata is so much easier.
1317
1305=back 1318=back
1306 1319
1307 1320
1308=head2 SPEED 1321=head2 SPEED
1309 1322
… …
1316a very short single-line JSON string (also available at 1329a very short single-line JSON string (also available at
1317L<http://dist.schmorp.de/misc/json/short.json>). 1330L<http://dist.schmorp.de/misc/json/short.json>).
1318 1331
1319 {"method": "handleMessage", "params": ["user1", 1332 {"method": "handleMessage", "params": ["user1",
1320 "we were just talking"], "id": null, "array":[1,11,234,-5,1e5,1e7, 1333 "we were just talking"], "id": null, "array":[1,11,234,-5,1e5,1e7,
1321 true, false]} 1334 1, 0]}
1322 1335
1323It shows the number of encodes/decodes per second (JSON::XS uses 1336It shows the number of encodes/decodes per second (JSON::XS uses
1324the functional interface, while JSON::XS/2 uses the OO interface 1337the functional interface, while JSON::XS/2 uses the OO interface
1325with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables 1338with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables
1326shrink). Higher is better: 1339shrink. JSON::DWIW/DS uses the deserialise function, while JSON::DWIW::FJ
1340uses the from_json method). Higher is better:
1327 1341
1328 module | encode | decode | 1342 module | encode | decode |
1329 -----------|------------|------------| 1343 --------------|------------|------------|
1330 JSON 1.x | 4990.842 | 4088.813 | 1344 JSON::DWIW/DS | 86302.551 | 102300.098 |
1331 JSON::DWIW | 51653.990 | 71575.154 | 1345 JSON::DWIW/FJ | 86302.551 | 75983.768 |
1332 JSON::PC | 65948.176 | 74631.744 | 1346 JSON::PP | 15827.562 | 6638.658 |
1333 JSON::PP | 8931.652 | 3817.168 | 1347 JSON::Syck | 63358.066 | 47662.545 |
1334 JSON::Syck | 24877.248 | 27776.848 | 1348 JSON::XS | 511500.488 | 511500.488 |
1335 JSON::XS | 388361.481 | 227951.304 | 1349 JSON::XS/2 | 291271.111 | 388361.481 |
1336 JSON::XS/2 | 227951.304 | 218453.333 | 1350 JSON::XS/3 | 361577.931 | 361577.931 |
1337 JSON::XS/3 | 338250.323 | 218453.333 | 1351 Storable | 66788.280 | 265462.278 |
1338 Storable | 16500.016 | 135300.129 |
1339 -----------+------------+------------+ 1352 --------------+------------+------------+
1340 1353
1341That is, JSON::XS is about five times faster than JSON::DWIW on encoding, 1354That is, JSON::XS is almost six times faster than JSON::DWIW on encoding,
1342about three times faster on decoding, and over forty times faster 1355about five times faster on decoding, and over thirty to seventy times
1343than JSON, even with pretty-printing and key sorting. It also compares 1356faster than JSON's pure perl implementation. It also compares favourably
1344favourably to Storable for small amounts of data. 1357to Storable for small amounts of data.
1345 1358
1346Using a longer test string (roughly 18KB, generated from Yahoo! Locals 1359Using a longer test string (roughly 18KB, generated from Yahoo! Locals
1347search API (L<http://dist.schmorp.de/misc/json/long.json>). 1360search API (L<http://dist.schmorp.de/misc/json/long.json>).
1348 1361
1349 module | encode | decode | 1362 module | encode | decode |
1350 -----------|------------|------------| 1363 --------------|------------|------------|
1351 JSON 1.x | 55.260 | 34.971 | 1364 JSON::DWIW/DS | 1647.927 | 2673.916 |
1352 JSON::DWIW | 825.228 | 1082.513 | 1365 JSON::DWIW/FJ | 1630.249 | 2596.128 |
1353 JSON::PC | 3571.444 | 2394.829 |
1354 JSON::PP | 210.987 | 32.574 | 1366 JSON::PP | 400.640 | 62.311 |
1355 JSON::Syck | 552.551 | 787.544 | 1367 JSON::Syck | 1481.040 | 1524.869 |
1356 JSON::XS | 5780.463 | 4854.519 | 1368 JSON::XS | 20661.596 | 9541.183 |
1357 JSON::XS/2 | 3869.998 | 4798.975 | 1369 JSON::XS/2 | 10683.403 | 9416.938 |
1358 JSON::XS/3 | 5862.880 | 4798.975 | 1370 JSON::XS/3 | 20661.596 | 9400.054 |
1359 Storable | 4445.002 | 5235.027 | 1371 Storable | 19765.806 | 10000.725 |
1360 -----------+------------+------------+ 1372 --------------+------------+------------+
1361 1373
1362Again, JSON::XS leads by far (except for Storable which non-surprisingly 1374Again, JSON::XS leads by far (except for Storable which non-surprisingly
1363decodes faster). 1375decodes a bit faster).
1364 1376
1365On large strings containing lots of high Unicode characters, some modules 1377On large strings containing lots of high Unicode characters, some modules
1366(such as JSON::PC) seem to decode faster than JSON::XS, but the result 1378(such as JSON::PC) seem to decode faster than JSON::XS, but the result
1367will be broken due to missing (or wrong) Unicode handling. Others refuse 1379will be broken due to missing (or wrong) Unicode handling. Others refuse
1368to decode or encode properly, so it was impossible to prepare a fair 1380to decode or encode properly, so it was impossible to prepare a fair
… …
1404information you might want to make sure that exceptions thrown by JSON::XS 1416information you might want to make sure that exceptions thrown by JSON::XS
1405will not end up in front of untrusted eyes. 1417will not end up in front of untrusted eyes.
1406 1418
1407If you are using JSON::XS to return packets to consumption 1419If you are using JSON::XS to return packets to consumption
1408by JavaScript scripts in a browser you should have a look at 1420by JavaScript scripts in a browser you should have a look at
1409L<http://jpsykes.com/47/practical-csrf-and-json-security> to see whether 1421L<http://blog.archive.jpsykes.com/47/practical-csrf-and-json-security/> to
1410you are vulnerable to some common attack vectors (which really are browser 1422see whether you are vulnerable to some common attack vectors (which really
1411design bugs, but it is still you who will have to deal with it, as major 1423are browser design bugs, but it is still you who will have to deal with
1412browser developers care only for features, not about getting security 1424it, as major browser developers care only for features, not about getting
1413right). 1425security right).
1414 1426
1415 1427
1416=head1 THREADS 1428=head1 THREADS
1417 1429
1418This module is I<not> guaranteed to be thread safe and there are no 1430This module is I<not> guaranteed to be thread safe and there are no

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines