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

Comparing JSON-XS/README (file contents):
Revision 1.14 by root, Sat Jun 23 23:50:03 2007 UTC vs.
Revision 1.15 by root, Mon Jul 2 08:06:48 2007 UTC

… …
7 # exported functions, they croak on error 7 # exported functions, they croak on error
8 # and expect/generate UTF-8 8 # and expect/generate UTF-8
9 9
10 $utf8_encoded_json_text = to_json $perl_hash_or_arrayref; 10 $utf8_encoded_json_text = to_json $perl_hash_or_arrayref;
11 $perl_hash_or_arrayref = from_json $utf8_encoded_json_text; 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 12
17 # OO-interface 13 # OO-interface
18 14
19 $coder = JSON::XS->new->ascii->pretty->allow_nonref; 15 $coder = JSON::XS->new->ascii->pretty->allow_nonref;
20 $pretty_printed_unencoded = $coder->encode ($perl_scalar); 16 $pretty_printed_unencoded = $coder->encode ($perl_scalar);
… …
277 Example, encode a Perl scalar as JSON value with enabled 273 Example, encode a Perl scalar as JSON value with enabled
278 "allow_nonref", resulting in an invalid JSON text: 274 "allow_nonref", resulting in an invalid JSON text:
279 275
280 JSON::XS->new->allow_nonref->encode ("Hello, World!") 276 JSON::XS->new->allow_nonref->encode ("Hello, World!")
281 => "Hello, World!" 277 => "Hello, World!"
278
279 $json = $json->allow_blessed ([$enable])
280 If $enable is true (or missing), then the "encode" method will not
281 barf when it encounters a blessed reference. Instead, the value of
282 the convert_blessed option will decide wether "null"
283 ("convert_blessed" disabled or no "to_json" method found) or a
284 representation of the object ("convert_blessed" enabled and
285 "to_json" method found) is being encoded. Has no effect on "decode".
286
287 If $enable is false (the default), then "encode" will throw an
288 exception when it encounters a blessed object.
289
290 $json = $json->convert_blessed ([$enable])
291 If $enable is true (or missing), then "encode", upon encountering a
292 blessed object, will check for the availability of the "TO_JSON"
293 method on the object's class. If found, it will be called in scalar
294 context and the resulting scalar will be encoded instead of the
295 object. If no "TO_JSON" method is found, the value of
296 "allow_blessed" will decide what to do.
297
298 The "TO_JSON" method may safely call die if it wants. If "TO_JSON"
299 returns other blessed objects, those will be handled in the same
300 way. "TO_JSON" must take care of not causing an endless recursion
301 cycle (== crash) in this case. The name of "TO_JSON" was chosen
302 because other methods called by the Perl core (== not by the user of
303 the object) are usually in upper case letters and to avoid
304 collisions with the "to_json" function.
305
306 This setting does not yet influence "decode" in any way, but in the
307 future, global hooks might get installed that influence "decode" and
308 are enabled by this setting.
309
310 If $enable is false, then the "allow_blessed" setting will decide
311 what to do when a blessed object is found.
312
313 $json = $json->filter_json_object ([$coderef->($hashref)])
314 When $coderef is specified, it will be called from "decode" each
315 time it decodes a JSON object. The only argument is a reference to
316 the newly-created hash. If the code references returns a single
317 scalar (which need not be a reference), this value (i.e. a copy of
318 that scalar to avoid aliasing) is inserted into the deserialised
319 data structure. If it returns an empty list (NOTE: *not* "undef",
320 which is a valid scalar), the original deserialised hash will be
321 inserted. This setting can slow down decoding considerably.
322
323 When $coderef is omitted or undefined, any existing callback will be
324 removed and "decode" will not change the deserialised hash in any
325 way.
326
327 Example, convert all JSON objects into the integer 5:
328
329 my $js = JSON::XS->new->filter_json_object (sub { 5 });
330 # returns [5]
331 $js->decode ('[{}]')
332 # throw an exception because allow_nonref is not enabled
333 # so a lone 5 is not allowed.
334 $js->decode ('{"a":1, "b":2}');
335
336 $json = $json->filter_json_single_key_object ($key [=>
337 $coderef->($value)])
338 Works remotely similar to "filter_json_object", but is only called
339 for JSON objects having a single key named $key.
340
341 This $coderef is called before the one specified via
342 "filter_json_object", if any. It gets passed the single value in the
343 JSON object. If it returns a single value, it will be inserted into
344 the data structure. If it returns nothing (not even "undef" but the
345 empty list), the callback from "filter_json_object" will be called
346 next, as if no single-key callback were specified.
347
348 If $coderef is omitted or undefined, the corresponding callback will
349 be disabled. There can only ever be one callback for a given key.
350
351 As this callback gets called less often then the
352 "filter_json_object" one, decoding speed will not usually suffer as
353 much. Therefore, single-key objects make excellent targets to
354 serialise Perl objects into, especially as single-key JSON objects
355 are as close to the type-tagged value concept as JSON gets (its
356 basically an ID/VALUE tuple). Of course, JSON does not support this
357 in any way, so you need to make sure your data never looks like a
358 serialised Perl hash.
359
360 Typical names for the single object key are "__class_whatever__", or
361 "$__dollars_are_rarely_used__$" or "}ugly_brace_placement", or even
362 things like "__class_md5sum(classname)__", to reduce the risk of
363 clashing with real hashes.
364
365 Example, decode JSON objects of the form "{ "__widget__" => <id> }"
366 into the corresponding $WIDGET{<id>} object:
367
368 # return whatever is in $WIDGET{5}:
369 JSON::XS
370 ->new
371 ->filter_json_single_key_object (__widget__ => sub {
372 $WIDGET{ $_[0] }
373 })
374 ->decode ('{"__widget__": 5')
375
376 # this can be used with a TO_JSON method in some "widget" class
377 # for serialisation to json:
378 sub WidgetBase::TO_JSON {
379 my ($self) = @_;
380
381 unless ($self->{id}) {
382 $self->{id} = ..get..some..id..;
383 $WIDGET{$self->{id}} = $self;
384 }
385
386 { __widget__ => $self->{id} }
387 }
282 388
283 $json = $json->shrink ([$enable]) 389 $json = $json->shrink ([$enable])
284 Perl usually over-allocates memory a bit when allocating space for 390 Perl usually over-allocates memory a bit when allocating space for
285 strings. This flag optionally resizes strings generated by either 391 strings. This flag optionally resizes strings generated by either
286 "encode" or "decode" to their minimum size possible. This can save 392 "encode" or "decode" to their minimum size possible. This can save
… …
319 crossed to reach a given character in a string. 425 crossed to reach a given character in a string.
320 426
321 Setting the maximum depth to one disallows any nesting, so that 427 Setting the maximum depth to one disallows any nesting, so that
322 ensures that the object is only a single hash/object or array. 428 ensures that the object is only a single hash/object or array.
323 429
324 The argument to "max_depth" will be rounded up to the next nearest 430 The argument to "max_depth" will be rounded up to the next highest
325 power of two. 431 power of two. If no argument is given, the highest possible setting
432 will be used, which is rarely useful.
433
434 See SECURITY CONSIDERATIONS, below, for more info on why this is
435 useful.
436
437 $json = $json->max_size ([$maximum_string_size])
438 Set the maximum length a JSON text may have (in bytes) where
439 decoding is being attempted. The default is 0, meaning no limit.
440 When "decode" is called on a string longer then this number of
441 characters it will not attempt to decode the string but throw an
442 exception. This setting has no effect on "encode" (yet).
443
444 The argument to "max_size" will be rounded up to the next highest
445 power of two (so may be more than requested). If no argument is
446 given, the limit check will be deactivated (same as when 0 is
447 specified).
326 448
327 See SECURITY CONSIDERATIONS, below, for more info on why this is 449 See SECURITY CONSIDERATIONS, below, for more info on why this is
328 useful. 450 useful.
329 451
330 $json_text = $json->encode ($perl_scalar) 452 $json_text = $json->encode ($perl_scalar)
… …
588 It shows the number of encodes/decodes per second (JSON::XS uses the 710 It shows the number of encodes/decodes per second (JSON::XS uses the
589 functional interface, while JSON::XS/2 uses the OO interface with 711 functional interface, while JSON::XS/2 uses the OO interface with
590 pretty-printing and hashkey sorting enabled, JSON::XS/3 enables shrink). 712 pretty-printing and hashkey sorting enabled, JSON::XS/3 enables shrink).
591 Higher is better: 713 Higher is better:
592 714
715 Storable | 15779.925 | 14169.946 |
716 -----------+------------+------------+
593 module | encode | decode | 717 module | encode | decode |
594 -----------|------------|------------| 718 -----------|------------|------------|
595 JSON | 7645.468 | 4208.613 | 719 JSON | 4990.842 | 4088.813 |
596 JSON::DWIW | 40721.398 | 77101.176 | 720 JSON::DWIW | 51653.990 | 71575.154 |
597 JSON::PC | 65948.176 | 78251.940 | 721 JSON::PC | 65948.176 | 74631.744 |
598 JSON::Syck | 22844.793 | 26479.192 | 722 JSON::PP | 8931.652 | 3817.168 |
723 JSON::Syck | 24877.248 | 27776.848 |
599 JSON::XS | 388361.481 | 199728.762 | 724 JSON::XS | 388361.481 | 227951.304 |
600 JSON::XS/2 | 218453.333 | 192399.266 | 725 JSON::XS/2 | 227951.304 | 218453.333 |
601 JSON::XS/3 | 338250.323 | 192399.266 | 726 JSON::XS/3 | 338250.323 | 218453.333 |
602 Storable | 15779.925 | 14169.946 | 727 Storable | 16500.016 | 135300.129 |
603 -----------+------------+------------+ 728 -----------+------------+------------+
604 729
605 That is, JSON::XS is about five times faster than JSON::DWIW on 730 That is, JSON::XS is about five times faster than JSON::DWIW on
606 encoding, about three times faster on decoding, and over fourty times 731 encoding, about three times faster on decoding, and over fourty times
607 faster than JSON, even with pretty-printing and key sorting. It also 732 faster than JSON, even with pretty-printing and key sorting. It also
… …
610 Using a longer test string (roughly 18KB, generated from Yahoo! Locals 735 Using a longer test string (roughly 18KB, generated from Yahoo! Locals
611 search API (http://nanoref.com/yahooapis/mgPdGg): 736 search API (http://nanoref.com/yahooapis/mgPdGg):
612 737
613 module | encode | decode | 738 module | encode | decode |
614 -----------|------------|------------| 739 -----------|------------|------------|
615 JSON | 254.685 | 37.665 | 740 JSON | 55.260 | 34.971 |
616 JSON::DWIW | 843.343 | 1049.731 | 741 JSON::DWIW | 825.228 | 1082.513 |
617 JSON::PC | 3602.116 | 2307.352 | 742 JSON::PC | 3571.444 | 2394.829 |
743 JSON::PP | 210.987 | 32.574 |
618 JSON::Syck | 505.107 | 787.899 | 744 JSON::Syck | 552.551 | 787.544 |
619 JSON::XS | 5747.196 | 3690.220 | 745 JSON::XS | 5780.463 | 4854.519 |
620 JSON::XS/2 | 3968.121 | 3676.634 | 746 JSON::XS/2 | 3869.998 | 4798.975 |
621 JSON::XS/3 | 6105.246 | 3662.508 | 747 JSON::XS/3 | 5862.880 | 4798.975 |
622 Storable | 4417.337 | 5285.161 | 748 Storable | 4445.002 | 5235.027 |
623 -----------+------------+------------+ 749 -----------+------------+------------+
624 750
625 Again, JSON::XS leads by far (except for Storable which non-surprisingly 751 Again, JSON::XS leads by far (except for Storable which non-surprisingly
626 decodes faster). 752 decodes faster).
627 753
… …
642 Second, you need to avoid resource-starving attacks. That means you 768 Second, you need to avoid resource-starving attacks. That means you
643 should limit the size of JSON texts you accept, or make sure then when 769 should limit the size of JSON texts you accept, or make sure then when
644 your resources run out, thats just fine (e.g. by using a separate 770 your resources run out, thats just fine (e.g. by using a separate
645 process that can crash safely). The size of a JSON text in octets or 771 process that can crash safely). The size of a JSON text in octets or
646 characters is usually a good indication of the size of the resources 772 characters is usually a good indication of the size of the resources
647 required to decode it into a Perl structure. 773 required to decode it into a Perl structure. While JSON::XS can check
774 the size of the JSON text, it might be too late when you already have it
775 in memory, so you might want to check the size before you accept the
776 string.
648 777
649 Third, JSON::XS recurses using the C stack when decoding objects and 778 Third, JSON::XS recurses using the C stack when decoding objects and
650 arrays. The C stack is a limited resource: for instance, on my amd64 779 arrays. The C stack is a limited resource: for instance, on my amd64
651 machine with 8MB of stack size I can decode around 180k nested arrays 780 machine with 8MB of stack size I can decode around 180k nested arrays
652 but only 14k nested JSON objects (due to perl itself recursing deeply on 781 but only 14k nested JSON objects (due to perl itself recursing deeply on

Diff Legend

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