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.49 by root, Sun Jul 1 14:08:03 2007 UTC

… …
9 # exported functions, they croak on error 9 # exported functions, they croak on error
10 # and expect/generate UTF-8 10 # and expect/generate UTF-8
11 11
12 $utf8_encoded_json_text = to_json $perl_hash_or_arrayref; 12 $utf8_encoded_json_text = to_json $perl_hash_or_arrayref;
13 $perl_hash_or_arrayref = from_json $utf8_encoded_json_text; 13 $perl_hash_or_arrayref = from_json $utf8_encoded_json_text;
14
15 # objToJson and jsonToObj aliases to to_json and from_json
16 # are exported for compatibility to the JSON module,
17 # but should not be used in new code.
18 14
19 # OO-interface 15 # OO-interface
20 16
21 $coder = JSON::XS->new->ascii->pretty->allow_nonref; 17 $coder = JSON::XS->new->ascii->pretty->allow_nonref;
22 $pretty_printed_unencoded = $coder->encode ($perl_scalar); 18 $pretty_printed_unencoded = $coder->encode ($perl_scalar);
… …
85 81
86package JSON::XS; 82package JSON::XS;
87 83
88use strict; 84use strict;
89 85
90BEGIN {
91 our $VERSION = '1.24'; 86our $VERSION = '1.4';
92 our @ISA = qw(Exporter); 87our @ISA = qw(Exporter);
93 88
94 our @EXPORT = qw(to_json from_json objToJson jsonToObj); 89our @EXPORT = qw(to_json from_json);
95 require Exporter;
96 90
97 require XSLoader; 91use Exporter;
98 XSLoader::load JSON::XS::, $VERSION; 92use XSLoader;
99}
100 93
101=head1 FUNCTIONAL INTERFACE 94=head1 FUNCTIONAL INTERFACE
102 95
103The following convinience methods are provided by this module. They are 96The following convinience methods are provided by this module. They are
104exported by default: 97exported by default:
… …
126This function call is functionally identical to: 119This function call is functionally identical to:
127 120
128 $perl_scalar = JSON::XS->new->utf8->decode ($json_text) 121 $perl_scalar = JSON::XS->new->utf8->decode ($json_text)
129 122
130except being faster. 123except being faster.
124
125=item $is_boolean = JSON::XS::is_bool $scalar
126
127Returns true if the passed scalar represents either JSON::XS::true or
128JSON::XS::false, two constants that act like C<1> and C<0>, respectively
129and are used to represent JSON C<true> and C<false> values in Perl.
130
131See MAPPING, below, for more information on how JSON values are mapped to
132Perl.
131 133
132=back 134=back
133 135
134 136
135=head1 OBJECT-ORIENTED INTERFACE 137=head1 OBJECT-ORIENTED INTERFACE
… …
309Example, encode a Perl scalar as JSON value with enabled C<allow_nonref>, 311Example, encode a Perl scalar as JSON value with enabled C<allow_nonref>,
310resulting in an invalid JSON text: 312resulting in an invalid JSON text:
311 313
312 JSON::XS->new->allow_nonref->encode ("Hello, World!") 314 JSON::XS->new->allow_nonref->encode ("Hello, World!")
313 => "Hello, World!" 315 => "Hello, World!"
316
317=item $json = $json->allow_blessed ([$enable])
318
319If C<$enable> is true (or missing), then the C<encode> method will not
320barf when it encounters a blessed reference. Instead, the value of the
321B<convert_blessed> option will decide wether C<null> (C<convert_blessed>
322disabled or no C<to_json> method found) or a representation of the
323object (C<convert_blessed> enabled and C<to_json> method found) is being
324encoded. Has no effect on C<decode>.
325
326If C<$enable> is false (the default), then C<encode> will throw an
327exception when it encounters a blessed object.
328
329=item $json = $json->convert_blessed ([$enable])
330
331If C<$enable> is true (or missing), then C<encode>, upon encountering a
332blessed object, will check for the availability of the C<TO_JSON> method
333on the object's class. If found, it will be called in scalar context
334and the resulting scalar will be encoded instead of the object. If no
335C<TO_JSON> method is found, the value of C<allow_blessed> will decide what
336to do.
337
338The C<TO_JSON> method may safely call die if it wants. If C<TO_JSON>
339returns other blessed objects, those will be handled in the same
340way. C<TO_JSON> must take care of not causing an endless recursion cycle
341(== crash) in this case. The name of C<TO_JSON> was chosen because other
342methods called by the Perl core (== not by the user of the object) are
343usually in upper case letters and to avoid collisions with the C<to_json>
344function.
345
346This setting does not yet influence C<decode> in any way, but in the
347future, global hooks might get installed that influence C<decode> and are
348enabled by this setting.
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
… …
351given character in a string. 389given character in a string.
352 390
353Setting the maximum depth to one disallows any nesting, so that ensures 391Setting the maximum depth to one disallows any nesting, so that ensures
354that the object is only a single hash/object or array. 392that the object is only a single hash/object or array.
355 393
356The argument to C<max_depth> will be rounded up to the next nearest power 394The argument to C<max_depth> will be rounded up to the next highest power
357of two. 395of two. If no argument is given, the highest possible setting will be
396used, which is rarely useful.
397
398See SECURITY CONSIDERATIONS, below, for more info on why this is useful.
399
400=item $json = $json->max_size ([$maximum_string_size])
401
402Set the maximum length a JSON text may have (in bytes) where decoding is
403being attempted. The default is C<0>, meaning no limit. When C<decode>
404is called on a string longer then this number of characters it will not
405attempt to decode the string but throw an exception. This setting has no
406effect on C<encode> (yet).
407
408The argument to C<max_size> will be rounded up to the next B<highest>
409power of two (so may be more than requested). If no argument is given, the
410limit check will be deactivated (same as when C<0> is specified).
358 411
359See SECURITY CONSIDERATIONS, below, for more info on why this is useful. 412See SECURITY CONSIDERATIONS, below, for more info on why this is useful.
360 413
361=item $json_text = $json->encode ($perl_scalar) 414=item $json_text = $json->encode ($perl_scalar)
362 415
… …
432conversion details, but an integer may take slightly less memory and might 485conversion details, but an integer may take slightly less memory and might
433represent more values exactly than (floating point) numbers. 486represent more values exactly than (floating point) numbers.
434 487
435=item true, false 488=item true, false
436 489
437These JSON atoms become C<0>, C<1>, respectively. Information is lost in 490These JSON atoms become C<JSON::XS::true> and C<JSON::XS::false>,
438this process. Future versions might represent those values differently, 491respectively. They are overloaded to act almost exactly like the numbers
439but they will be guarenteed to act like these integers would normally in 492C<1> and C<0>. You can check wether a scalar is a JSON boolean by using
440Perl. 493the C<JSON::XS::is_bool> function.
441 494
442=item null 495=item null
443 496
444A JSON null atom becomes C<undef> in Perl. 497A JSON null atom becomes C<undef> in Perl.
445 498
… …
477C<1>, which get turned into C<false> and C<true> atoms in JSON. You can 530C<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. 531also use C<JSON::XS::false> and C<JSON::XS::true> to improve readability.
479 532
480 to_json [\0,JSON::XS::true] # yields [false,true] 533 to_json [\0,JSON::XS::true] # yields [false,true]
481 534
535=item JSON::XS::true, JSON::XS::false
536
537These special values become JSON true and JSON false values,
538respectively. You cna alos use C<\1> and C<\0> directly if you want.
539
482=item blessed objects 540=item blessed objects
483 541
484Blessed objects are not allowed. JSON::XS currently tries to encode their 542Blessed objects are not allowed. JSON::XS currently tries to encode their
485underlying representation (hash- or arrayref), but this behaviour might 543underlying representation (hash- or arrayref), but this behaviour might
486change in future versions. 544change in future versions.
… …
649It shows the number of encodes/decodes per second (JSON::XS uses 707It shows the number of encodes/decodes per second (JSON::XS uses
650the functional interface, while JSON::XS/2 uses the OO interface 708the functional interface, while JSON::XS/2 uses the OO interface
651with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables 709with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables
652shrink). Higher is better: 710shrink). Higher is better:
653 711
712 Storable | 15779.925 | 14169.946 |
713 -----------+------------+------------+
654 module | encode | decode | 714 module | encode | decode |
655 -----------|------------|------------| 715 -----------|------------|------------|
656 JSON | 7645.468 | 4208.613 | 716 JSON | 4990.842 | 4088.813 |
657 JSON::DWIW | 40721.398 | 77101.176 | 717 JSON::DWIW | 51653.990 | 71575.154 |
658 JSON::PC | 65948.176 | 78251.940 | 718 JSON::PC | 65948.176 | 74631.744 |
659 JSON::Syck | 22844.793 | 26479.192 | 719 JSON::PP | 8931.652 | 3817.168 |
720 JSON::Syck | 24877.248 | 27776.848 |
660 JSON::XS | 388361.481 | 199728.762 | 721 JSON::XS | 388361.481 | 227951.304 |
661 JSON::XS/2 | 218453.333 | 192399.266 | 722 JSON::XS/2 | 227951.304 | 218453.333 |
662 JSON::XS/3 | 338250.323 | 192399.266 | 723 JSON::XS/3 | 338250.323 | 218453.333 |
663 Storable | 15779.925 | 14169.946 | 724 Storable | 16500.016 | 135300.129 |
664 -----------+------------+------------+ 725 -----------+------------+------------+
665 726
666That is, JSON::XS is about five times faster than JSON::DWIW on encoding, 727That is, JSON::XS is about five times faster than JSON::DWIW on encoding,
667about three times faster on decoding, and over fourty times faster 728about three times faster on decoding, and over fourty times faster
668than JSON, even with pretty-printing and key sorting. It also compares 729than JSON, even with pretty-printing and key sorting. It also compares
… …
671Using a longer test string (roughly 18KB, generated from Yahoo! Locals 732Using a longer test string (roughly 18KB, generated from Yahoo! Locals
672search API (http://nanoref.com/yahooapis/mgPdGg): 733search API (http://nanoref.com/yahooapis/mgPdGg):
673 734
674 module | encode | decode | 735 module | encode | decode |
675 -----------|------------|------------| 736 -----------|------------|------------|
676 JSON | 254.685 | 37.665 | 737 JSON | 55.260 | 34.971 |
677 JSON::DWIW | 843.343 | 1049.731 | 738 JSON::DWIW | 825.228 | 1082.513 |
678 JSON::PC | 3602.116 | 2307.352 | 739 JSON::PC | 3571.444 | 2394.829 |
740 JSON::PP | 210.987 | 32.574 |
679 JSON::Syck | 505.107 | 787.899 | 741 JSON::Syck | 552.551 | 787.544 |
680 JSON::XS | 5747.196 | 3690.220 | 742 JSON::XS | 5780.463 | 4854.519 |
681 JSON::XS/2 | 3968.121 | 3676.634 | 743 JSON::XS/2 | 3869.998 | 4798.975 |
682 JSON::XS/3 | 6105.246 | 3662.508 | 744 JSON::XS/3 | 5862.880 | 4798.975 |
683 Storable | 4417.337 | 5285.161 | 745 Storable | 4445.002 | 5235.027 |
684 -----------+------------+------------+ 746 -----------+------------+------------+
685 747
686Again, JSON::XS leads by far (except for Storable which non-surprisingly 748Again, JSON::XS leads by far (except for Storable which non-surprisingly
687decodes faster). 749decodes faster).
688 750
… …
705Second, you need to avoid resource-starving attacks. That means you should 767Second, 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 768limit 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 769resources 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 770can 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 771usually a good indication of the size of the resources required to decode
710it into a Perl structure. 772it into a Perl structure. While JSON::XS can check the size of the JSON
773text, it might be too late when you already have it in memory, so you
774might want to check the size before you accept the string.
711 775
712Third, JSON::XS recurses using the C stack when decoding objects and 776Third, JSON::XS recurses using the C stack when decoding objects and
713arrays. The C stack is a limited resource: for instance, on my amd64 777arrays. 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 778machine 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 779only 14k nested JSON objects (due to perl itself recursing deeply on croak
… …
720 784
721And last but least, something else could bomb you that I forgot to think 785And 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, 786of. In that case, you get to keep the pieces. I am always open for hints,
723though... 787though...
724 788
789If you are using JSON::XS to return packets to consumption
790by javascript scripts in a browser you should have a look at
791L<http://jpsykes.com/47/practical-csrf-and-json-security> to see wether
792you are vulnerable to some common attack vectors (which really are browser
793design bugs, but it is still you who will have to deal with it, as major
794browser developers care only for features, not about doing security
795right).
796
725 797
726=head1 BUGS 798=head1 BUGS
727 799
728While the goal of this module is to be correct, that unfortunately does 800While 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 801not 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 802still relatively early in its development. If you keep reporting bugs they
731will be fixed swiftly, though. 803will be fixed swiftly, though.
732 804
733=cut 805=cut
734 806
807our $true = do { bless \(my $dummy = 1), "JSON::XS::Boolean" };
808our $false = do { bless \(my $dummy = 0), "JSON::XS::Boolean" };
809
735sub true() { \1 } 810sub true() { $true }
736sub false() { \0 } 811sub false() { $false }
812
813sub is_bool($) {
814 UNIVERSAL::isa $_[0], "JSON::XS::Boolean"
815# or UNIVERSAL::isa $_[0], "JSON::Literal"
816}
817
818XSLoader::load "JSON::XS", $VERSION;
819
820package JSON::XS::Boolean;
821
822use overload
823 "0+" => sub { ${$_[0]} },
824 "++" => sub { $_[0] = ${$_[0]} + 1 },
825 "--" => sub { $_[0] = ${$_[0]} - 1 },
826 fallback => 1;
737 827
7381; 8281;
739 829
740=head1 AUTHOR 830=head1 AUTHOR
741 831

Diff Legend

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