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.48 by root, Mon Jun 25 22:11:39 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 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
… …
351given character in a string. 393given character in a string.
352 394
353Setting the maximum depth to one disallows any nesting, so that ensures 395Setting the maximum depth to one disallows any nesting, so that ensures
354that the object is only a single hash/object or array. 396that the object is only a single hash/object or array.
355 397
356The argument to C<max_depth> will be rounded up to the next nearest power 398The argument to C<max_depth> will be rounded up to the next highest power
357of two. 399of two. If no argument is given, the highest possible setting will be
400used, which is rarely useful.
401
402See SECURITY CONSIDERATIONS, below, for more info on why this is useful.
403
404=item $json = $json->max_size ([$maximum_string_size])
405
406Set the maximum length a JSON text may have (in bytes) where decoding is
407being attempted. The default is C<0>, meaning no limit. When C<decode>
408is called on a string longer then this number of characters it will not
409attempt to decode the string but throw an exception. This setting has no
410effect on C<encode> (yet).
411
412The argument to C<max_size> will be rounded up to the next B<highest>
413power of two (so may be more than requested). If no argument is given, the
414limit check will be deactivated (same as when C<0> is specified).
358 415
359See SECURITY CONSIDERATIONS, below, for more info on why this is useful. 416See SECURITY CONSIDERATIONS, below, for more info on why this is useful.
360 417
361=item $json_text = $json->encode ($perl_scalar) 418=item $json_text = $json->encode ($perl_scalar)
362 419
… …
432conversion details, but an integer may take slightly less memory and might 489conversion details, but an integer may take slightly less memory and might
433represent more values exactly than (floating point) numbers. 490represent more values exactly than (floating point) numbers.
434 491
435=item true, false 492=item true, false
436 493
437These JSON atoms become C<0>, C<1>, respectively. Information is lost in 494These JSON atoms become C<JSON::XS::true> and C<JSON::XS::false>,
438this process. Future versions might represent those values differently, 495respectively. They are overloaded to act almost exactly like the numbers
439but they will be guarenteed to act like these integers would normally in 496C<1> and C<0>. You can check wether a scalar is a JSON boolean by using
440Perl. 497the C<JSON::XS::is_bool> function.
441 498
442=item null 499=item null
443 500
444A JSON null atom becomes C<undef> in Perl. 501A JSON null atom becomes C<undef> in Perl.
445 502
… …
477C<1>, which get turned into C<false> and C<true> atoms in JSON. You can 534C<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. 535also use C<JSON::XS::false> and C<JSON::XS::true> to improve readability.
479 536
480 to_json [\0,JSON::XS::true] # yields [false,true] 537 to_json [\0,JSON::XS::true] # yields [false,true]
481 538
539=item JSON::XS::true, JSON::XS::false
540
541These special values become JSON true and JSON false values,
542respectively. You cna alos use C<\1> and C<\0> directly if you want.
543
482=item blessed objects 544=item blessed objects
483 545
484Blessed objects are not allowed. JSON::XS currently tries to encode their 546Blessed objects are not allowed. JSON::XS currently tries to encode their
485underlying representation (hash- or arrayref), but this behaviour might 547underlying representation (hash- or arrayref), but this behaviour might
486change in future versions. 548change in future versions.
… …
649It shows the number of encodes/decodes per second (JSON::XS uses 711It shows the number of encodes/decodes per second (JSON::XS uses
650the functional interface, while JSON::XS/2 uses the OO interface 712the functional interface, while JSON::XS/2 uses the OO interface
651with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables 713with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables
652shrink). Higher is better: 714shrink). Higher is better:
653 715
716 Storable | 15779.925 | 14169.946 |
717 -----------+------------+------------+
654 module | encode | decode | 718 module | encode | decode |
655 -----------|------------|------------| 719 -----------|------------|------------|
656 JSON | 7645.468 | 4208.613 | 720 JSON | 4990.842 | 4088.813 |
657 JSON::DWIW | 40721.398 | 77101.176 | 721 JSON::DWIW | 51653.990 | 71575.154 |
658 JSON::PC | 65948.176 | 78251.940 | 722 JSON::PC | 65948.176 | 74631.744 |
659 JSON::Syck | 22844.793 | 26479.192 | 723 JSON::PP | 8931.652 | 3817.168 |
724 JSON::Syck | 24877.248 | 27776.848 |
660 JSON::XS | 388361.481 | 199728.762 | 725 JSON::XS | 388361.481 | 227951.304 |
661 JSON::XS/2 | 218453.333 | 192399.266 | 726 JSON::XS/2 | 227951.304 | 218453.333 |
662 JSON::XS/3 | 338250.323 | 192399.266 | 727 JSON::XS/3 | 338250.323 | 218453.333 |
663 Storable | 15779.925 | 14169.946 | 728 Storable | 16500.016 | 135300.129 |
664 -----------+------------+------------+ 729 -----------+------------+------------+
665 730
666That is, JSON::XS is about five times faster than JSON::DWIW on encoding, 731That is, JSON::XS is about five times faster than JSON::DWIW on encoding,
667about three times faster on decoding, and over fourty times faster 732about three times faster on decoding, and over fourty times faster
668than JSON, even with pretty-printing and key sorting. It also compares 733than JSON, even with pretty-printing and key sorting. It also compares
… …
671Using a longer test string (roughly 18KB, generated from Yahoo! Locals 736Using a longer test string (roughly 18KB, generated from Yahoo! Locals
672search API (http://nanoref.com/yahooapis/mgPdGg): 737search API (http://nanoref.com/yahooapis/mgPdGg):
673 738
674 module | encode | decode | 739 module | encode | decode |
675 -----------|------------|------------| 740 -----------|------------|------------|
676 JSON | 254.685 | 37.665 | 741 JSON | 55.260 | 34.971 |
677 JSON::DWIW | 843.343 | 1049.731 | 742 JSON::DWIW | 825.228 | 1082.513 |
678 JSON::PC | 3602.116 | 2307.352 | 743 JSON::PC | 3571.444 | 2394.829 |
744 JSON::PP | 210.987 | 32.574 |
679 JSON::Syck | 505.107 | 787.899 | 745 JSON::Syck | 552.551 | 787.544 |
680 JSON::XS | 5747.196 | 3690.220 | 746 JSON::XS | 5780.463 | 4854.519 |
681 JSON::XS/2 | 3968.121 | 3676.634 | 747 JSON::XS/2 | 3869.998 | 4798.975 |
682 JSON::XS/3 | 6105.246 | 3662.508 | 748 JSON::XS/3 | 5862.880 | 4798.975 |
683 Storable | 4417.337 | 5285.161 | 749 Storable | 4445.002 | 5235.027 |
684 -----------+------------+------------+ 750 -----------+------------+------------+
685 751
686Again, JSON::XS leads by far (except for Storable which non-surprisingly 752Again, JSON::XS leads by far (except for Storable which non-surprisingly
687decodes faster). 753decodes faster).
688 754
… …
705Second, you need to avoid resource-starving attacks. That means you should 771Second, you need to avoid resource-starving attacks. That means you should
706limit the size of JSON texts you accept, or make sure then when your 772limit the size of JSON texts you accept, or make sure then when your
707resources run out, thats just fine (e.g. by using a separate process that 773resources run out, thats just fine (e.g. by using a separate process that
708can crash safely). The size of a JSON text in octets or characters is 774can crash safely). The size of a JSON text in octets or characters is
709usually a good indication of the size of the resources required to decode 775usually a good indication of the size of the resources required to decode
710it into a Perl structure. 776it into a Perl structure. While JSON::XS can check the size of the JSON
777text, it might be too late when you already have it in memory, so you
778might want to check the size before you accept the string.
711 779
712Third, JSON::XS recurses using the C stack when decoding objects and 780Third, JSON::XS recurses using the C stack when decoding objects and
713arrays. The C stack is a limited resource: for instance, on my amd64 781arrays. The C stack is a limited resource: for instance, on my amd64
714machine with 8MB of stack size I can decode around 180k nested arrays but 782machine with 8MB of stack size I can decode around 180k nested arrays but
715only 14k nested JSON objects (due to perl itself recursing deeply on croak 783only 14k nested JSON objects (due to perl itself recursing deeply on croak
… …
720 788
721And last but least, something else could bomb you that I forgot to think 789And 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, 790of. In that case, you get to keep the pieces. I am always open for hints,
723though... 791though...
724 792
793If you are using JSON::XS to return packets to consumption
794by javascript scripts in a browser you should have a look at
795L<http://jpsykes.com/47/practical-csrf-and-json-security> to see wether
796you are vulnerable to some common attack vectors (which really are browser
797design bugs, but it is still you who will have to deal with it, as major
798browser developers care only for features, not about doing security
799right).
800
725 801
726=head1 BUGS 802=head1 BUGS
727 803
728While the goal of this module is to be correct, that unfortunately does 804While 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 805not 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 806still relatively early in its development. If you keep reporting bugs they
731will be fixed swiftly, though. 807will be fixed swiftly, though.
732 808
733=cut 809=cut
734 810
811our $true = do { bless \(my $dummy = 1), "JSON::XS::Boolean" };
812our $false = do { bless \(my $dummy = 0), "JSON::XS::Boolean" };
813
735sub true() { \1 } 814sub true() { $true }
736sub false() { \0 } 815sub false() { $false }
816
817sub is_bool($) {
818 UNIVERSAL::isa $_[0], "JSON::XS::Boolean"
819# or UNIVERSAL::isa $_[0], "JSON::Literal"
820}
821
822XSLoader::load "JSON::XS", $VERSION;
823
824package JSON::XS::Boolean;
825
826use overload
827 "0+" => sub { ${$_[0]} },
828 "++" => sub { $_[0] = ${$_[0]} + 1 },
829 "--" => sub { $_[0] = ${$_[0]} - 1 },
830 fallback => 1;
737 831
7381; 8321;
739 833
740=head1 AUTHOR 834=head1 AUTHOR
741 835

Diff Legend

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