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.9 by root, Thu Mar 29 02:45:49 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
… …
238 "encode" or "decode" to their minimum size possible. This can save 245 "encode" or "decode" to their minimum size possible. This can save
239 memory when your JSON texts are either very very long or you have 246 memory when your JSON texts are either very very long or you have
240 many short strings. It will also try to downgrade any strings to 247 many short strings. It will also try to downgrade any strings to
241 octet-form if possible: perl stores strings internally either in an 248 octet-form if possible: perl stores strings internally either in an
242 encoding called UTF-X or in octet-form. The latter cannot store 249 encoding called UTF-X or in octet-form. The latter cannot store
243 everything but uses less space in general. 250 everything but uses less space in general (and some buggy Perl or C
251 code might even rely on that internal representation being used).
252
253 The actual definition of what shrink does might change in future
254 versions, but it will always try to save space at the expense of
255 time.
244 256
245 If $enable is true (or missing), the string returned by "encode" 257 If $enable is true (or missing), the string returned by "encode"
246 will be shrunk-to-fit, while all strings generated by "decode" will 258 will be shrunk-to-fit, while all strings generated by "decode" will
247 also be shrunk-to-fit. 259 also be shrunk-to-fit.
248 260
… …
251 263
252 In the future, this setting might control other things, such as 264 In the future, this setting might control other things, such as
253 converting strings that look like integers or floats into integers 265 converting strings that look like integers or floats into integers
254 or floats internally (there is no difference on the Perl level), 266 or floats internally (there is no difference on the Perl level),
255 saving space. 267 saving space.
268
269 $json = $json->max_depth ([$maximum_nesting_depth])
270 Sets the maximum nesting level (default 4096) accepted while
271 encoding or decoding. If the JSON text or Perl data structure has an
272 equal or higher nesting level then this limit, then the encoder and
273 decoder will stop and croak at that point.
274
275 Nesting level is defined by number of hash- or arrayrefs that the
276 encoder needs to traverse to reach a given point or the number of
277 "{" or "[" characters without their matching closing parenthesis
278 crossed to reach a given character in a string.
279
280 Setting the maximum depth to one disallows any nesting, so that
281 ensures that the object is only a single hash/object or array.
282
283 The argument to "max_depth" will be rounded up to the next nearest
284 power of two.
285
286 See SECURITY CONSIDERATIONS, below, for more info on why this is
287 useful.
256 288
257 $json_text = $json->encode ($perl_scalar) 289 $json_text = $json->encode ($perl_scalar)
258 Converts the given Perl data structure (a simple scalar or a 290 Converts the given Perl data structure (a simple scalar or a
259 reference to a hash or array) to its JSON representation. Simple 291 reference to a hash or array) to its JSON representation. Simple
260 scalars will be converted into JSON string or number sequences, 292 scalars will be converted into JSON string or number sequences,
… …
317 truly typeless language, so we can only guess which JSON type is meant 349 truly typeless language, so we can only guess which JSON type is meant
318 by a Perl value. 350 by a Perl value.
319 351
320 hash references 352 hash references
321 Perl hash references become JSON objects. As there is no inherent 353 Perl hash references become JSON objects. As there is no inherent
322 ordering in hash keys, they will usually be encoded in a 354 ordering in hash keys (or JSON objects), they will usually be
323 pseudo-random order that can change between runs of the same program 355 encoded in a pseudo-random order that can change between runs of the
324 but stays generally the same within a single run of a program. 356 same program but stays generally the same within a single run of a
325 JSON::XS can optionally sort the hash keys (determined by the 357 program. JSON::XS can optionally sort the hash keys (determined by
326 *canonical* flag), so the same datastructure will serialise to the 358 the *canonical* flag), so the same datastructure will serialise to
327 same JSON text (given same settings and version of JSON::XS), but 359 the same JSON text (given same settings and version of JSON::XS),
328 this incurs a runtime overhead. 360 but this incurs a runtime overhead and is only rarely useful, e.g.
361 when you want to compare some JSON text against another for
362 equality.
329 363
330 array references 364 array references
331 Perl array references become JSON arrays. 365 Perl array references become JSON arrays.
366
367 other references
368 Other unblessed references are generally not allowed and will cause
369 an exception to be thrown, except for references to the integers 0
370 and 1, which get turned into "false" and "true" atoms in JSON. You
371 can also use "JSON::XS::false" and "JSON::XS::true" to improve
372 readability.
373
374 to_json [\0,JSON::XS::true] # yields [false,true]
332 375
333 blessed objects 376 blessed objects
334 Blessed objects are not allowed. JSON::XS currently tries to encode 377 Blessed objects are not allowed. JSON::XS currently tries to encode
335 their underlying representation (hash- or arrayref), but this 378 their underlying representation (hash- or arrayref), but this
336 behaviour might change in future versions. 379 behaviour might change in future versions.
… …
457 tables. They have been generated with the help of the "eg/bench" program 500 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 501 in the JSON::XS distribution, to make it easy to compare on your own
459 system. 502 system.
460 503
461 First comes a comparison between various modules using a very short JSON 504 First comes a comparison between various modules using a very short JSON
462 string (83 bytes), showing the number of encodes/decodes per second 505 string:
463 (JSON::XS is the functional interface, while JSON::XS/2 is the OO 506
507 {"method": "handleMessage", "params": ["user1", "we were just talking"], "id": null}
508
509 It shows the number of encodes/decodes per second (JSON::XS uses the
510 functional interface, while JSON::XS/2 uses the OO interface with
464 interface with pretty-printing and hashkey sorting enabled). Higher is 511 pretty-printing and hashkey sorting enabled). Higher is better:
465 better:
466 512
467 module | encode | decode | 513 module | encode | decode |
468 -----------|------------|------------| 514 -----------|------------|------------|
469 JSON | 14006 | 6820 | 515 JSON | 11488.516 | 7823.035 |
470 JSON::DWIW | 200937 | 120386 | 516 JSON::DWIW | 94708.054 | 129094.260 |
471 JSON::PC | 85065 | 129366 | 517 JSON::PC | 63884.157 | 128528.212 |
472 JSON::Syck | 59898 | 44232 | 518 JSON::Syck | 34898.677 | 42096.911 |
473 JSON::XS | 1171478 | 342435 | 519 JSON::XS | 654027.064 | 396423.669 |
474 JSON::XS/2 | 730760 | 328714 | 520 JSON::XS/2 | 371564.190 | 371725.613 |
475 -----------+------------+------------+ 521 -----------+------------+------------+
476 522
477 That is, JSON::XS is 6 times faster than than JSON::DWIW and about 80 523 That is, JSON::XS is more than six times faster than JSON::DWIW on
524 encoding, more than three times faster on decoding, and about thirty
478 times faster than JSON, even with pretty-printing and key sorting. 525 times faster than JSON, even with pretty-printing and key sorting.
479 526
480 Using a longer test string (roughly 18KB, generated from Yahoo! Locals 527 Using a longer test string (roughly 18KB, generated from Yahoo! Locals
481 search API (http://nanoref.com/yahooapis/mgPdGg): 528 search API (http://nanoref.com/yahooapis/mgPdGg):
482 529
483 module | encode | decode | 530 module | encode | decode |
484 -----------|------------|------------| 531 -----------|------------|------------|
485 JSON | 673 | 38 | 532 JSON | 273.023 | 44.674 |
486 JSON::DWIW | 5271 | 770 | 533 JSON::DWIW | 1089.383 | 1145.704 |
487 JSON::PC | 9901 | 2491 | 534 JSON::PC | 3097.419 | 2393.921 |
488 JSON::Syck | 2360 | 786 | 535 JSON::Syck | 514.060 | 843.053 |
489 JSON::XS | 37398 | 3202 | 536 JSON::XS | 6479.668 | 3636.364 |
490 JSON::XS/2 | 13765 | 3153 | 537 JSON::XS/2 | 3774.221 | 3599.124 |
491 -----------+------------+------------+ 538 -----------+------------+------------+
492 539
493 Again, JSON::XS leads by far in the encoding case, while still beating 540 Again, JSON::XS leads by far.
494 every other module in the decoding case.
495 541
496 On large strings containing lots of unicode characters, some modules 542 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 543 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 544 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 545 refuse to decode or encode properly, so it was impossible to prepare a
500 for that case. 546 fair comparison table for that case.
501 547
502RESOURCE LIMITS 548SECURITY CONSIDERATIONS
503 JSON::XS does not impose any limits on the size of JSON texts or Perl 549 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 550 hostile creatures requires relatively few measures.
505 encode or decode it. Future versions might optionally impose structure 551
506 depth and memory use resource limits. 552 First of all, your JSON decoder should be secure, that is, should not
553 have any buffer overflows. Obviously, this module should ensure that and
554 I am trying hard on making that true, but you never know.
555
556 Second, you need to avoid resource-starving attacks. That means you
557 should limit the size of JSON texts you accept, or make sure then when
558 your resources run out, thats just fine (e.g. by using a separate
559 process that can crash safely). The size of a JSON text in octets or
560 characters is usually a good indication of the size of the resources
561 required to decode it into a Perl structure.
562
563 Third, JSON::XS recurses using the C stack when decoding objects and
564 arrays. The C stack is a limited resource: for instance, on my amd64
565 machine with 8MB of stack size I can decode around 180k nested arrays
566 but only 14k nested JSON objects. If that is exceeded, the program
567 crashes. Thats why the default nesting limit is set to 4096. If your
568 process has a smaller stack, you should adjust this setting accordingly
569 with the "max_depth" method.
570
571 And last but least, something else could bomb you that I forgot to think
572 of. In that case, you get to keep the pieces. I am alway sopen for
573 hints, though...
507 574
508BUGS 575BUGS
509 While the goal of this module is to be correct, that unfortunately does 576 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 577 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 578 still relatively early in its development. If you keep reporting bugs
512 will be fixed swiftly, though. 579 they will be fixed swiftly, though.
513 580
514AUTHOR 581AUTHOR
515 Marc Lehmann <schmorp@schmorp.de> 582 Marc Lehmann <schmorp@schmorp.de>
516 http://home.schmorp.de/ 583 http://home.schmorp.de/
517 584

Diff Legend

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