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.39 by root, Mon Jun 11 02:58:10 2007 UTC vs.
Revision 1.46 by root, Mon Jun 25 04:21:14 2007 UTC

… …
85 85
86package JSON::XS; 86package JSON::XS;
87 87
88use strict; 88use strict;
89 89
90BEGIN {
91 our $VERSION = '1.23'; 90our $VERSION = '1.4';
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
… …
309Example, encode a Perl scalar as JSON value with enabled C<allow_nonref>, 315Example, encode a Perl scalar as JSON value with enabled C<allow_nonref>,
310resulting in an invalid JSON text: 316resulting in an invalid JSON text:
311 317
312 JSON::XS->new->allow_nonref->encode ("Hello, World!") 318 JSON::XS->new->allow_nonref->encode ("Hello, World!")
313 => "Hello, World!" 319 => "Hello, World!"
320
321=item $json = $json->allow_blessed ([$enable])
322
323If C<$enable> is true (or missing), then the C<encode> method will not
324barf when it encounters a blessed reference. Instead, the value of the
325B<convert_blessed> option will decide wether C<null> (C<convert_blessed>
326disabled or no C<to_json> method found) or a representation of the
327object (C<convert_blessed> enabled and C<to_json> method found) is being
328encoded. Has no effect on C<decode>.
329
330If C<$enable> is false (the default), then C<encode> will throw an
331exception when it encounters a blessed object.
332
333=item $json = $json->convert_blessed ([$enable])
334
335If C<$enable> is true (or missing), then C<encode>, upon encountering a
336blessed object, will check for the availability of the C<TO_JSON> method
337on the object's class. If found, it will be called in scalar context
338and the resulting scalar will be encoded instead of the object. If no
339C<TO_JSON> method is found, the value of C<allow_blessed> will decide what
340to do.
341
342The C<TO_JSON> method may safely call die if it wants. If C<TO_JSON>
343returns other blessed objects, those will be handled in the same
344way. C<TO_JSON> must take care of not causing an endless recursion cycle
345(== crash) in this case. The name of C<TO_JSON> was chosen because other
346methods called by the Perl core (== not by the user of the object) are
347usually in upper case letters and to avoid collisions with the C<to_json>
348function.
349
350This setting does not yet influence C<decode> in any way, but in the
351future, global hooks might get installed that influence C<decode> and are
352enabled by this setting.
353
354If C<$enable> is false, then the C<allow_blessed> setting will decide what
355to do when a blessed object is found.
314 356
315=item $json = $json->shrink ([$enable]) 357=item $json = $json->shrink ([$enable])
316 358
317Perl usually over-allocates memory a bit when allocating space for 359Perl usually over-allocates memory a bit when allocating space for
318strings. This flag optionally resizes strings generated by either 360strings. This flag optionally resizes strings generated by either
… …
432conversion details, but an integer may take slightly less memory and might 474conversion details, but an integer may take slightly less memory and might
433represent more values exactly than (floating point) numbers. 475represent more values exactly than (floating point) numbers.
434 476
435=item true, false 477=item true, false
436 478
437These JSON atoms become C<0>, C<1>, respectively. Information is lost in 479These JSON atoms become C<JSON::XS::true> and C<JSON::XS::false>,
438this process. Future versions might represent those values differently, 480respectively. They are overloaded to act almost exactly like the numbers
439but they will be guarenteed to act like these integers would normally in 481C<1> and C<0>. You can check wether a scalar is a JSON boolean by using
440Perl. 482the C<JSON::XS::is_bool> function.
441 483
442=item null 484=item null
443 485
444A JSON null atom becomes C<undef> in Perl. 486A JSON null atom becomes C<undef> in Perl.
445 487
… …
477C<1>, which get turned into C<false> and C<true> atoms in JSON. You can 519C<1>, which get turned into C<false> and C<true> atoms in JSON. You can
478also use C<JSON::XS::false> and C<JSON::XS::true> to improve readability. 520also use C<JSON::XS::false> and C<JSON::XS::true> to improve readability.
479 521
480 to_json [\0,JSON::XS::true] # yields [false,true] 522 to_json [\0,JSON::XS::true] # yields [false,true]
481 523
524=item JSON::XS::true, JSON::XS::false
525
526These special values become JSON true and JSON false values,
527respectively. You cna alos use C<\1> and C<\0> directly if you want.
528
482=item blessed objects 529=item blessed objects
483 530
484Blessed objects are not allowed. JSON::XS currently tries to encode their 531Blessed objects are not allowed. JSON::XS currently tries to encode their
485underlying representation (hash- or arrayref), but this behaviour might 532underlying representation (hash- or arrayref), but this behaviour might
486change in future versions. 533change in future versions.
… …
614 661
615You often hear that JSON is a subset (or a close subset) of YAML. This is, 662You 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 663however, 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. 664no way to configure JSON::XS to output a data structure as valid YAML.
618 665
619If you really must use JSON::XS to generate YAML, you should this 666If you really must use JSON::XS to generate YAML, you should use this
620algorithm (subject to change in future versions): 667algorithm (subject to change in future versions):
621 668
622 my $to_yaml = JSON::XS->new->utf8->space_after (1); 669 my $to_yaml = JSON::XS->new->utf8->space_after (1);
623 my $yaml = $to_yaml->encode ($ref) . "\n"; 670 my $yaml = $to_yaml->encode ($ref) . "\n";
624 671
625This will usually generate JSON texts that also parse as valid 672This will usually generate JSON texts that also parse as valid
626YAML. Please note that YAML has hardcoded limits on object key lengths 673YAML. Please note that YAML has hardcoded limits on (simple) object key
627that JSON doesn't have, so you should make sure that your hash keys are 674lengths that JSON doesn't have, so you should make sure that your hash
628noticably shorter than 1024 characters. 675keys are noticably shorter than the 1024 characters YAML allows.
629 676
630There might be other incompatibilities that I am not aware of. In general 677There 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, 678you 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. 679or try to parse JSON with a YAML parser or vice versa: chances are high
680that you will run into severe interoperability problems.
633 681
634 682
635=head2 SPEED 683=head2 SPEED
636 684
637It seems that JSON::XS is surprisingly fast, as shown in the following 685It seems that JSON::XS is surprisingly fast, as shown in the following
… …
651shrink). Higher is better: 699shrink). Higher is better:
652 700
653 module | encode | decode | 701 module | encode | decode |
654 -----------|------------|------------| 702 -----------|------------|------------|
655 JSON | 7645.468 | 4208.613 | 703 JSON | 7645.468 | 4208.613 |
656 JSON::DWIW | 68534.379 | 79437.576 | 704 JSON::DWIW | 40721.398 | 77101.176 |
657 JSON::PC | 65948.176 | 78251.940 | 705 JSON::PC | 65948.176 | 78251.940 |
658 JSON::Syck | 23379.621 | 28416.694 | 706 JSON::Syck | 22844.793 | 26479.192 |
659 JSON::XS | 388361.481 | 199728.762 | 707 JSON::XS | 388361.481 | 199728.762 |
660 JSON::XS/2 | 218453.333 | 192399.266 | 708 JSON::XS/2 | 218453.333 | 192399.266 |
661 JSON::XS/3 | 338250.323 | 192399.266 | 709 JSON::XS/3 | 338250.323 | 192399.266 |
662 Storable | 15732.573 | 28571.553 | 710 Storable | 15779.925 | 14169.946 |
663 -----------+------------+------------+ 711 -----------+------------+------------+
664 712
665That is, JSON::XS is about five times faster than JSON::DWIW on encoding, 713That is, JSON::XS is about five times faster than JSON::DWIW on encoding,
666about three times faster on decoding, and over fourty times faster 714about three times faster on decoding, and over fourty times faster
667than JSON, even with pretty-printing and key sorting. It also compares 715than JSON, even with pretty-printing and key sorting. It also compares
… …
671search API (http://nanoref.com/yahooapis/mgPdGg): 719search API (http://nanoref.com/yahooapis/mgPdGg):
672 720
673 module | encode | decode | 721 module | encode | decode |
674 -----------|------------|------------| 722 -----------|------------|------------|
675 JSON | 254.685 | 37.665 | 723 JSON | 254.685 | 37.665 |
676 JSON::DWIW | 1014.244 | 1087.678 | 724 JSON::DWIW | 843.343 | 1049.731 |
677 JSON::PC | 3602.116 | 2307.352 | 725 JSON::PC | 3602.116 | 2307.352 |
678 JSON::Syck | 558.035 | 776.263 | 726 JSON::Syck | 505.107 | 787.899 |
679 JSON::XS | 5747.196 | 3543.684 | 727 JSON::XS | 5747.196 | 3690.220 |
680 JSON::XS/2 | 3968.121 | 3589.170 | 728 JSON::XS/2 | 3968.121 | 3676.634 |
681 JSON::XS/3 | 6105.246 | 3561.134 | 729 JSON::XS/3 | 6105.246 | 3662.508 |
682 Storable | 4456.337 | 5320.020 | 730 Storable | 4417.337 | 5285.161 |
683 -----------+------------+------------+ 731 -----------+------------+------------+
684 732
685Again, JSON::XS leads by far. 733Again, JSON::XS leads by far (except for Storable which non-surprisingly
734decodes faster).
686 735
687On large strings containing lots of high unicode characters, some modules 736On large strings containing lots of high unicode characters, some modules
688(such as JSON::PC) seem to decode faster than JSON::XS, but the result 737(such as JSON::PC) seem to decode faster than JSON::XS, but the result
689will be broken due to missing (or wrong) unicode handling. Others refuse 738will be broken due to missing (or wrong) unicode handling. Others refuse
690to decode or encode properly, so it was impossible to prepare a fair 739to decode or encode properly, so it was impossible to prepare a fair
… …
718 767
719And last but least, something else could bomb you that I forgot to think 768And last but least, something else could bomb you that I forgot to think
720of. In that case, you get to keep the pieces. I am always open for hints, 769of. In that case, you get to keep the pieces. I am always open for hints,
721though... 770though...
722 771
772If you are using JSON::XS to return packets to consumption
773by javascript scripts in a browser you should have a look at
774L<http://jpsykes.com/47/practical-csrf-and-json-security> to see wether
775you are vulnerable to some common attack vectors (which really are browser
776design bugs, but it is still you who will have to deal with it, as major
777browser developers care only for features, not about doing security
778right).
779
723 780
724=head1 BUGS 781=head1 BUGS
725 782
726While the goal of this module is to be correct, that unfortunately does 783While the goal of this module is to be correct, that unfortunately does
727not mean its bug-free, only that I think its design is bug-free. It is 784not mean its bug-free, only that I think its design is bug-free. It is
728still relatively early in its development. If you keep reporting bugs they 785still relatively early in its development. If you keep reporting bugs they
729will be fixed swiftly, though. 786will be fixed swiftly, though.
730 787
731=cut 788=cut
732 789
790our $true = do { bless \(my $dummy = 1), "JSON::XS::Boolean" };
791our $false = do { bless \(my $dummy = 0), "JSON::XS::Boolean" };
792
733sub true() { \1 } 793sub true() { $true }
734sub false() { \0 } 794sub false() { $false }
795
796sub is_bool($) {
797 UNIVERSAL::isa $_[0], "JSON::XS::Boolean"
798# or UNIVERSAL::isa $_[0], "JSON::Literal"
799}
800
801XSLoader::load "JSON::XS", $VERSION;
802
803package JSON::XS::Boolean;
804
805use overload
806 "0+" => sub { ${$_[0]} },
807 "++" => sub { $_[0] = ${$_[0]} + 1 },
808 "--" => sub { $_[0] = ${$_[0]} - 1 },
809 fallback => 1;
735 810
7361; 8111;
737 812
738=head1 AUTHOR 813=head1 AUTHOR
739 814

Diff Legend

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