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

Comparing JSON-XS/README (file contents):
Revision 1.6 by root, Sat Mar 24 19:42:14 2007 UTC vs.
Revision 1.8 by root, Sun Mar 25 22:11:06 2007 UTC

… …
2 JSON::XS - JSON serialising/deserialising, done correctly and fast 2 JSON::XS - JSON serialising/deserialising, done correctly and fast
3 3
4SYNOPSIS 4SYNOPSIS
5 use JSON::XS; 5 use JSON::XS;
6 6
7 # exported functions, croak on error 7 # exported functions, they croak on error
8 # and expect/generate UTF-8
8 9
9 $utf8_encoded_json_text = to_json $perl_hash_or_arrayref; 10 $utf8_encoded_json_text = to_json $perl_hash_or_arrayref;
10 $perl_hash_or_arrayref = from_json $utf8_encoded_json_text; 11 $perl_hash_or_arrayref = from_json $utf8_encoded_json_text;
11 12
13 # objToJson and jsonToObj aliases to to_json and from_json
14 # are exported for compatibility to the JSON module,
15 # but should not be used in new code.
16
12 # oo-interface 17 # OO-interface
13 18
14 $coder = JSON::XS->new->ascii->pretty->allow_nonref; 19 $coder = JSON::XS->new->ascii->pretty->allow_nonref;
15 $pretty_printed_unencoded = $coder->encode ($perl_scalar); 20 $pretty_printed_unencoded = $coder->encode ($perl_scalar);
16 $perl_scalar = $coder->decode ($unicode_json_text); 21 $perl_scalar = $coder->decode ($unicode_json_text);
17 22
… …
30 35
31 See MAPPING, below, on how JSON::XS maps perl values to JSON values and 36 See MAPPING, below, on how JSON::XS maps perl values to JSON values and
32 vice versa. 37 vice versa.
33 38
34 FEATURES 39 FEATURES
35 * correct handling of unicode issues 40 * correct unicode handling
36 This module knows how to handle Unicode, and even documents how and 41 This module knows how to handle Unicode, and even documents how and
37 when it does so. 42 when it does so.
38 43
39 * round-trip integrity 44 * round-trip integrity
40 When you serialise a perl data structure using only datatypes 45 When you serialise a perl data structure using only datatypes
41 supported by JSON, the deserialised data structure is identical on 46 supported by JSON, the deserialised data structure is identical on
42 the Perl level. (e.g. the string "2.0" doesn't suddenly become "2"). 47 the Perl level. (e.g. the string "2.0" doesn't suddenly become "2"
48 just because it looks like a number).
43 49
44 * strict checking of JSON correctness 50 * strict checking of JSON correctness
45 There is no guessing, no generating of illegal JSON texts by 51 There is no guessing, no generating of illegal JSON texts by
46 default, and only JSON is accepted as input by default (the latter 52 default, and only JSON is accepted as input by default (the latter
47 is a security feature). 53 is a security feature).
… …
55 interface. 61 interface.
56 62
57 * reasonably versatile output formats 63 * reasonably versatile output formats
58 You can choose between the most compact guarenteed single-line 64 You can choose between the most compact guarenteed single-line
59 format possible (nice for simple line-based protocols), a pure-ascii 65 format possible (nice for simple line-based protocols), a pure-ascii
60 format (for when your transport is not 8-bit clean), or a 66 format (for when your transport is not 8-bit clean, still supports
61 pretty-printed format (for when you want to read that stuff). Or you 67 the whole unicode range), or a pretty-printed format (for when you
62 can combine those features in whatever way you like. 68 want to read that stuff). Or you can combine those features in
69 whatever way you like.
63 70
64FUNCTIONAL INTERFACE 71FUNCTIONAL INTERFACE
65 The following convinience methods are provided by this module. They are 72 The following convinience methods are provided by this module. They are
66 exported by default: 73 exported by default:
67 74
… …
252 In the future, this setting might control other things, such as 259 In the future, this setting might control other things, such as
253 converting strings that look like integers or floats into integers 260 converting strings that look like integers or floats into integers
254 or floats internally (there is no difference on the Perl level), 261 or floats internally (there is no difference on the Perl level),
255 saving space. 262 saving space.
256 263
264 $json = $json->max_depth ([$maximum_nesting_depth])
265 Sets the maximum nesting level (default 8192) accepted while
266 encoding or decoding. If the JSON text or Perl data structure has an
267 equal or higher nesting level then this limit, then the encoder and
268 decoder will stop and croak at that point.
269
270 Nesting level is defined by number of hash- or arrayrefs that the
271 encoder needs to traverse to reach a given point or the number of
272 "{" or "[" characters without their matching closing parenthesis
273 crossed to reach a given character in a string.
274
275 Setting the maximum depth to one disallows any nesting, so that
276 ensures that the object is only a single hash/object or array.
277
278 The argument to "max_depth" will be rounded up to the next nearest
279 power of two.
280
281 See SECURITY CONSIDERATIONS, below, for more info on why this is
282 useful.
283
257 $json_text = $json->encode ($perl_scalar) 284 $json_text = $json->encode ($perl_scalar)
258 Converts the given Perl data structure (a simple scalar or a 285 Converts the given Perl data structure (a simple scalar or a
259 reference to a hash or array) to its JSON representation. Simple 286 reference to a hash or array) to its JSON representation. Simple
260 scalars will be converted into JSON string or number sequences, 287 scalars will be converted into JSON string or number sequences,
261 while references to arrays become JSON arrays and references to 288 while references to arrays become JSON arrays and references to
… …
457 tables. They have been generated with the help of the "eg/bench" program 484 tables. They have been generated with the help of the "eg/bench" program
458 in the JSON::XS distribution, to make it easy to compare on your own 485 in the JSON::XS distribution, to make it easy to compare on your own
459 system. 486 system.
460 487
461 First comes a comparison between various modules using a very short JSON 488 First comes a comparison between various modules using a very short JSON
462 string (83 bytes), showing the number of encodes/decodes per second 489 string:
463 (JSON::XS is the functional interface, while JSON::XS/2 is the OO 490
491 {"method": "handleMessage", "params": ["user1", "we were just talking"], "id": null}
492
493 It shows the number of encodes/decodes per second (JSON::XS uses the
494 functional interface, while JSON::XS/2 uses the OO interface with
464 interface with pretty-printing and hashkey sorting enabled). Higher is 495 pretty-printing and hashkey sorting enabled). Higher is better:
465 better:
466 496
467 module | encode | decode | 497 module | encode | decode |
468 -----------|------------|------------| 498 -----------|------------|------------|
469 JSON | 14006 | 6820 | 499 JSON | 11488.516 | 7823.035 |
470 JSON::DWIW | 200937 | 120386 | 500 JSON::DWIW | 94708.054 | 129094.260 |
471 JSON::PC | 85065 | 129366 | 501 JSON::PC | 63884.157 | 128528.212 |
472 JSON::Syck | 59898 | 44232 | 502 JSON::Syck | 34898.677 | 42096.911 |
473 JSON::XS | 1171478 | 342435 | 503 JSON::XS | 654027.064 | 396423.669 |
474 JSON::XS/2 | 730760 | 328714 | 504 JSON::XS/2 | 371564.190 | 371725.613 |
475 -----------+------------+------------+ 505 -----------+------------+------------+
476 506
477 That is, JSON::XS is 6 times faster than than JSON::DWIW and about 80 507 That is, JSON::XS is more than six times faster than JSON::DWIW on
508 encoding, more than three times faster on decoding, and about thirty
478 times faster than JSON, even with pretty-printing and key sorting. 509 times faster than JSON, even with pretty-printing and key sorting.
479 510
480 Using a longer test string (roughly 18KB, generated from Yahoo! Locals 511 Using a longer test string (roughly 18KB, generated from Yahoo! Locals
481 search API (http://nanoref.com/yahooapis/mgPdGg): 512 search API (http://nanoref.com/yahooapis/mgPdGg):
482 513
483 module | encode | decode | 514 module | encode | decode |
484 -----------|------------|------------| 515 -----------|------------|------------|
485 JSON | 673 | 38 | 516 JSON | 273.023 | 44.674 |
486 JSON::DWIW | 5271 | 770 | 517 JSON::DWIW | 1089.383 | 1145.704 |
487 JSON::PC | 9901 | 2491 | 518 JSON::PC | 3097.419 | 2393.921 |
488 JSON::Syck | 2360 | 786 | 519 JSON::Syck | 514.060 | 843.053 |
489 JSON::XS | 37398 | 3202 | 520 JSON::XS | 6479.668 | 3636.364 |
490 JSON::XS/2 | 13765 | 3153 | 521 JSON::XS/2 | 3774.221 | 3599.124 |
491 -----------+------------+------------+ 522 -----------+------------+------------+
492 523
493 Again, JSON::XS leads by far in the encoding case, while still beating 524 Again, JSON::XS leads by far.
494 every other module in the decoding case.
495 525
496 On large strings containing lots of unicode characters, some modules 526 On large strings containing lots of high unicode characters, some
497 (such as JSON::PC) decode faster than JSON::XS, but the result will be 527 modules (such as JSON::PC) seem to decode faster than JSON::XS, but the
498 broken due to missing unicode handling. Others refuse to decode or 528 result will be broken due to missing (or wrong) unicode handling. Others
499 encode properly, so it was impossible to prepare a fair comparison table 529 refuse to decode or encode properly, so it was impossible to prepare a
500 for that case. 530 fair comparison table for that case.
501 531
502RESOURCE LIMITS 532SECURITY CONSIDERATIONS
503 JSON::XS does not impose any limits on the size of JSON texts or Perl 533 When you are using JSON in a protocol, talking to untrusted potentially
504 values they represent - if your machine can handle it, JSON::XS will 534 hostile creatures requires relatively few measures.
505 encode or decode it. Future versions might optionally impose structure 535
506 depth and memory use resource limits. 536 First of all, your JSON decoder should be secure, that is, should not
537 have any buffer overflows. Obviously, this module should ensure that and
538 I am trying hard on making that true, but you never know.
539
540 Second, you need to avoid resource-starving attacks. That means you
541 should limit the size of JSON texts you accept, or make sure then when
542 your resources run out, thats just fine (e.g. by using a separate
543 process that can crash safely). The size of a JSON text in octets or
544 characters is usually a good indication of the size of the resources
545 required to decode it into a Perl structure.
546
547 Third, JSON::XS recurses using the C stack when decoding objects and
548 arrays. The C stack is a limited resource: for instance, on my amd64
549 machine with 8MB of stack size I can decode around 180k nested arrays
550 but only 14k nested JSON objects. If that is exceeded, the program
551 crashes. Thats why the default nesting limit is set to 8192. If your
552 process has a smaller stack, you should adjust this setting accordingly
553 with the "max_depth" method.
554
555 And last but least, something else could bomb you that I forgot to think
556 of. In that case, you get to keep the pieces. I am alway sopen for
557 hints, though...
507 558
508BUGS 559BUGS
509 While the goal of this module is to be correct, that unfortunately does 560 While the goal of this module is to be correct, that unfortunately does
510 not mean its bug-free, only that I think its design is bug-free. It is 561 not mean its bug-free, only that I think its design is bug-free. It is
511 still very young and not well-tested. If you keep reporting bugs they 562 still relatively early in its development. If you keep reporting bugs
512 will be fixed swiftly, though. 563 they will be fixed swiftly, though.
513 564
514AUTHOR 565AUTHOR
515 Marc Lehmann <schmorp@schmorp.de> 566 Marc Lehmann <schmorp@schmorp.de>
516 http://home.schmorp.de/ 567 http://home.schmorp.de/
517 568

Diff Legend

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