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

Comparing JSON-XS/README (file contents):
Revision 1.1 by root, Thu Mar 22 16:40:16 2007 UTC vs.
Revision 1.8 by root, Sun Mar 25 22:11:06 2007 UTC

1NAME 1NAME
2 Convert::Scalar - convert between different representations of perl 2 JSON::XS - JSON serialising/deserialising, done correctly and fast
3 scalars
4 3
5SYNOPSIS 4SYNOPSIS
6 use Convert::Scalar; 5 use JSON::XS;
6
7 # exported functions, they croak on error
8 # and expect/generate UTF-8
9
10 $utf8_encoded_json_text = to_json $perl_hash_or_arrayref;
11 $perl_hash_or_arrayref = from_json $utf8_encoded_json_text;
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
17 # OO-interface
18
19 $coder = JSON::XS->new->ascii->pretty->allow_nonref;
20 $pretty_printed_unencoded = $coder->encode ($perl_scalar);
21 $perl_scalar = $coder->decode ($unicode_json_text);
7 22
8DESCRIPTION 23DESCRIPTION
9 This module exports various internal perl methods that change the 24 This module converts Perl data structures to JSON and vice versa. Its
10 internal representation or state of a perl scalar. All of these work 25 primary goal is to be *correct* and its secondary goal is to be *fast*.
11 in-place, that is, they modify their scalar argument. No functions are 26 To reach the latter goal it was written in C.
27
28 As this is the n-th-something JSON module on CPAN, what was the reason
29 to write yet another JSON module? While it seems there are many JSON
30 modules, none of them correctly handle all corner cases, and in most
31 cases their maintainers are unresponsive, gone missing, or not listening
32 to bug reports for other reasons.
33
34 See COMPARISON, below, for a comparison to some other JSON modules.
35
36 See MAPPING, below, on how JSON::XS maps perl values to JSON values and
37 vice versa.
38
39 FEATURES
40 * correct unicode handling
41 This module knows how to handle Unicode, and even documents how and
42 when it does so.
43
44 * round-trip integrity
45 When you serialise a perl data structure using only datatypes
46 supported by JSON, the deserialised data structure is identical on
47 the Perl level. (e.g. the string "2.0" doesn't suddenly become "2"
48 just because it looks like a number).
49
50 * strict checking of JSON correctness
51 There is no guessing, no generating of illegal JSON texts by
52 default, and only JSON is accepted as input by default (the latter
53 is a security feature).
54
55 * fast
56 Compared to other JSON modules, this module compares favourably in
57 terms of speed, too.
58
59 * simple to use
60 This module has both a simple functional interface as well as an OO
61 interface.
62
63 * reasonably versatile output formats
64 You can choose between the most compact guarenteed single-line
65 format possible (nice for simple line-based protocols), a pure-ascii
66 format (for when your transport is not 8-bit clean, still supports
67 the whole unicode range), or a pretty-printed format (for when you
68 want to read that stuff). Or you can combine those features in
69 whatever way you like.
70
71FUNCTIONAL INTERFACE
72 The following convinience methods are provided by this module. They are
12 exported by default. 73 exported by default:
13 74
14 The following export tags exist: 75 $json_text = to_json $perl_scalar
76 Converts the given Perl data structure (a simple scalar or a
77 reference to a hash or array) to a UTF-8 encoded, binary string
78 (that is, the string contains octets only). Croaks on error.
15 79
16 :utf8 all functions with utf8 in their name 80 This function call is functionally identical to:
17 :taint all functions with taint in their name
18 :refcnt all functions with refcnt in their name
19 :ok all *ok-functions.
20 81
21 utf8 scalar[, mode] 82 $json_text = JSON::XS->new->utf8->encode ($perl_scalar)
22 Returns true when the given scalar is marked as utf8, false
23 otherwise. If the optional mode argument is given, also forces the
24 interpretation of the string to utf8 (mode true) or plain bytes
25 (mode false). The actual (byte-) content is not changed. The return
26 value always reflects the state before any modification is done.
27 83
28 This function is useful when you "import" utf8-data into perl, or 84 except being faster.
29 when some external function (e.g. storing/retrieving from a
30 database) removes the utf8-flag.
31 85
32 utf8_on scalar 86 $perl_scalar = from_json $json_text
33 Similar to "utf8 scalar, 1", but additionally returns the scalar 87 The opposite of "to_json": expects an UTF-8 (binary) string and
34 (the argument is still modified in-place). 88 tries to parse that as an UTF-8 encoded JSON text, returning the
89 resulting simple scalar or reference. Croaks on error.
35 90
36 utf8_off scalar 91 This function call is functionally identical to:
37 Similar to "utf8 scalar, 0", but additionally returns the scalar
38 (the argument is still modified in-place).
39 92
40 utf8_valid scalar [Perl 5.7] 93 $perl_scalar = JSON::XS->new->utf8->decode ($json_text)
41 Returns true if the bytes inside the scalar form a valid utf8
42 string, false otherwise (the check is independent of the actual
43 encoding perl thinks the string is in).
44 94
45 utf8_upgrade scalar 95 except being faster.
46 Convert the string content of the scalar in-place to its
47 UTF8-encoded form (and also returns it).
48 96
49 utf8_downgrade scalar[, fail_ok=0] 97OBJECT-ORIENTED INTERFACE
50 Attempt to convert the string content of the scalar from 98 The object oriented interface lets you configure your own encoding or
51 UTF8-encoded to ISO-8859-1. This may not be possible if the string 99 decoding style, within the limits of supported formats.
52 contains characters that cannot be represented in a single byte; if
53 this is the case, it leaves the scalar unchanged and either returns
54 false or, if "fail_ok" is not true (the default), croaks.
55 100
56 utf8_encode scalar 101 $json = new JSON::XS
57 Convert the string value of the scalar to UTF8-encoded, but then 102 Creates a new JSON::XS object that can be used to de/encode JSON
58 turn off the "SvUTF8" flag so that it looks like bytes to perl 103 strings. All boolean flags described below are by default
59 again. (Might be removed in future versions). 104 *disabled*.
60 105
61 utf8_length scalar 106 The mutators for flags all return the JSON object again and thus
62 Returns the number of characters in the string, counting wide UTF8 107 calls can be chained:
63 characters as a single character, independent of wether the scalar
64 is marked as containing bytes or mulitbyte characters.
65 108
66 unmagic scalar, type 109 my $json = JSON::XS->new->utf8->space_after->encode ({a => [1,2]})
67 Remove the specified magic from the scalar (DANGEROUS!). 110 => {"a": [1, 2]}
68 111
69 weaken scalar 112 $json = $json->ascii ([$enable])
70 Weaken a reference. (See also WeakRef). 113 If $enable is true (or missing), then the "encode" method will not
114 generate characters outside the code range 0..127 (which is ASCII).
115 Any unicode characters outside that range will be escaped using
116 either a single \uXXXX (BMP characters) or a double \uHHHH\uLLLLL
117 escape sequence, as per RFC4627.
71 118
72 taint scalar 119 If $enable is false, then the "encode" method will not escape
73 Taint the scalar. 120 Unicode characters unless required by the JSON syntax. This results
121 in a faster and more compact format.
74 122
75 tainted scalar 123 JSON::XS->new->ascii (1)->encode ([chr 0x10401])
76 returns true when the scalar is tainted, false otherwise. 124 => ["\ud801\udc01"]
77 125
78 untaint scalar 126 $json = $json->utf8 ([$enable])
79 Remove the tainted flag from the specified scalar. 127 If $enable is true (or missing), then the "encode" method will
128 encode the JSON result into UTF-8, as required by many protocols,
129 while the "decode" method expects to be handled an UTF-8-encoded
130 string. Please note that UTF-8-encoded strings do not contain any
131 characters outside the range 0..255, they are thus useful for
132 bytewise/binary I/O. In future versions, enabling this option might
133 enable autodetection of the UTF-16 and UTF-32 encoding families, as
134 described in RFC4627.
80 135
81 grow scalar, newlen 136 If $enable is false, then the "encode" method will return the JSON
82 Sets the memory area used for the scalar to the given length, if the 137 string as a (non-encoded) unicode string, while "decode" expects
83 current length is less than the new value. This does not affect the 138 thus a unicode string. Any decoding or encoding (e.g. to UTF-8 or
84 contents of the scalar, but is only useful to "pre-allocate" memory 139 UTF-16) needs to be done yourself, e.g. using the Encode module.
85 space if you know the scalar will grow. The return value is the
86 modified scalar (the scalar is modified in-place).
87 140
88 refcnt scalar[, newrefcnt] 141 Example, output UTF-16BE-encoded JSON:
89 Returns the current reference count of the given scalar and
90 optionally sets it to the given reference count.
91 142
92 refcnt_inc scalar 143 use Encode;
93 Increments the reference count of the given scalar inplace. 144 $jsontext = encode "UTF-16BE", JSON::XS->new->encode ($object);
94 145
95 refcnt_dec scalar 146 Example, decode UTF-32LE-encoded JSON:
96 Decrements the reference count of the given scalar inplace. Use
97 "weaken" instead if you understand what this function is fore.
98 Better yet: don't use this module in this case.
99 147
100 refcnt_rv scalar[, newrefcnt] 148 use Encode;
101 Works like "refcnt", but dereferences the given reference first. 149 $object = JSON::XS->new->decode (decode "UTF-32LE", $jsontext);
102 This is useful to find the reference count of arrays or hashes,
103 which cnanot be passed directly. Remember that taking a reference of
104 some object increases it's reference count, so the reference count
105 used by the *_rv-functions tend to be one higher.
106 150
107 refcnt_inc_rv scalar 151 $json = $json->pretty ([$enable])
108 Works like "refcnt_inc", but dereferences the given reference first. 152 This enables (or disables) all of the "indent", "space_before" and
153 "space_after" (and in the future possibly more) flags in one call to
154 generate the most readable (or most compact) form possible.
109 155
110 refcnt_dec_rv scalar 156 Example, pretty-print some simple structure:
111 Works like "refcnt_dec", but dereferences the given reference first.
112 157
113 ok scalar 158 my $json = JSON::XS->new->pretty(1)->encode ({a => [1,2]})
114 uok scalar 159 =>
115 rok scalar 160 {
161 "a" : [
162 1,
163 2
164 ]
165 }
166
167 $json = $json->indent ([$enable])
168 If $enable is true (or missing), then the "encode" method will use a
169 multiline format as output, putting every array member or
170 object/hash key-value pair into its own line, identing them
171 properly.
172
173 If $enable is false, no newlines or indenting will be produced, and
174 the resulting JSON text is guarenteed not to contain any "newlines".
175
176 This setting has no effect when decoding JSON texts.
177
178 $json = $json->space_before ([$enable])
179 If $enable is true (or missing), then the "encode" method will add
180 an extra optional space before the ":" separating keys from values
181 in JSON objects.
182
183 If $enable is false, then the "encode" method will not add any extra
184 space at those places.
185
186 This setting has no effect when decoding JSON texts. You will also
187 most likely combine this setting with "space_after".
188
189 Example, space_before enabled, space_after and indent disabled:
190
191 {"key" :"value"}
192
193 $json = $json->space_after ([$enable])
194 If $enable is true (or missing), then the "encode" method will add
195 an extra optional space after the ":" separating keys from values in
196 JSON objects and extra whitespace after the "," separating key-value
197 pairs and array members.
198
199 If $enable is false, then the "encode" method will not add any extra
200 space at those places.
201
202 This setting has no effect when decoding JSON texts.
203
204 Example, space_before and indent disabled, space_after enabled:
205
206 {"key": "value"}
207
208 $json = $json->canonical ([$enable])
209 If $enable is true (or missing), then the "encode" method will
210 output JSON objects by sorting their keys. This is adding a
211 comparatively high overhead.
212
213 If $enable is false, then the "encode" method will output key-value
214 pairs in the order Perl stores them (which will likely change
215 between runs of the same script).
216
217 This option is useful if you want the same data structure to be
218 encoded as the same JSON text (given the same overall settings). If
219 it is disabled, the same hash migh be encoded differently even if
220 contains the same data, as key-value pairs have no inherent ordering
221 in Perl.
222
223 This setting has no effect when decoding JSON texts.
224
225 $json = $json->allow_nonref ([$enable])
226 If $enable is true (or missing), then the "encode" method can
227 convert a non-reference into its corresponding string, number or
228 null JSON value, which is an extension to RFC4627. Likewise,
229 "decode" will accept those JSON values instead of croaking.
230
231 If $enable is false, then the "encode" method will croak if it isn't
232 passed an arrayref or hashref, as JSON texts must either be an
233 object or array. Likewise, "decode" will croak if given something
234 that is not a JSON object or array.
235
236 Example, encode a Perl scalar as JSON value with enabled
237 "allow_nonref", resulting in an invalid JSON text:
238
239 JSON::XS->new->allow_nonref->encode ("Hello, World!")
240 => "Hello, World!"
241
242 $json = $json->shrink ([$enable])
243 Perl usually over-allocates memory a bit when allocating space for
244 strings. This flag optionally resizes strings generated by either
245 "encode" or "decode" to their minimum size possible. This can save
246 memory when your JSON texts are either very very long or you have
247 many short strings. It will also try to downgrade any strings to
248 octet-form if possible: perl stores strings internally either in an
249 encoding called UTF-X or in octet-form. The latter cannot store
250 everything but uses less space in general.
251
252 If $enable is true (or missing), the string returned by "encode"
253 will be shrunk-to-fit, while all strings generated by "decode" will
254 also be shrunk-to-fit.
255
256 If $enable is false, then the normal perl allocation algorithms are
257 used. If you work with your data, then this is likely to be faster.
258
259 In the future, this setting might control other things, such as
260 converting strings that look like integers or floats into integers
261 or floats internally (there is no difference on the Perl level),
262 saving space.
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
284 $json_text = $json->encode ($perl_scalar)
285 Converts the given Perl data structure (a simple scalar or a
286 reference to a hash or array) to its JSON representation. Simple
287 scalars will be converted into JSON string or number sequences,
288 while references to arrays become JSON arrays and references to
289 hashes become JSON objects. Undefined Perl values (e.g. "undef")
290 become JSON "null" values. Neither "true" nor "false" values will be
291 generated.
292
293 $perl_scalar = $json->decode ($json_text)
294 The opposite of "encode": expects a JSON text and tries to parse it,
295 returning the resulting simple scalar or reference. Croaks on error.
296
297 JSON numbers and strings become simple Perl scalars. JSON arrays
298 become Perl arrayrefs and JSON objects become Perl hashrefs. "true"
299 becomes 1, "false" becomes 0 and "null" becomes "undef".
300
301MAPPING
302 This section describes how JSON::XS maps Perl values to JSON values and
303 vice versa. These mappings are designed to "do the right thing" in most
304 circumstances automatically, preserving round-tripping characteristics
305 (what you put in comes out as something equivalent).
306
307 For the more enlightened: note that in the following descriptions,
308 lowercase *perl* refers to the Perl interpreter, while uppcercase *Perl*
309 refers to the abstract Perl language itself.
310
311 JSON -> PERL
312 object
313 A JSON object becomes a reference to a hash in Perl. No ordering of
314 object keys is preserved (JSON does not preserver object key
315 ordering itself).
316
317 array
318 A JSON array becomes a reference to an array in Perl.
319
320 string
321 A JSON string becomes a string scalar in Perl - Unicode codepoints
322 in JSON are represented by the same codepoints in the Perl string,
323 so no manual decoding is necessary.
324
325 number
326 A JSON number becomes either an integer or numeric (floating point)
327 scalar in perl, depending on its range and any fractional parts. On
328 the Perl level, there is no difference between those as Perl handles
329 all the conversion details, but an integer may take slightly less
330 memory and might represent more values exactly than (floating point)
331 numbers.
332
333 true, false
334 These JSON atoms become 0, 1, respectively. Information is lost in
335 this process. Future versions might represent those values
336 differently, but they will be guarenteed to act like these integers
337 would normally in Perl.
338
339 null
340 A JSON null atom becomes "undef" in Perl.
341
342 PERL -> JSON
343 The mapping from Perl to JSON is slightly more difficult, as Perl is a
344 truly typeless language, so we can only guess which JSON type is meant
345 by a Perl value.
346
347 hash references
348 Perl hash references become JSON objects. As there is no inherent
349 ordering in hash keys, they will usually be encoded in a
350 pseudo-random order that can change between runs of the same program
351 but stays generally the same within a single run of a program.
352 JSON::XS can optionally sort the hash keys (determined by the
353 *canonical* flag), so the same datastructure will serialise to the
354 same JSON text (given same settings and version of JSON::XS), but
355 this incurs a runtime overhead.
356
357 array references
358 Perl array references become JSON arrays.
359
360 blessed objects
361 Blessed objects are not allowed. JSON::XS currently tries to encode
362 their underlying representation (hash- or arrayref), but this
363 behaviour might change in future versions.
364
116 pok scalar 365 simple scalars
117 nok scalar 366 Simple Perl scalars (any scalar that is not a reference) are the
118 niok scalar 367 most difficult objects to encode: JSON::XS will encode undefined
119 Calls SvOK, SvUOK, SvROK, SvPOK, SvNOK or SvNIOK on the given 368 scalars as JSON null value, scalars that have last been used in a
120 scalar, respectively. 369 string context before encoding as JSON strings and anything else as
370 number value:
121 371
122 CANDIDATES FOR FUTURE RELEASES 372 # dump as number
123 The following API functions (perlapi) are considered for future 373 to_json [2] # yields [2]
124 inclusion in this module If you want them, write me. 374 to_json [-3.0e17] # yields [-3e+17]
375 my $value = 5; to_json [$value] # yields [5]
125 376
126 sv_upgrade 377 # used as string, so dump as string
127 sv_pvn_force 378 print $value;
128 sv_pvutf8n_force 379 to_json [$value] # yields ["5"]
129 the sv2xx family 380
381 # undef becomes null
382 to_json [undef] # yields [null]
383
384 You can force the type to be a string by stringifying it:
385
386 my $x = 3.1; # some variable containing a number
387 "$x"; # stringified
388 $x .= ""; # another, more awkward way to stringify
389 print $x; # perl does it for you, too, quite often
390
391 You can force the type to be a number by numifying it:
392
393 my $x = "3"; # some variable containing a string
394 $x += 0; # numify it, ensuring it will be dumped as a number
395 $x *= 1; # same thing, the choise is yours.
396
397 You can not currently output JSON booleans or force the type in
398 other, less obscure, ways. Tell me if you need this capability.
399
400 circular data structures
401 Those will be encoded until memory or stackspace runs out.
402
403COMPARISON
404 As already mentioned, this module was created because none of the
405 existing JSON modules could be made to work correctly. First I will
406 describe the problems (or pleasures) I encountered with various existing
407 JSON modules, followed by some benchmark values. JSON::XS was designed
408 not to suffer from any of these problems or limitations.
409
410 JSON 1.07
411 Slow (but very portable, as it is written in pure Perl).
412
413 Undocumented/buggy Unicode handling (how JSON handles unicode values
414 is undocumented. One can get far by feeding it unicode strings and
415 doing en-/decoding oneself, but unicode escapes are not working
416 properly).
417
418 No roundtripping (strings get clobbered if they look like numbers,
419 e.g. the string 2.0 will encode to 2.0 instead of "2.0", and that
420 will decode into the number 2.
421
422 JSON::PC 0.01
423 Very fast.
424
425 Undocumented/buggy Unicode handling.
426
427 No roundtripping.
428
429 Has problems handling many Perl values (e.g. regex results and other
430 magic values will make it croak).
431
432 Does not even generate valid JSON ("{1,2}" gets converted to "{1:2}"
433 which is not a valid JSON text.
434
435 Unmaintained (maintainer unresponsive for many months, bugs are not
436 getting fixed).
437
438 JSON::Syck 0.21
439 Very buggy (often crashes).
440
441 Very inflexible (no human-readable format supported, format pretty
442 much undocumented. I need at least a format for easy reading by
443 humans and a single-line compact format for use in a protocol, and
444 preferably a way to generate ASCII-only JSON texts).
445
446 Completely broken (and confusingly documented) Unicode handling
447 (unicode escapes are not working properly, you need to set
448 ImplicitUnicode to *different* values on en- and decoding to get
449 symmetric behaviour).
450
451 No roundtripping (simple cases work, but this depends on wether the
452 scalar value was used in a numeric context or not).
453
454 Dumping hashes may skip hash values depending on iterator state.
455
456 Unmaintained (maintainer unresponsive for many months, bugs are not
457 getting fixed).
458
459 Does not check input for validity (i.e. will accept non-JSON input
460 and return "something" instead of raising an exception. This is a
461 security issue: imagine two banks transfering money between each
462 other using JSON. One bank might parse a given non-JSON request and
463 deduct money, while the other might reject the transaction with a
464 syntax error. While a good protocol will at least recover, that is
465 extra unnecessary work and the transaction will still not succeed).
466
467 JSON::DWIW 0.04
468 Very fast. Very natural. Very nice.
469
470 Undocumented unicode handling (but the best of the pack. Unicode
471 escapes still don't get parsed properly).
472
473 Very inflexible.
474
475 No roundtripping.
476
477 Does not generate valid JSON texts (key strings are often unquoted,
478 empty keys result in nothing being output)
479
480 Does not check input for validity.
481
482 SPEED
483 It seems that JSON::XS is surprisingly fast, as shown in the following
484 tables. They have been generated with the help of the "eg/bench" program
485 in the JSON::XS distribution, to make it easy to compare on your own
486 system.
487
488 First comes a comparison between various modules using a very short JSON
489 string:
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
495 pretty-printing and hashkey sorting enabled). Higher is better:
496
497 module | encode | decode |
498 -----------|------------|------------|
499 JSON | 11488.516 | 7823.035 |
500 JSON::DWIW | 94708.054 | 129094.260 |
501 JSON::PC | 63884.157 | 128528.212 |
502 JSON::Syck | 34898.677 | 42096.911 |
503 JSON::XS | 654027.064 | 396423.669 |
504 JSON::XS/2 | 371564.190 | 371725.613 |
505 -----------+------------+------------+
506
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
509 times faster than JSON, even with pretty-printing and key sorting.
510
511 Using a longer test string (roughly 18KB, generated from Yahoo! Locals
512 search API (http://nanoref.com/yahooapis/mgPdGg):
513
514 module | encode | decode |
515 -----------|------------|------------|
516 JSON | 273.023 | 44.674 |
517 JSON::DWIW | 1089.383 | 1145.704 |
518 JSON::PC | 3097.419 | 2393.921 |
519 JSON::Syck | 514.060 | 843.053 |
520 JSON::XS | 6479.668 | 3636.364 |
521 JSON::XS/2 | 3774.221 | 3599.124 |
522 -----------+------------+------------+
523
524 Again, JSON::XS leads by far.
525
526 On large strings containing lots of high unicode characters, some
527 modules (such as JSON::PC) seem to decode faster than JSON::XS, but the
528 result will be broken due to missing (or wrong) unicode handling. Others
529 refuse to decode or encode properly, so it was impossible to prepare a
530 fair comparison table for that case.
531
532SECURITY CONSIDERATIONS
533 When you are using JSON in a protocol, talking to untrusted potentially
534 hostile creatures requires relatively few measures.
535
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...
558
559BUGS
560 While the goal of this module is to be correct, that unfortunately does
561 not mean its bug-free, only that I think its design is bug-free. It is
562 still relatively early in its development. If you keep reporting bugs
563 they will be fixed swiftly, though.
130 564
131AUTHOR 565AUTHOR
132 Marc Lehmann <schmorp@schmorp.de> 566 Marc Lehmann <schmorp@schmorp.de>
133 http://home.schmorp.de/ 567 http://home.schmorp.de/
134 568

Diff Legend

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