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.16 by root, Thu Jul 26 11:33:35 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)
… …
380 A JSON string becomes a string scalar in Perl - Unicode codepoints 502 A JSON string becomes a string scalar in Perl - Unicode codepoints
381 in JSON are represented by the same codepoints in the Perl string, 503 in JSON are represented by the same codepoints in the Perl string,
382 so no manual decoding is necessary. 504 so no manual decoding is necessary.
383 505
384 number 506 number
385 A JSON number becomes either an integer or numeric (floating point) 507 A JSON number becomes either an integer, numeric (floating point) or
386 scalar in perl, depending on its range and any fractional parts. On 508 string scalar in perl, depending on its range and any fractional
387 the Perl level, there is no difference between those as Perl handles 509 parts. On the Perl level, there is no difference between those as
388 all the conversion details, but an integer may take slightly less 510 Perl handles all the conversion details, but an integer may take
389 memory and might represent more values exactly than (floating point) 511 slightly less memory and might represent more values exactly than
390 numbers. 512 (floating point) numbers.
513
514 If the number consists of digits only, JSON::XS will try to
515 represent it as an integer value. If that fails, it will try to
516 represent it as a numeric (floating point) value if that is possible
517 without loss of precision. Otherwise it will preserve the number as
518 a string value.
519
520 Numbers containing a fractional or exponential part will always be
521 represented as numeric (floating point) values, possibly at a loss
522 of precision.
523
524 This might create round-tripping problems as numbers might become
525 strings, but as Perl is typeless there is no other way to do it.
391 526
392 true, false 527 true, false
393 These JSON atoms become "JSON::XS::true" and "JSON::XS::false", 528 These JSON atoms become "JSON::XS::true" and "JSON::XS::false",
394 respectively. They are overloaded to act almost exactly like the 529 respectively. They are overloaded to act almost exactly like the
395 numbers 1 and 0. You can check wether a scalar is a JSON boolean by 530 numbers 1 and 0. You can check wether a scalar is a JSON boolean by
… …
588 It shows the number of encodes/decodes per second (JSON::XS uses the 723 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 724 functional interface, while JSON::XS/2 uses the OO interface with
590 pretty-printing and hashkey sorting enabled, JSON::XS/3 enables shrink). 725 pretty-printing and hashkey sorting enabled, JSON::XS/3 enables shrink).
591 Higher is better: 726 Higher is better:
592 727
728 Storable | 15779.925 | 14169.946 |
729 -----------+------------+------------+
593 module | encode | decode | 730 module | encode | decode |
594 -----------|------------|------------| 731 -----------|------------|------------|
595 JSON | 7645.468 | 4208.613 | 732 JSON | 4990.842 | 4088.813 |
596 JSON::DWIW | 40721.398 | 77101.176 | 733 JSON::DWIW | 51653.990 | 71575.154 |
597 JSON::PC | 65948.176 | 78251.940 | 734 JSON::PC | 65948.176 | 74631.744 |
598 JSON::Syck | 22844.793 | 26479.192 | 735 JSON::PP | 8931.652 | 3817.168 |
736 JSON::Syck | 24877.248 | 27776.848 |
599 JSON::XS | 388361.481 | 199728.762 | 737 JSON::XS | 388361.481 | 227951.304 |
600 JSON::XS/2 | 218453.333 | 192399.266 | 738 JSON::XS/2 | 227951.304 | 218453.333 |
601 JSON::XS/3 | 338250.323 | 192399.266 | 739 JSON::XS/3 | 338250.323 | 218453.333 |
602 Storable | 15779.925 | 14169.946 | 740 Storable | 16500.016 | 135300.129 |
603 -----------+------------+------------+ 741 -----------+------------+------------+
604 742
605 That is, JSON::XS is about five times faster than JSON::DWIW on 743 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 744 encoding, about three times faster on decoding, and over fourty times
607 faster than JSON, even with pretty-printing and key sorting. It also 745 faster than JSON, even with pretty-printing and key sorting. It also
… …
610 Using a longer test string (roughly 18KB, generated from Yahoo! Locals 748 Using a longer test string (roughly 18KB, generated from Yahoo! Locals
611 search API (http://nanoref.com/yahooapis/mgPdGg): 749 search API (http://nanoref.com/yahooapis/mgPdGg):
612 750
613 module | encode | decode | 751 module | encode | decode |
614 -----------|------------|------------| 752 -----------|------------|------------|
615 JSON | 254.685 | 37.665 | 753 JSON | 55.260 | 34.971 |
616 JSON::DWIW | 843.343 | 1049.731 | 754 JSON::DWIW | 825.228 | 1082.513 |
617 JSON::PC | 3602.116 | 2307.352 | 755 JSON::PC | 3571.444 | 2394.829 |
756 JSON::PP | 210.987 | 32.574 |
618 JSON::Syck | 505.107 | 787.899 | 757 JSON::Syck | 552.551 | 787.544 |
619 JSON::XS | 5747.196 | 3690.220 | 758 JSON::XS | 5780.463 | 4854.519 |
620 JSON::XS/2 | 3968.121 | 3676.634 | 759 JSON::XS/2 | 3869.998 | 4798.975 |
621 JSON::XS/3 | 6105.246 | 3662.508 | 760 JSON::XS/3 | 5862.880 | 4798.975 |
622 Storable | 4417.337 | 5285.161 | 761 Storable | 4445.002 | 5235.027 |
623 -----------+------------+------------+ 762 -----------+------------+------------+
624 763
625 Again, JSON::XS leads by far (except for Storable which non-surprisingly 764 Again, JSON::XS leads by far (except for Storable which non-surprisingly
626 decodes faster). 765 decodes faster).
627 766
… …
642 Second, you need to avoid resource-starving attacks. That means you 781 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 782 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 783 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 784 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 785 characters is usually a good indication of the size of the resources
647 required to decode it into a Perl structure. 786 required to decode it into a Perl structure. While JSON::XS can check
787 the size of the JSON text, it might be too late when you already have it
788 in memory, so you might want to check the size before you accept the
789 string.
648 790
649 Third, JSON::XS recurses using the C stack when decoding objects and 791 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 792 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 793 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 794 but only 14k nested JSON objects (due to perl itself recursing deeply on

Diff Legend

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