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.10 by root, Wed Apr 4 00:01:44 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 512) accepted while encoding
271 or decoding. If the JSON text or Perl data structure has an equal or
272 higher nesting level then this limit, then the encoder and decoder
273 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.
… …
367 $x += 0; # numify it, ensuring it will be dumped as a number 410 $x += 0; # numify it, ensuring it will be dumped as a number
368 $x *= 1; # same thing, the choise is yours. 411 $x *= 1; # same thing, the choise is yours.
369 412
370 You can not currently output JSON booleans or force the type in 413 You can not currently output JSON booleans or force the type in
371 other, less obscure, ways. Tell me if you need this capability. 414 other, less obscure, ways. Tell me if you need this capability.
372
373 circular data structures
374 Those will be encoded until memory or stackspace runs out.
375 415
376COMPARISON 416COMPARISON
377 As already mentioned, this module was created because none of the 417 As already mentioned, this module was created because none of the
378 existing JSON modules could be made to work correctly. First I will 418 existing JSON modules could be made to work correctly. First I will
379 describe the problems (or pleasures) I encountered with various existing 419 describe the problems (or pleasures) I encountered with various existing
… …
457 tables. They have been generated with the help of the "eg/bench" program 497 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 498 in the JSON::XS distribution, to make it easy to compare on your own
459 system. 499 system.
460 500
461 First comes a comparison between various modules using a very short JSON 501 First comes a comparison between various modules using a very short JSON
462 string (83 bytes), showing the number of encodes/decodes per second 502 string:
463 (JSON::XS is the functional interface, while JSON::XS/2 is the OO 503
504 {"method": "handleMessage", "params": ["user1", "we were just talking"], "id": null}
505
506 It shows the number of encodes/decodes per second (JSON::XS uses the
507 functional interface, while JSON::XS/2 uses the OO interface with
464 interface with pretty-printing and hashkey sorting enabled). Higher is 508 pretty-printing and hashkey sorting enabled). Higher is better:
465 better:
466 509
467 module | encode | decode | 510 module | encode | decode |
468 -----------|------------|------------| 511 -----------|------------|------------|
469 JSON | 14006 | 6820 | 512 JSON | 11488.516 | 7823.035 |
470 JSON::DWIW | 200937 | 120386 | 513 JSON::DWIW | 94708.054 | 129094.260 |
471 JSON::PC | 85065 | 129366 | 514 JSON::PC | 63884.157 | 128528.212 |
472 JSON::Syck | 59898 | 44232 | 515 JSON::Syck | 34898.677 | 42096.911 |
473 JSON::XS | 1171478 | 342435 | 516 JSON::XS | 654027.064 | 396423.669 |
474 JSON::XS/2 | 730760 | 328714 | 517 JSON::XS/2 | 371564.190 | 371725.613 |
475 -----------+------------+------------+ 518 -----------+------------+------------+
476 519
477 That is, JSON::XS is 6 times faster than than JSON::DWIW and about 80 520 That is, JSON::XS is more than six times faster than JSON::DWIW on
521 encoding, more than three times faster on decoding, and about thirty
478 times faster than JSON, even with pretty-printing and key sorting. 522 times faster than JSON, even with pretty-printing and key sorting.
479 523
480 Using a longer test string (roughly 18KB, generated from Yahoo! Locals 524 Using a longer test string (roughly 18KB, generated from Yahoo! Locals
481 search API (http://nanoref.com/yahooapis/mgPdGg): 525 search API (http://nanoref.com/yahooapis/mgPdGg):
482 526
483 module | encode | decode | 527 module | encode | decode |
484 -----------|------------|------------| 528 -----------|------------|------------|
485 JSON | 673 | 38 | 529 JSON | 273.023 | 44.674 |
486 JSON::DWIW | 5271 | 770 | 530 JSON::DWIW | 1089.383 | 1145.704 |
487 JSON::PC | 9901 | 2491 | 531 JSON::PC | 3097.419 | 2393.921 |
488 JSON::Syck | 2360 | 786 | 532 JSON::Syck | 514.060 | 843.053 |
489 JSON::XS | 37398 | 3202 | 533 JSON::XS | 6479.668 | 3636.364 |
490 JSON::XS/2 | 13765 | 3153 | 534 JSON::XS/2 | 3774.221 | 3599.124 |
491 -----------+------------+------------+ 535 -----------+------------+------------+
492 536
493 Again, JSON::XS leads by far in the encoding case, while still beating 537 Again, JSON::XS leads by far.
494 every other module in the decoding case.
495 538
496 On large strings containing lots of unicode characters, some modules 539 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 540 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 541 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 542 refuse to decode or encode properly, so it was impossible to prepare a
500 for that case. 543 fair comparison table for that case.
501 544
502RESOURCE LIMITS 545SECURITY CONSIDERATIONS
503 JSON::XS does not impose any limits on the size of JSON texts or Perl 546 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 547 hostile creatures requires relatively few measures.
505 encode or decode it. Future versions might optionally impose structure 548
506 depth and memory use resource limits. 549 First of all, your JSON decoder should be secure, that is, should not
550 have any buffer overflows. Obviously, this module should ensure that and
551 I am trying hard on making that true, but you never know.
552
553 Second, you need to avoid resource-starving attacks. That means you
554 should limit the size of JSON texts you accept, or make sure then when
555 your resources run out, thats just fine (e.g. by using a separate
556 process that can crash safely). The size of a JSON text in octets or
557 characters is usually a good indication of the size of the resources
558 required to decode it into a Perl structure.
559
560 Third, JSON::XS recurses using the C stack when decoding objects and
561 arrays. The C stack is a limited resource: for instance, on my amd64
562 machine with 8MB of stack size I can decode around 180k nested arrays
563 but only 14k nested JSON objects (due to perl itself recursing deeply on
564 croak to free the temporary). If that is exceeded, the program crashes.
565 to be conservative, the default nesting limit is set to 512. If your
566 process has a smaller stack, you should adjust this setting accordingly
567 with the "max_depth" method.
568
569 And last but least, something else could bomb you that I forgot to think
570 of. In that case, you get to keep the pieces. I am alway sopen for
571 hints, though...
507 572
508BUGS 573BUGS
509 While the goal of this module is to be correct, that unfortunately does 574 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 575 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 576 still relatively early in its development. If you keep reporting bugs
512 will be fixed swiftly, though. 577 they will be fixed swiftly, though.
513 578
514AUTHOR 579AUTHOR
515 Marc Lehmann <schmorp@schmorp.de> 580 Marc Lehmann <schmorp@schmorp.de>
516 http://home.schmorp.de/ 581 http://home.schmorp.de/
517 582

Diff Legend

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