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.41 by root, Mon Jun 11 03:45:26 2007 UTC vs.
Revision 1.44 by root, Mon Jun 25 04:08:17 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.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 the user of the object) are
347usually in upper case letters and to avoid collisions with the C<to_json>
348function.
349
350If C<$enable> is false, then the C<allow_blessed> setting will decide what
351to do when a blessed object is found.
314 352
315=item $json = $json->shrink ([$enable]) 353=item $json = $json->shrink ([$enable])
316 354
317Perl usually over-allocates memory a bit when allocating space for 355Perl usually over-allocates memory a bit when allocating space for
318strings. This flag optionally resizes strings generated by either 356strings. This flag optionally resizes strings generated by either
… …
432conversion details, but an integer may take slightly less memory and might 470conversion details, but an integer may take slightly less memory and might
433represent more values exactly than (floating point) numbers. 471represent more values exactly than (floating point) numbers.
434 472
435=item true, false 473=item true, false
436 474
437These JSON atoms become C<0>, C<1>, respectively. Information is lost in 475These JSON atoms become C<JSON::XS::true> and C<JSON::XS::false>,
438this process. Future versions might represent those values differently, 476respectively. They are overloaded to act almost exactly like the numbers
439but they will be guarenteed to act like these integers would normally in 477C<1> and C<0>. You can check wether a scalar is a JSON boolean by using
440Perl. 478the C<JSON::XS::is_bool> function.
441 479
442=item null 480=item null
443 481
444A JSON null atom becomes C<undef> in Perl. 482A JSON null atom becomes C<undef> in Perl.
445 483
… …
476exception to be thrown, except for references to the integers C<0> and 514exception to be thrown, except for references to the integers C<0> and
477C<1>, which get turned into C<false> and C<true> atoms in JSON. You can 515C<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. 516also use C<JSON::XS::false> and C<JSON::XS::true> to improve readability.
479 517
480 to_json [\0,JSON::XS::true] # yields [false,true] 518 to_json [\0,JSON::XS::true] # yields [false,true]
519
520=item JSON::XS::true, JSON::XS::false
521
522These special values become JSON true and JSON false values,
523respectively. You cna alos use C<\1> and C<\0> directly if you want.
481 524
482=item blessed objects 525=item blessed objects
483 526
484Blessed objects are not allowed. JSON::XS currently tries to encode their 527Blessed objects are not allowed. JSON::XS currently tries to encode their
485underlying representation (hash- or arrayref), but this behaviour might 528underlying representation (hash- or arrayref), but this behaviour might
… …
720 763
721And last but least, something else could bomb you that I forgot to think 764And last but least, something else could bomb you that I forgot to think
722of. In that case, you get to keep the pieces. I am always open for hints, 765of. In that case, you get to keep the pieces. I am always open for hints,
723though... 766though...
724 767
768If you are using JSON::XS to return packets to consumption
769by javascript scripts in a browser you should have a look at
770L<http://jpsykes.com/47/practical-csrf-and-json-security> to see wether
771you are vulnerable to some common attack vectors (which really are browser
772design bugs, but it is still you who will have to deal with it, as major
773browser developers care only for features, not about doing security
774right).
775
725 776
726=head1 BUGS 777=head1 BUGS
727 778
728While the goal of this module is to be correct, that unfortunately does 779While the goal of this module is to be correct, that unfortunately does
729not mean its bug-free, only that I think its design is bug-free. It is 780not mean its bug-free, only that I think its design is bug-free. It is
730still relatively early in its development. If you keep reporting bugs they 781still relatively early in its development. If you keep reporting bugs they
731will be fixed swiftly, though. 782will be fixed swiftly, though.
732 783
733=cut 784=cut
734 785
786our $true = do { bless \(my $dummy = 1), "JSON::XS::Boolean" };
787our $false = do { bless \(my $dummy = 0), "JSON::XS::Boolean" };
788
735sub true() { \1 } 789sub true() { $true }
736sub false() { \0 } 790sub false() { $false }
791
792sub is_bool($) {
793 UNIVERSAL::isa $_[0], "JSON::XS::Boolean"
794# or UNIVERSAL::isa $_[0], "JSON::Literal"
795}
796
797XSLoader::load "JSON::XS", $VERSION;
798
799package JSON::XS::Boolean;
800
801use overload
802 "0+" => sub { ${$_[0]} },
803 "++" => sub { $_[0] = ${$_[0]} + 1 },
804 "--" => sub { $_[0] = ${$_[0]} - 1 },
805 fallback => 1;
737 806
7381; 8071;
739 808
740=head1 AUTHOR 809=head1 AUTHOR
741 810

Diff Legend

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