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

Comparing JSON-XS/README (file contents):
Revision 1.11 by root, Wed May 9 16:35:21 2007 UTC vs.
Revision 1.14 by root, Sat Jun 23 23:50:03 2007 UTC

… …
91 This function call is functionally identical to: 91 This function call is functionally identical to:
92 92
93 $perl_scalar = JSON::XS->new->utf8->decode ($json_text) 93 $perl_scalar = JSON::XS->new->utf8->decode ($json_text)
94 94
95 except being faster. 95 except being faster.
96
97 $is_boolean = JSON::XS::is_bool $scalar
98 Returns true if the passed scalar represents either JSON::XS::true
99 or JSON::XS::false, two constants that act like 1 and 0,
100 respectively and are used to represent JSON "true" and "false"
101 values in Perl.
102
103 See MAPPING, below, for more information on how JSON values are
104 mapped to Perl.
96 105
97OBJECT-ORIENTED INTERFACE 106OBJECT-ORIENTED INTERFACE
98 The object oriented interface lets you configure your own encoding or 107 The object oriented interface lets you configure your own encoding or
99 decoding style, within the limits of supported formats. 108 decoding style, within the limits of supported formats.
100 109
… …
379 all the conversion details, but an integer may take slightly less 388 all the conversion details, but an integer may take slightly less
380 memory and might represent more values exactly than (floating point) 389 memory and might represent more values exactly than (floating point)
381 numbers. 390 numbers.
382 391
383 true, false 392 true, false
384 These JSON atoms become 0, 1, respectively. Information is lost in 393 These JSON atoms become "JSON::XS::true" and "JSON::XS::false",
385 this process. Future versions might represent those values 394 respectively. They are overloaded to act almost exactly like the
386 differently, but they will be guarenteed to act like these integers 395 numbers 1 and 0. You can check wether a scalar is a JSON boolean by
387 would normally in Perl. 396 using the "JSON::XS::is_bool" function.
388 397
389 null 398 null
390 A JSON null atom becomes "undef" in Perl. 399 A JSON null atom becomes "undef" in Perl.
391 400
392 PERL -> JSON 401 PERL -> JSON
… …
416 can also use "JSON::XS::false" and "JSON::XS::true" to improve 425 can also use "JSON::XS::false" and "JSON::XS::true" to improve
417 readability. 426 readability.
418 427
419 to_json [\0,JSON::XS::true] # yields [false,true] 428 to_json [\0,JSON::XS::true] # yields [false,true]
420 429
430 JSON::XS::true, JSON::XS::false
431 These special values become JSON true and JSON false values,
432 respectively. You cna alos use "\1" and "\0" directly if you want.
433
421 blessed objects 434 blessed objects
422 Blessed objects are not allowed. JSON::XS currently tries to encode 435 Blessed objects are not allowed. JSON::XS currently tries to encode
423 their underlying representation (hash- or arrayref), but this 436 their underlying representation (hash- or arrayref), but this
424 behaviour might change in future versions. 437 behaviour might change in future versions.
425 438
… …
535 Does not generate valid JSON texts (key strings are often unquoted, 548 Does not generate valid JSON texts (key strings are often unquoted,
536 empty keys result in nothing being output) 549 empty keys result in nothing being output)
537 550
538 Does not check input for validity. 551 Does not check input for validity.
539 552
553 JSON and YAML
554 You often hear that JSON is a subset (or a close subset) of YAML. This
555 is, however, a mass hysteria and very far from the truth. In general,
556 there is no way to configure JSON::XS to output a data structure as
557 valid YAML.
558
559 If you really must use JSON::XS to generate YAML, you should use this
560 algorithm (subject to change in future versions):
561
562 my $to_yaml = JSON::XS->new->utf8->space_after (1);
563 my $yaml = $to_yaml->encode ($ref) . "\n";
564
565 This will usually generate JSON texts that also parse as valid YAML.
566 Please note that YAML has hardcoded limits on (simple) object key
567 lengths that JSON doesn't have, so you should make sure that your hash
568 keys are noticably shorter than the 1024 characters YAML allows.
569
570 There might be other incompatibilities that I am not aware of. In
571 general you should not try to generate YAML with a JSON generator or
572 vice versa, or try to parse JSON with a YAML parser or vice versa:
573 chances are high that you will run into severe interoperability
574 problems.
575
540 SPEED 576 SPEED
541 It seems that JSON::XS is surprisingly fast, as shown in the following 577 It seems that JSON::XS is surprisingly fast, as shown in the following
542 tables. They have been generated with the help of the "eg/bench" program 578 tables. They have been generated with the help of the "eg/bench" program
543 in the JSON::XS distribution, to make it easy to compare on your own 579 in the JSON::XS distribution, to make it easy to compare on your own
544 system. 580 system.
545 581
546 First comes a comparison between various modules using a very short JSON 582 First comes a comparison between various modules using a very short
547 string: 583 single-line JSON string:
548 584
549 {"method": "handleMessage", "params": ["user1", "we were just talking"], "id": null} 585 {"method": "handleMessage", "params": ["user1", "we were just talking"], \
586 "id": null, "array":[1,11,234,-5,1e5,1e7, true, false]}
550 587
551 It shows the number of encodes/decodes per second (JSON::XS uses the 588 It shows the number of encodes/decodes per second (JSON::XS uses the
552 functional interface, while JSON::XS/2 uses the OO interface with 589 functional interface, while JSON::XS/2 uses the OO interface with
553 pretty-printing and hashkey sorting enabled). Higher is better: 590 pretty-printing and hashkey sorting enabled, JSON::XS/3 enables shrink).
591 Higher is better:
554 592
555 module | encode | decode | 593 module | encode | decode |
556 -----------|------------|------------| 594 -----------|------------|------------|
557 JSON | 11488.516 | 7823.035 | 595 JSON | 7645.468 | 4208.613 |
558 JSON::DWIW | 94708.054 | 129094.260 | 596 JSON::DWIW | 40721.398 | 77101.176 |
559 JSON::PC | 63884.157 | 128528.212 | 597 JSON::PC | 65948.176 | 78251.940 |
560 JSON::Syck | 34898.677 | 42096.911 | 598 JSON::Syck | 22844.793 | 26479.192 |
561 JSON::XS | 654027.064 | 396423.669 | 599 JSON::XS | 388361.481 | 199728.762 |
562 JSON::XS/2 | 371564.190 | 371725.613 | 600 JSON::XS/2 | 218453.333 | 192399.266 |
601 JSON::XS/3 | 338250.323 | 192399.266 |
602 Storable | 15779.925 | 14169.946 |
563 -----------+------------+------------+ 603 -----------+------------+------------+
564 604
565 That is, JSON::XS is more than six times faster than JSON::DWIW on 605 That is, JSON::XS is about five times faster than JSON::DWIW on
566 encoding, more than three times faster on decoding, and about thirty 606 encoding, about three times faster on decoding, and over fourty times
567 times faster than JSON, even with pretty-printing and key sorting. 607 faster than JSON, even with pretty-printing and key sorting. It also
608 compares favourably to Storable for small amounts of data.
568 609
569 Using a longer test string (roughly 18KB, generated from Yahoo! Locals 610 Using a longer test string (roughly 18KB, generated from Yahoo! Locals
570 search API (http://nanoref.com/yahooapis/mgPdGg): 611 search API (http://nanoref.com/yahooapis/mgPdGg):
571 612
572 module | encode | decode | 613 module | encode | decode |
573 -----------|------------|------------| 614 -----------|------------|------------|
574 JSON | 273.023 | 44.674 | 615 JSON | 254.685 | 37.665 |
575 JSON::DWIW | 1089.383 | 1145.704 | 616 JSON::DWIW | 843.343 | 1049.731 |
576 JSON::PC | 3097.419 | 2393.921 | 617 JSON::PC | 3602.116 | 2307.352 |
577 JSON::Syck | 514.060 | 843.053 | 618 JSON::Syck | 505.107 | 787.899 |
578 JSON::XS | 6479.668 | 3636.364 | 619 JSON::XS | 5747.196 | 3690.220 |
579 JSON::XS/2 | 3774.221 | 3599.124 | 620 JSON::XS/2 | 3968.121 | 3676.634 |
621 JSON::XS/3 | 6105.246 | 3662.508 |
622 Storable | 4417.337 | 5285.161 |
580 -----------+------------+------------+ 623 -----------+------------+------------+
581 624
582 Again, JSON::XS leads by far. 625 Again, JSON::XS leads by far (except for Storable which non-surprisingly
626 decodes faster).
583 627
584 On large strings containing lots of high unicode characters, some 628 On large strings containing lots of high unicode characters, some
585 modules (such as JSON::PC) seem to decode faster than JSON::XS, but the 629 modules (such as JSON::PC) seem to decode faster than JSON::XS, but the
586 result will be broken due to missing (or wrong) unicode handling. Others 630 result will be broken due to missing (or wrong) unicode handling. Others
587 refuse to decode or encode properly, so it was impossible to prepare a 631 refuse to decode or encode properly, so it was impossible to prepare a
… …
613 657
614 And last but least, something else could bomb you that I forgot to think 658 And last but least, something else could bomb you that I forgot to think
615 of. In that case, you get to keep the pieces. I am always open for 659 of. In that case, you get to keep the pieces. I am always open for
616 hints, though... 660 hints, though...
617 661
662 If you are using JSON::XS to return packets to consumption by javascript
663 scripts in a browser you should have a look at
664 <http://jpsykes.com/47/practical-csrf-and-json-security> to see wether
665 you are vulnerable to some common attack vectors (which really are
666 browser design bugs, but it is still you who will have to deal with it,
667 as major browser developers care only for features, not about doing
668 security right).
669
618BUGS 670BUGS
619 While the goal of this module is to be correct, that unfortunately does 671 While the goal of this module is to be correct, that unfortunately does
620 not mean its bug-free, only that I think its design is bug-free. It is 672 not mean its bug-free, only that I think its design is bug-free. It is
621 still relatively early in its development. If you keep reporting bugs 673 still relatively early in its development. If you keep reporting bugs
622 they will be fixed swiftly, though. 674 they will be fixed swiftly, though.

Diff Legend

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