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.126 by root, Wed Jan 6 08:02:18 2010 UTC vs.
Revision 1.135 by root, Wed Jun 1 13:01:09 2011 UTC

… …
64so, and even documents what "correct" means. 64so, and even documents what "correct" means.
65 65
66=item * round-trip integrity 66=item * round-trip integrity
67 67
68When you serialise a perl data structure using only data types supported 68When you serialise a perl data structure using only data types supported
69by JSON, the deserialised data structure is identical on the Perl level. 69by JSON and Perl, the deserialised data structure is identical on the Perl
70(e.g. the string "2.0" doesn't suddenly become "2" just because it looks 70level. (e.g. the string "2.0" doesn't suddenly become "2" just because
71like a number). There minor I<are> exceptions to this, read the MAPPING 71it looks like a number). There I<are> minor exceptions to this, read the
72section below to learn about those. 72MAPPING section below to learn about those.
73 73
74=item * strict checking of JSON correctness 74=item * strict checking of JSON correctness
75 75
76There is no guessing, no generating of illegal JSON texts by default, 76There is no guessing, no generating of illegal JSON texts by default,
77and only JSON is accepted as input by default (the latter is a security 77and only JSON is accepted as input by default (the latter is a security
… …
101 101
102package JSON::XS; 102package JSON::XS;
103 103
104use common::sense; 104use common::sense;
105 105
106our $VERSION = '2.27'; 106our $VERSION = '2.3';
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($) {
… …
713calls). 713calls).
714 714
715JSON::XS will only attempt to parse the JSON text once it is sure it 715JSON::XS will only attempt to parse the JSON text once it is sure it
716has enough text to get a decisive result, using a very simple but 716has enough text to get a decisive result, using a very simple but
717truly incremental parser. This means that it sometimes won't stop as 717truly incremental parser. This means that it sometimes won't stop as
718early as the full parser, for example, it doesn't detect parenthese 718early as the full parser, for example, it doesn't detect mismatched
719mismatches. The only thing it guarantees is that it starts decoding as 719parentheses. The only thing it guarantees is that it starts decoding as
720soon as a syntactically valid JSON text has been seen. This means you need 720soon as a syntactically valid JSON text has been seen. This means you need
721to set resource limits (e.g. C<max_size>) to ensure the parser will stop 721to set resource limits (e.g. C<max_size>) to ensure the parser will stop
722parsing in the presence if syntax errors. 722parsing in the presence if syntax errors.
723 723
724The following methods implement this incremental parser. 724The following methods implement this incremental parser.
… …
750otherwise. For this to work, there must be no separators between the JSON 750otherwise. For this to work, there must be no separators between the JSON
751objects or arrays, instead they must be concatenated back-to-back. If 751objects or arrays, instead they must be concatenated back-to-back. If
752an 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
753case. 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
754lost. 754lost.
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]");
755 760
756=item $lvalue_string = $json->incr_text 761=item $lvalue_string = $json->incr_text
757 762
758This method returns the currently stored JSON fragment as an lvalue, that 763This method returns the currently stored JSON fragment as an lvalue, that
759is, 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
… …
989Numbers containing a fractional or exponential part will always be 994Numbers containing a fractional or exponential part will always be
990represented as numeric (floating point) values, possibly at a loss of 995represented as numeric (floating point) values, possibly at a loss of
991precision (in which case you might lose perfect roundtripping ability, but 996precision (in which case you might lose perfect roundtripping ability, but
992the JSON number will still be re-encoded as a JSON number). 997the JSON number will still be re-encoded as a JSON number).
993 998
999Note that precision is not accuracy - binary floating point values cannot
1000represent most decimal fractions exactly, and when converting from and to
1001floating point, JSON::XS only guarantees precision up to but not including
1002the leats significant bit.
1003
994=item true, false 1004=item true, false
995 1005
996These JSON atoms become C<JSON::XS::true> and C<JSON::XS::false>, 1006These JSON atoms become C<JSON::XS::true> and C<JSON::XS::false>,
997respectively. They are overloaded to act almost exactly like the numbers 1007respectively. They are overloaded to act almost exactly like the numbers
998C<1> and C<0>. You can check whether a scalar is a JSON boolean by using 1008C<1> and C<0>. You can check whether a scalar is a JSON boolean by using
… …
1085 1095
1086You can not currently force the type in other, less obscure, ways. Tell me 1096You can not currently force the type in other, less obscure, ways. Tell me
1087if you need this capability (but don't forget to explain why it's needed 1097if you need this capability (but don't forget to explain why it's needed
1088:). 1098:).
1089 1099
1100Note that numerical precision has the same meaning as under Perl (so
1101binary to decimal conversion follows the same rules as in Perl, which
1102can differ to other languages). Also, your perl interpreter might expose
1103extensions to the floating point numbers of your platform, such as
1104infinities or NaN's - these cannot be represented in JSON, and it is an
1105error to pass those in.
1106
1090=back 1107=back
1091 1108
1092 1109
1093=head1 ENCODING/CODESET FLAG NOTES 1110=head1 ENCODING/CODESET FLAG NOTES
1094 1111
… …
1238well - using C<eval> naively simply I<will> cause problems. 1255well - using C<eval> naively simply I<will> cause problems.
1239 1256
1240Another problem is that some javascript implementations reserve 1257Another problem is that some javascript implementations reserve
1241some property names for their own purposes (which probably makes 1258some property names for their own purposes (which probably makes
1242them non-ECMAscript-compliant). For example, Iceweasel reserves the 1259them non-ECMAscript-compliant). For example, Iceweasel reserves the
1243C<__proto__> property name for it's own purposes. 1260C<__proto__> property name for its own purposes.
1244 1261
1245If that is a problem, you could parse try to filter the resulting JSON 1262If that is a problem, you could parse try to filter the resulting JSON
1246output for these property strings, e.g.: 1263output for these property strings, e.g.:
1247 1264
1248 $json =~ s/"__proto__"\s*:/"__proto__renamed":/g; 1265 $json =~ s/"__proto__"\s*:/"__proto__renamed":/g;
… …
1302that difficult or long) and finally make YAML compatible to it, and 1319that difficult or long) and finally make YAML compatible to it, and
1303educating users about the changes, instead of spreading lies about the 1320educating users about the changes, instead of spreading lies about the
1304real compatibility for many I<years> and trying to silence people who 1321real compatibility for many I<years> and trying to silence people who
1305point out that it isn't true. 1322point out that it isn't true.
1306 1323
1307Addendum/2009: the YAML 1.2 spec is still incomaptible with JSON, even 1324Addendum/2009: the YAML 1.2 spec is still incompatible with JSON, even
1308though the incompatibilities have been documented (and are known to 1325though the incompatibilities have been documented (and are known to Brian)
1309Brian) for many years and the spec makes explicit claims that YAML is a 1326for many years and the spec makes explicit claims that YAML is a superset
1310superset of JSON. It would be so easy to fix, but apparently, bullying and 1327of JSON. It would be so easy to fix, but apparently, bullying people and
1311corrupting userdata is so much easier. 1328corrupting userdata is so much easier.
1312 1329
1313=back 1330=back
1314 1331
1315 1332
… …
1324a very short single-line JSON string (also available at 1341a very short single-line JSON string (also available at
1325L<http://dist.schmorp.de/misc/json/short.json>). 1342L<http://dist.schmorp.de/misc/json/short.json>).
1326 1343
1327 {"method": "handleMessage", "params": ["user1", 1344 {"method": "handleMessage", "params": ["user1",
1328 "we were just talking"], "id": null, "array":[1,11,234,-5,1e5,1e7, 1345 "we were just talking"], "id": null, "array":[1,11,234,-5,1e5,1e7,
1329 true, false]} 1346 1, 0]}
1330 1347
1331It shows the number of encodes/decodes per second (JSON::XS uses 1348It shows the number of encodes/decodes per second (JSON::XS uses
1332the functional interface, while JSON::XS/2 uses the OO interface 1349the functional interface, while JSON::XS/2 uses the OO interface
1333with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables 1350with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables
1334shrink). Higher is better: 1351shrink. JSON::DWIW/DS uses the deserialise function, while JSON::DWIW::FJ
1352uses the from_json method). Higher is better:
1335 1353
1336 module | encode | decode | 1354 module | encode | decode |
1337 -----------|------------|------------| 1355 --------------|------------|------------|
1338 JSON 1.x | 4990.842 | 4088.813 | 1356 JSON::DWIW/DS | 86302.551 | 102300.098 |
1339 JSON::DWIW | 51653.990 | 71575.154 | 1357 JSON::DWIW/FJ | 86302.551 | 75983.768 |
1340 JSON::PC | 65948.176 | 74631.744 | 1358 JSON::PP | 15827.562 | 6638.658 |
1341 JSON::PP | 8931.652 | 3817.168 | 1359 JSON::Syck | 63358.066 | 47662.545 |
1342 JSON::Syck | 24877.248 | 27776.848 | 1360 JSON::XS | 511500.488 | 511500.488 |
1343 JSON::XS | 388361.481 | 227951.304 | 1361 JSON::XS/2 | 291271.111 | 388361.481 |
1344 JSON::XS/2 | 227951.304 | 218453.333 | 1362 JSON::XS/3 | 361577.931 | 361577.931 |
1345 JSON::XS/3 | 338250.323 | 218453.333 | 1363 Storable | 66788.280 | 265462.278 |
1346 Storable | 16500.016 | 135300.129 |
1347 -----------+------------+------------+ 1364 --------------+------------+------------+
1348 1365
1349That is, JSON::XS is about five times faster than JSON::DWIW on encoding, 1366That is, JSON::XS is almost six times faster than JSON::DWIW on encoding,
1350about three times faster on decoding, and over forty times faster 1367about five times faster on decoding, and over thirty to seventy times
1351than JSON, even with pretty-printing and key sorting. It also compares 1368faster than JSON's pure perl implementation. It also compares favourably
1352favourably to Storable for small amounts of data. 1369to Storable for small amounts of data.
1353 1370
1354Using a longer test string (roughly 18KB, generated from Yahoo! Locals 1371Using a longer test string (roughly 18KB, generated from Yahoo! Locals
1355search API (L<http://dist.schmorp.de/misc/json/long.json>). 1372search API (L<http://dist.schmorp.de/misc/json/long.json>).
1356 1373
1357 module | encode | decode | 1374 module | encode | decode |
1358 -----------|------------|------------| 1375 --------------|------------|------------|
1359 JSON 1.x | 55.260 | 34.971 | 1376 JSON::DWIW/DS | 1647.927 | 2673.916 |
1360 JSON::DWIW | 825.228 | 1082.513 | 1377 JSON::DWIW/FJ | 1630.249 | 2596.128 |
1361 JSON::PC | 3571.444 | 2394.829 |
1362 JSON::PP | 210.987 | 32.574 | 1378 JSON::PP | 400.640 | 62.311 |
1363 JSON::Syck | 552.551 | 787.544 | 1379 JSON::Syck | 1481.040 | 1524.869 |
1364 JSON::XS | 5780.463 | 4854.519 | 1380 JSON::XS | 20661.596 | 9541.183 |
1365 JSON::XS/2 | 3869.998 | 4798.975 | 1381 JSON::XS/2 | 10683.403 | 9416.938 |
1366 JSON::XS/3 | 5862.880 | 4798.975 | 1382 JSON::XS/3 | 20661.596 | 9400.054 |
1367 Storable | 4445.002 | 5235.027 | 1383 Storable | 19765.806 | 10000.725 |
1368 -----------+------------+------------+ 1384 --------------+------------+------------+
1369 1385
1370Again, JSON::XS leads by far (except for Storable which non-surprisingly 1386Again, JSON::XS leads by far (except for Storable which non-surprisingly
1371decodes faster). 1387decodes a bit faster).
1372 1388
1373On large strings containing lots of high Unicode characters, some modules 1389On large strings containing lots of high Unicode characters, some modules
1374(such as JSON::PC) seem to decode faster than JSON::XS, but the result 1390(such as JSON::PC) seem to decode faster than JSON::XS, but the result
1375will be broken due to missing (or wrong) Unicode handling. Others refuse 1391will be broken due to missing (or wrong) Unicode handling. Others refuse
1376to decode or encode properly, so it was impossible to prepare a fair 1392to decode or encode properly, so it was impossible to prepare a fair
… …
1412information you might want to make sure that exceptions thrown by JSON::XS 1428information you might want to make sure that exceptions thrown by JSON::XS
1413will not end up in front of untrusted eyes. 1429will not end up in front of untrusted eyes.
1414 1430
1415If you are using JSON::XS to return packets to consumption 1431If you are using JSON::XS to return packets to consumption
1416by JavaScript scripts in a browser you should have a look at 1432by JavaScript scripts in a browser you should have a look at
1417L<http://jpsykes.com/47/practical-csrf-and-json-security> to see whether 1433L<http://blog.archive.jpsykes.com/47/practical-csrf-and-json-security/> to
1418you are vulnerable to some common attack vectors (which really are browser 1434see whether you are vulnerable to some common attack vectors (which really
1419design bugs, but it is still you who will have to deal with it, as major 1435are browser design bugs, but it is still you who will have to deal with
1420browser developers care only for features, not about getting security 1436it, as major browser developers care only for features, not about getting
1421right). 1437security right).
1422 1438
1423 1439
1424=head1 THREADS 1440=head1 THREADS
1425 1441
1426This module is I<not> guaranteed to be thread safe and there are no 1442This module is I<not> guaranteed to be thread safe and there are no

Diff Legend

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