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

Comparing JSON-XS/README (file contents):
Revision 1.7 by root, Sun Mar 25 00:47:42 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
… …
500 modules (such as JSON::PC) seem to decode faster than JSON::XS, but the 527 modules (such as JSON::PC) seem to decode faster than JSON::XS, but the
501 result will be broken due to missing (or wrong) unicode handling. Others 528 result will be broken due to missing (or wrong) unicode handling. Others
502 refuse to decode or encode properly, so it was impossible to prepare a 529 refuse to decode or encode properly, so it was impossible to prepare a
503 fair comparison table for that case. 530 fair comparison table for that case.
504 531
505RESOURCE LIMITS 532SECURITY CONSIDERATIONS
506 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
507 values they represent - if your machine can handle it, JSON::XS will 534 hostile creatures requires relatively few measures.
508 encode or decode it. Future versions might optionally impose structure 535
509 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...
510 558
511BUGS 559BUGS
512 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
513 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
514 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
515 will be fixed swiftly, though. 563 they will be fixed swiftly, though.
516 564
517AUTHOR 565AUTHOR
518 Marc Lehmann <schmorp@schmorp.de> 566 Marc Lehmann <schmorp@schmorp.de>
519 http://home.schmorp.de/ 567 http://home.schmorp.de/
520 568

Diff Legend

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