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.40 by root, Mon Jun 11 03:42:57 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.24'; 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
… …
432conversion details, but an integer may take slightly less memory and might 438conversion details, but an integer may take slightly less memory and might
433represent more values exactly than (floating point) numbers. 439represent more values exactly than (floating point) numbers.
434 440
435=item true, false 441=item true, false
436 442
437These 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>,
438this process. Future versions might represent those values differently, 444respectively. They are overloaded to act almost exactly like the numbers
439but 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
440Perl. 446the C<JSON::XS::is_bool> function.
441 447
442=item null 448=item null
443 449
444A JSON null atom becomes C<undef> in Perl. 450A JSON null atom becomes C<undef> in Perl.
445 451
… …
477C<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
478also 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.
479 485
480 to_json [\0,JSON::XS::true] # yields [false,true] 486 to_json [\0,JSON::XS::true] # yields [false,true]
481 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
482=item blessed objects 493=item blessed objects
483 494
484Blessed objects are not allowed. JSON::XS currently tries to encode their 495Blessed objects are not allowed. JSON::XS currently tries to encode their
485underlying representation (hash- or arrayref), but this behaviour might 496underlying representation (hash- or arrayref), but this behaviour might
486change in future versions. 497change in future versions.
… …
614 625
615You often hear that JSON is a subset (or a close subset) of YAML. This is, 626You 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 627however, 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. 628no way to configure JSON::XS to output a data structure as valid YAML.
618 629
619If you really must use JSON::XS to generate YAML, you should this 630If you really must use JSON::XS to generate YAML, you should use this
620algorithm (subject to change in future versions): 631algorithm (subject to change in future versions):
621 632
622 my $to_yaml = JSON::XS->new->utf8->space_after (1); 633 my $to_yaml = JSON::XS->new->utf8->space_after (1);
623 my $yaml = $to_yaml->encode ($ref) . "\n"; 634 my $yaml = $to_yaml->encode ($ref) . "\n";
624 635
625This will usually generate JSON texts that also parse as valid 636This will usually generate JSON texts that also parse as valid
626YAML. Please note that YAML has hardcoded limits on object key lengths 637YAML. 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 638lengths that JSON doesn't have, so you should make sure that your hash
628noticably shorter than 1024 characters. 639keys are noticably shorter than the 1024 characters YAML allows.
629 640
630There might be other incompatibilities that I am not aware of. In general 641There 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, 642you 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. 643or try to parse JSON with a YAML parser or vice versa: chances are high
644that you will run into severe interoperability problems.
633 645
634 646
635=head2 SPEED 647=head2 SPEED
636 648
637It 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
… …
719 731
720And 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
721of. 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,
722though... 734though...
723 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
724 744
725=head1 BUGS 745=head1 BUGS
726 746
727While 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
728not 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
729still relatively early in its development. If you keep reporting bugs they 749still relatively early in its development. If you keep reporting bugs they
730will be fixed swiftly, though. 750will be fixed swiftly, though.
731 751
732=cut 752=cut
733 753
754our $true = do { bless \(my $dummy = 1), "JSON::XS::Boolean" };
755our $false = do { bless \(my $dummy = 0), "JSON::XS::Boolean" };
756
734sub true() { \1 } 757sub true() { $true }
735sub 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;
736 774
7371; 7751;
738 776
739=head1 AUTHOR 777=head1 AUTHOR
740 778

Diff Legend

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