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

Comparing JSON-XS/XS.pm (file contents):
Revision 1.36 by root, Wed May 23 22:07:43 2007 UTC vs.
Revision 1.42 by root, Thu Jun 14 23:58:57 2007 UTC

… …
86package JSON::XS; 86package JSON::XS;
87 87
88use strict; 88use strict;
89 89
90BEGIN { 90BEGIN {
91 our $VERSION = '1.22'; 91 our $VERSION = '1.24';
92 our @ISA = qw(Exporter); 92 our @ISA = qw(Exporter);
93 93
94 our @EXPORT = qw(to_json from_json objToJson jsonToObj); 94 our @EXPORT = qw(to_json from_json objToJson jsonToObj);
95 require Exporter; 95 require Exporter;
96 96
… …
402 402
403For the more enlightened: note that in the following descriptions, 403For the more enlightened: note that in the following descriptions,
404lowercase I<perl> refers to the Perl interpreter, while uppcercase I<Perl> 404lowercase I<perl> refers to the Perl interpreter, while uppcercase I<Perl>
405refers to the abstract Perl language itself. 405refers to the abstract Perl language itself.
406 406
407
407=head2 JSON -> PERL 408=head2 JSON -> PERL
408 409
409=over 4 410=over 4
410 411
411=item object 412=item object
… …
441=item null 442=item null
442 443
443A JSON null atom becomes C<undef> in Perl. 444A JSON null atom becomes C<undef> in Perl.
444 445
445=back 446=back
447
446 448
447=head2 PERL -> JSON 449=head2 PERL -> JSON
448 450
449The mapping from Perl to JSON is slightly more difficult, as Perl is a 451The mapping from Perl to JSON is slightly more difficult, as Perl is a
450truly typeless language, so we can only guess which JSON type is meant by 452truly typeless language, so we can only guess which JSON type is meant by
… …
605 607
606Does not check input for validity. 608Does not check input for validity.
607 609
608=back 610=back
609 611
612
613=head2 JSON and YAML
614
615You often hear that JSON is a subset (or a close subset) of YAML. This is,
616however, a mass hysteria and very far from the truth. In general, there is
617no way to configure JSON::XS to output a data structure as valid YAML.
618
619If you really must use JSON::XS to generate YAML, you should use this
620algorithm (subject to change in future versions):
621
622 my $to_yaml = JSON::XS->new->utf8->space_after (1);
623 my $yaml = $to_yaml->encode ($ref) . "\n";
624
625This will usually generate JSON texts that also parse as valid
626YAML. Please note that YAML has hardcoded limits on (simple) object key
627lengths that JSON doesn't have, so you should make sure that your hash
628keys are noticably shorter than the 1024 characters YAML allows.
629
630There might be other incompatibilities that I am not aware of. In general
631you should not try to generate YAML with a JSON generator or vice versa,
632or try to parse JSON with a YAML parser or vice versa: chances are high
633that you will run into severe interoperability problems.
634
635
610=head2 SPEED 636=head2 SPEED
611 637
612It seems that JSON::XS is surprisingly fast, as shown in the following 638It seems that JSON::XS is surprisingly fast, as shown in the following
613tables. They have been generated with the help of the C<eg/bench> program 639tables. They have been generated with the help of the C<eg/bench> program
614in the JSON::XS distribution, to make it easy to compare on your own 640in the JSON::XS distribution, to make it easy to compare on your own
615system. 641system.
616 642
617First comes a comparison between various modules using a very short JSON 643First comes a comparison between various modules using a very short
618string: 644single-line JSON string:
619 645
620 {"method": "handleMessage", "params": ["user1", "we were just talking"], "id": null} 646 {"method": "handleMessage", "params": ["user1", "we were just talking"], \
647 "id": null, "array":[1,11,234,-5,1e5,1e7, true, false]}
621 648
622It shows the number of encodes/decodes per second (JSON::XS uses the 649It shows the number of encodes/decodes per second (JSON::XS uses
623functional interface, while JSON::XS/2 uses the OO interface with 650the functional interface, while JSON::XS/2 uses the OO interface
624pretty-printing and hashkey sorting enabled). Higher is better: 651with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables
652shrink). Higher is better:
625 653
626 module | encode | decode | 654 module | encode | decode |
627 -----------|------------|------------| 655 -----------|------------|------------|
628 JSON | 11488.516 | 7823.035 | 656 JSON | 7645.468 | 4208.613 |
629 JSON::DWIW | 94708.054 | 129094.260 | 657 JSON::DWIW | 40721.398 | 77101.176 |
630 JSON::PC | 63884.157 | 128528.212 | 658 JSON::PC | 65948.176 | 78251.940 |
631 JSON::Syck | 34898.677 | 42096.911 | 659 JSON::Syck | 22844.793 | 26479.192 |
632 JSON::XS | 654027.064 | 396423.669 | 660 JSON::XS | 388361.481 | 199728.762 |
633 JSON::XS/2 | 371564.190 | 371725.613 | 661 JSON::XS/2 | 218453.333 | 192399.266 |
662 JSON::XS/3 | 338250.323 | 192399.266 |
663 Storable | 15779.925 | 14169.946 |
634 -----------+------------+------------+ 664 -----------+------------+------------+
635 665
636That is, JSON::XS is more than six times faster than JSON::DWIW on 666That is, JSON::XS is about five times faster than JSON::DWIW on encoding,
637encoding, more than three times faster on decoding, and about thirty times 667about three times faster on decoding, and over fourty times faster
638faster than JSON, even with pretty-printing and key sorting. 668than JSON, even with pretty-printing and key sorting. It also compares
669favourably to Storable for small amounts of data.
639 670
640Using a longer test string (roughly 18KB, generated from Yahoo! Locals 671Using a longer test string (roughly 18KB, generated from Yahoo! Locals
641search API (http://nanoref.com/yahooapis/mgPdGg): 672search API (http://nanoref.com/yahooapis/mgPdGg):
642 673
643 module | encode | decode | 674 module | encode | decode |
644 -----------|------------|------------| 675 -----------|------------|------------|
645 JSON | 273.023 | 44.674 | 676 JSON | 254.685 | 37.665 |
646 JSON::DWIW | 1089.383 | 1145.704 | 677 JSON::DWIW | 843.343 | 1049.731 |
647 JSON::PC | 3097.419 | 2393.921 | 678 JSON::PC | 3602.116 | 2307.352 |
648 JSON::Syck | 514.060 | 843.053 | 679 JSON::Syck | 505.107 | 787.899 |
649 JSON::XS | 6479.668 | 3636.364 | 680 JSON::XS | 5747.196 | 3690.220 |
650 JSON::XS/2 | 3774.221 | 3599.124 | 681 JSON::XS/2 | 3968.121 | 3676.634 |
682 JSON::XS/3 | 6105.246 | 3662.508 |
683 Storable | 4417.337 | 5285.161 |
651 -----------+------------+------------+ 684 -----------+------------+------------+
652 685
653Again, JSON::XS leads by far. 686Again, JSON::XS leads by far (except for Storable which non-surprisingly
687decodes faster).
654 688
655On large strings containing lots of high unicode characters, some modules 689On large strings containing lots of high unicode characters, some modules
656(such as JSON::PC) seem to decode faster than JSON::XS, but the result 690(such as JSON::PC) seem to decode faster than JSON::XS, but the result
657will be broken due to missing (or wrong) unicode handling. Others refuse 691will be broken due to missing (or wrong) unicode handling. Others refuse
658to decode or encode properly, so it was impossible to prepare a fair 692to decode or encode properly, so it was impossible to prepare a fair
… …
686 720
687And last but least, something else could bomb you that I forgot to think 721And last but least, something else could bomb you that I forgot to think
688of. In that case, you get to keep the pieces. I am always open for hints, 722of. In that case, you get to keep the pieces. I am always open for hints,
689though... 723though...
690 724
725If you are using JSON::XS to return packets to consumption
726by javascript scripts in a browser you should have a look at
727L<http://jpsykes.com/47/practical-csrf-and-json-security> to see wether
728you are vulnerable to some common attack vectors (which really are browser
729design bugs, but it is still you who will have to deal with it, as major
730browser developers care only for features, not about doing security
731right).
732
691 733
692=head1 BUGS 734=head1 BUGS
693 735
694While the goal of this module is to be correct, that unfortunately does 736While the goal of this module is to be correct, that unfortunately does
695not mean its bug-free, only that I think its design is bug-free. It is 737not mean its bug-free, only that I think its design is bug-free. It is

Diff Legend

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