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.33 by root, Wed May 9 16:10:37 2007 UTC vs.
Revision 1.43 by root, Sat Jun 23 23:49:29 2007 UTC

… …
85 85
86package JSON::XS; 86package JSON::XS;
87 87
88use strict; 88use strict;
89 89
90BEGIN {
91 our $VERSION = '1.12'; 90our $VERSION = '1.3';
92 our @ISA = qw(Exporter); 91our @ISA = qw(Exporter);
93 92
94 our @EXPORT = qw(to_json from_json objToJson jsonToObj); 93our @EXPORT = qw(to_json from_json objToJson jsonToObj);
95 require Exporter;
96 94
97 require XSLoader; 95use Exporter;
98 XSLoader::load JSON::XS::, $VERSION; 96use XSLoader;
99}
100 97
101=head1 FUNCTIONAL INTERFACE 98=head1 FUNCTIONAL INTERFACE
102 99
103The following convinience methods are provided by this module. They are 100The following convinience methods are provided by this module. They are
104exported by default: 101exported by default:
… …
126This function call is functionally identical to: 123This function call is functionally identical to:
127 124
128 $perl_scalar = JSON::XS->new->utf8->decode ($json_text) 125 $perl_scalar = JSON::XS->new->utf8->decode ($json_text)
129 126
130except being faster. 127except being faster.
128
129=item $is_boolean = JSON::XS::is_bool $scalar
130
131Returns true if the passed scalar represents either JSON::XS::true or
132JSON::XS::false, two constants that act like C<1> and C<0>, respectively
133and are used to represent JSON C<true> and C<false> values in Perl.
134
135See MAPPING, below, for more information on how JSON values are mapped to
136Perl.
131 137
132=back 138=back
133 139
134 140
135=head1 OBJECT-ORIENTED INTERFACE 141=head1 OBJECT-ORIENTED INTERFACE
… …
374 380
375JSON numbers and strings become simple Perl scalars. JSON arrays become 381JSON numbers and strings become simple Perl scalars. JSON arrays become
376Perl arrayrefs and JSON objects become Perl hashrefs. C<true> becomes 382Perl arrayrefs and JSON objects become Perl hashrefs. C<true> becomes
377C<1>, C<false> becomes C<0> and C<null> becomes C<undef>. 383C<1>, C<false> becomes C<0> and C<null> becomes C<undef>.
378 384
385=item ($perl_scalar, $characters) = $json->decode_prefix ($json_text)
386
387This works like the C<decode> method, but instead of raising an exception
388when there is trailing garbage after the first JSON object, it will
389silently stop parsing there and return the number of characters consumed
390so far.
391
392This is useful if your JSON texts are not delimited by an outer protocol
393(which is not the brightest thing to do in the first place) and you need
394to know where the JSON text ends.
395
396 JSON::XS->new->decode_prefix ("[1] the tail")
397 => ([], 3)
398
379=back 399=back
380 400
381 401
382=head1 MAPPING 402=head1 MAPPING
383 403
… …
387(what you put in comes out as something equivalent). 407(what you put in comes out as something equivalent).
388 408
389For the more enlightened: note that in the following descriptions, 409For the more enlightened: note that in the following descriptions,
390lowercase I<perl> refers to the Perl interpreter, while uppcercase I<Perl> 410lowercase I<perl> refers to the Perl interpreter, while uppcercase I<Perl>
391refers to the abstract Perl language itself. 411refers to the abstract Perl language itself.
412
392 413
393=head2 JSON -> PERL 414=head2 JSON -> PERL
394 415
395=over 4 416=over 4
396 417
… …
417conversion details, but an integer may take slightly less memory and might 438conversion details, but an integer may take slightly less memory and might
418represent more values exactly than (floating point) numbers. 439represent more values exactly than (floating point) numbers.
419 440
420=item true, false 441=item true, false
421 442
422These JSON atoms become C<0>, C<1>, respectively. Information is lost in 443These JSON atoms become C<JSON::XS::true> and C<JSON::XS::false>,
423this process. Future versions might represent those values differently, 444respectively. They are overloaded to act almost exactly like the numbers
424but they will be guarenteed to act like these integers would normally in 445C<1> and C<0>. You can check wether a scalar is a JSON boolean by using
425Perl. 446the C<JSON::XS::is_bool> function.
426 447
427=item null 448=item null
428 449
429A JSON null atom becomes C<undef> in Perl. 450A JSON null atom becomes C<undef> in Perl.
430 451
431=back 452=back
453
432 454
433=head2 PERL -> JSON 455=head2 PERL -> JSON
434 456
435The mapping from Perl to JSON is slightly more difficult, as Perl is a 457The mapping from Perl to JSON is slightly more difficult, as Perl is a
436truly typeless language, so we can only guess which JSON type is meant by 458truly typeless language, so we can only guess which JSON type is meant by
… …
461C<1>, which get turned into C<false> and C<true> atoms in JSON. You can 483C<1>, which get turned into C<false> and C<true> atoms in JSON. You can
462also use C<JSON::XS::false> and C<JSON::XS::true> to improve readability. 484also use C<JSON::XS::false> and C<JSON::XS::true> to improve readability.
463 485
464 to_json [\0,JSON::XS::true] # yields [false,true] 486 to_json [\0,JSON::XS::true] # yields [false,true]
465 487
488=item JSON::XS::true, JSON::XS::false
489
490These special values become JSON true and JSON false values,
491respectively. You cna alos use C<\1> and C<\0> directly if you want.
492
466=item blessed objects 493=item blessed objects
467 494
468Blessed objects are not allowed. JSON::XS currently tries to encode their 495Blessed objects are not allowed. JSON::XS currently tries to encode their
469underlying representation (hash- or arrayref), but this behaviour might 496underlying representation (hash- or arrayref), but this behaviour might
470change in future versions. 497change in future versions.
… …
591 618
592Does not check input for validity. 619Does not check input for validity.
593 620
594=back 621=back
595 622
623
624=head2 JSON and YAML
625
626You often hear that JSON is a subset (or a close subset) of YAML. This is,
627however, a mass hysteria and very far from the truth. In general, there is
628no way to configure JSON::XS to output a data structure as valid YAML.
629
630If you really must use JSON::XS to generate YAML, you should use this
631algorithm (subject to change in future versions):
632
633 my $to_yaml = JSON::XS->new->utf8->space_after (1);
634 my $yaml = $to_yaml->encode ($ref) . "\n";
635
636This will usually generate JSON texts that also parse as valid
637YAML. Please note that YAML has hardcoded limits on (simple) object key
638lengths that JSON doesn't have, so you should make sure that your hash
639keys are noticably shorter than the 1024 characters YAML allows.
640
641There might be other incompatibilities that I am not aware of. In general
642you should not try to generate YAML with a JSON generator or vice versa,
643or try to parse JSON with a YAML parser or vice versa: chances are high
644that you will run into severe interoperability problems.
645
646
596=head2 SPEED 647=head2 SPEED
597 648
598It seems that JSON::XS is surprisingly fast, as shown in the following 649It seems that JSON::XS is surprisingly fast, as shown in the following
599tables. They have been generated with the help of the C<eg/bench> program 650tables. They have been generated with the help of the C<eg/bench> program
600in the JSON::XS distribution, to make it easy to compare on your own 651in the JSON::XS distribution, to make it easy to compare on your own
601system. 652system.
602 653
603First comes a comparison between various modules using a very short JSON 654First comes a comparison between various modules using a very short
604string: 655single-line JSON string:
605 656
606 {"method": "handleMessage", "params": ["user1", "we were just talking"], "id": null} 657 {"method": "handleMessage", "params": ["user1", "we were just talking"], \
658 "id": null, "array":[1,11,234,-5,1e5,1e7, true, false]}
607 659
608It shows the number of encodes/decodes per second (JSON::XS uses the 660It shows the number of encodes/decodes per second (JSON::XS uses
609functional interface, while JSON::XS/2 uses the OO interface with 661the functional interface, while JSON::XS/2 uses the OO interface
610pretty-printing and hashkey sorting enabled). Higher is better: 662with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables
663shrink). Higher is better:
611 664
612 module | encode | decode | 665 module | encode | decode |
613 -----------|------------|------------| 666 -----------|------------|------------|
614 JSON | 11488.516 | 7823.035 | 667 JSON | 7645.468 | 4208.613 |
615 JSON::DWIW | 94708.054 | 129094.260 | 668 JSON::DWIW | 40721.398 | 77101.176 |
616 JSON::PC | 63884.157 | 128528.212 | 669 JSON::PC | 65948.176 | 78251.940 |
617 JSON::Syck | 34898.677 | 42096.911 | 670 JSON::Syck | 22844.793 | 26479.192 |
618 JSON::XS | 654027.064 | 396423.669 | 671 JSON::XS | 388361.481 | 199728.762 |
619 JSON::XS/2 | 371564.190 | 371725.613 | 672 JSON::XS/2 | 218453.333 | 192399.266 |
673 JSON::XS/3 | 338250.323 | 192399.266 |
674 Storable | 15779.925 | 14169.946 |
620 -----------+------------+------------+ 675 -----------+------------+------------+
621 676
622That is, JSON::XS is more than six times faster than JSON::DWIW on 677That is, JSON::XS is about five times faster than JSON::DWIW on encoding,
623encoding, more than three times faster on decoding, and about thirty times 678about three times faster on decoding, and over fourty times faster
624faster than JSON, even with pretty-printing and key sorting. 679than JSON, even with pretty-printing and key sorting. It also compares
680favourably to Storable for small amounts of data.
625 681
626Using a longer test string (roughly 18KB, generated from Yahoo! Locals 682Using a longer test string (roughly 18KB, generated from Yahoo! Locals
627search API (http://nanoref.com/yahooapis/mgPdGg): 683search API (http://nanoref.com/yahooapis/mgPdGg):
628 684
629 module | encode | decode | 685 module | encode | decode |
630 -----------|------------|------------| 686 -----------|------------|------------|
631 JSON | 273.023 | 44.674 | 687 JSON | 254.685 | 37.665 |
632 JSON::DWIW | 1089.383 | 1145.704 | 688 JSON::DWIW | 843.343 | 1049.731 |
633 JSON::PC | 3097.419 | 2393.921 | 689 JSON::PC | 3602.116 | 2307.352 |
634 JSON::Syck | 514.060 | 843.053 | 690 JSON::Syck | 505.107 | 787.899 |
635 JSON::XS | 6479.668 | 3636.364 | 691 JSON::XS | 5747.196 | 3690.220 |
636 JSON::XS/2 | 3774.221 | 3599.124 | 692 JSON::XS/2 | 3968.121 | 3676.634 |
693 JSON::XS/3 | 6105.246 | 3662.508 |
694 Storable | 4417.337 | 5285.161 |
637 -----------+------------+------------+ 695 -----------+------------+------------+
638 696
639Again, JSON::XS leads by far. 697Again, JSON::XS leads by far (except for Storable which non-surprisingly
698decodes faster).
640 699
641On large strings containing lots of high unicode characters, some modules 700On large strings containing lots of high unicode characters, some modules
642(such as JSON::PC) seem to decode faster than JSON::XS, but the result 701(such as JSON::PC) seem to decode faster than JSON::XS, but the result
643will be broken due to missing (or wrong) unicode handling. Others refuse 702will be broken due to missing (or wrong) unicode handling. Others refuse
644to decode or encode properly, so it was impossible to prepare a fair 703to decode or encode properly, so it was impossible to prepare a fair
… …
672 731
673And last but least, something else could bomb you that I forgot to think 732And last but least, something else could bomb you that I forgot to think
674of. In that case, you get to keep the pieces. I am always open for hints, 733of. In that case, you get to keep the pieces. I am always open for hints,
675though... 734though...
676 735
736If you are using JSON::XS to return packets to consumption
737by javascript scripts in a browser you should have a look at
738L<http://jpsykes.com/47/practical-csrf-and-json-security> to see wether
739you are vulnerable to some common attack vectors (which really are browser
740design bugs, but it is still you who will have to deal with it, as major
741browser developers care only for features, not about doing security
742right).
743
677 744
678=head1 BUGS 745=head1 BUGS
679 746
680While the goal of this module is to be correct, that unfortunately does 747While the goal of this module is to be correct, that unfortunately does
681not mean its bug-free, only that I think its design is bug-free. It is 748not mean its bug-free, only that I think its design is bug-free. It is
682still relatively early in its development. If you keep reporting bugs they 749still relatively early in its development. If you keep reporting bugs they
683will be fixed swiftly, though. 750will be fixed swiftly, though.
684 751
685=cut 752=cut
686 753
754our $true = do { bless \(my $dummy = 1), "JSON::XS::Boolean" };
755our $false = do { bless \(my $dummy = 0), "JSON::XS::Boolean" };
756
687sub true() { \1 } 757sub true() { $true }
688sub false() { \0 } 758sub false() { $false }
759
760sub is_bool($) {
761 UNIVERSAL::isa $_[0], "JSON::XS::Boolean"
762 or UNIVERSAL::isa $_[0], "JSON::Literal"
763}
764
765XSLoader::load "JSON::XS", $VERSION;
766
767package JSON::XS::Boolean;
768
769use overload
770 "0+" => sub { ${$_[0]} },
771 "++" => sub { $_[0] = ${$_[0]} + 1 },
772 "--" => sub { $_[0] = ${$_[0]} - 1 },
773 fallback => 1;
689 774
6901; 7751;
691 776
692=head1 AUTHOR 777=head1 AUTHOR
693 778

Diff Legend

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