--- JSON-XS/XS.pm 2007/06/23 23:49:29 1.43 +++ JSON-XS/XS.pm 2007/07/02 00:29:38 1.50 @@ -12,10 +12,6 @@ $utf8_encoded_json_text = to_json $perl_hash_or_arrayref; $perl_hash_or_arrayref = from_json $utf8_encoded_json_text; - # objToJson and jsonToObj aliases to to_json and from_json - # are exported for compatibility to the JSON module, - # but should not be used in new code. - # OO-interface $coder = JSON::XS->new->ascii->pretty->allow_nonref; @@ -87,10 +83,10 @@ use strict; -our $VERSION = '1.3'; +our $VERSION = '1.4'; our @ISA = qw(Exporter); -our @EXPORT = qw(to_json from_json objToJson jsonToObj); +our @EXPORT = qw(to_json from_json); use Exporter; use XSLoader; @@ -318,6 +314,42 @@ JSON::XS->new->allow_nonref->encode ("Hello, World!") => "Hello, World!" +=item $json = $json->allow_blessed ([$enable]) + +If C<$enable> is true (or missing), then the C method will not +barf when it encounters a blessed reference. Instead, the value of the +B option will decide wether C (C +disabled or no C method found) or a representation of the +object (C enabled and C method found) is being +encoded. Has no effect on C. + +If C<$enable> is false (the default), then C will throw an +exception when it encounters a blessed object. + +=item $json = $json->convert_blessed ([$enable]) + +If C<$enable> is true (or missing), then C, upon encountering a +blessed object, will check for the availability of the C method +on the object's class. If found, it will be called in scalar context +and the resulting scalar will be encoded instead of the object. If no +C method is found, the value of C will decide what +to do. + +The C method may safely call die if it wants. If C +returns other blessed objects, those will be handled in the same +way. C must take care of not causing an endless recursion cycle +(== crash) in this case. The name of C was chosen because other +methods called by the Perl core (== not by the user of the object) are +usually in upper case letters and to avoid collisions with the C +function. + +This setting does not yet influence C in any way, but in the +future, global hooks might get installed that influence C and are +enabled by this setting. + +If C<$enable> is false, then the C setting will decide what +to do when a blessed object is found. + =item $json = $json->shrink ([$enable]) Perl usually over-allocates memory a bit when allocating space for @@ -359,8 +391,23 @@ Setting the maximum depth to one disallows any nesting, so that ensures that the object is only a single hash/object or array. -The argument to C will be rounded up to the next nearest power -of two. +The argument to C will be rounded up to the next highest power +of two. If no argument is given, the highest possible setting will be +used, which is rarely useful. + +See SECURITY CONSIDERATIONS, below, for more info on why this is useful. + +=item $json = $json->max_size ([$maximum_string_size]) + +Set the maximum length a JSON text may have (in bytes) where decoding is +being attempted. The default is C<0>, meaning no limit. When C +is called on a string longer then this number of characters it will not +attempt to decode the string but throw an exception. This setting has no +effect on C (yet). + +The argument to C will be rounded up to the next B +power of two (so may be more than requested). If no argument is given, the +limit check will be deactivated (same as when C<0> is specified). See SECURITY CONSIDERATIONS, below, for more info on why this is useful. @@ -662,16 +709,19 @@ with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables shrink). Higher is better: + Storable | 15779.925 | 14169.946 | + -----------+------------+------------+ module | encode | decode | -----------|------------|------------| - JSON | 7645.468 | 4208.613 | - JSON::DWIW | 40721.398 | 77101.176 | - JSON::PC | 65948.176 | 78251.940 | - JSON::Syck | 22844.793 | 26479.192 | - JSON::XS | 388361.481 | 199728.762 | - JSON::XS/2 | 218453.333 | 192399.266 | - JSON::XS/3 | 338250.323 | 192399.266 | - Storable | 15779.925 | 14169.946 | + JSON | 4990.842 | 4088.813 | + JSON::DWIW | 51653.990 | 71575.154 | + JSON::PC | 65948.176 | 74631.744 | + JSON::PP | 8931.652 | 3817.168 | + JSON::Syck | 24877.248 | 27776.848 | + JSON::XS | 388361.481 | 227951.304 | + JSON::XS/2 | 227951.304 | 218453.333 | + JSON::XS/3 | 338250.323 | 218453.333 | + Storable | 16500.016 | 135300.129 | -----------+------------+------------+ That is, JSON::XS is about five times faster than JSON::DWIW on encoding, @@ -684,14 +734,15 @@ module | encode | decode | -----------|------------|------------| - JSON | 254.685 | 37.665 | - JSON::DWIW | 843.343 | 1049.731 | - JSON::PC | 3602.116 | 2307.352 | - JSON::Syck | 505.107 | 787.899 | - JSON::XS | 5747.196 | 3690.220 | - JSON::XS/2 | 3968.121 | 3676.634 | - JSON::XS/3 | 6105.246 | 3662.508 | - Storable | 4417.337 | 5285.161 | + JSON | 55.260 | 34.971 | + JSON::DWIW | 825.228 | 1082.513 | + JSON::PC | 3571.444 | 2394.829 | + JSON::PP | 210.987 | 32.574 | + JSON::Syck | 552.551 | 787.544 | + JSON::XS | 5780.463 | 4854.519 | + JSON::XS/2 | 3869.998 | 4798.975 | + JSON::XS/3 | 5862.880 | 4798.975 | + Storable | 4445.002 | 5235.027 | -----------+------------+------------+ Again, JSON::XS leads by far (except for Storable which non-surprisingly @@ -718,7 +769,9 @@ resources run out, thats just fine (e.g. by using a separate process that can crash safely). The size of a JSON text in octets or characters is usually a good indication of the size of the resources required to decode -it into a Perl structure. +it into a Perl structure. While JSON::XS can check the size of the JSON +text, it might be too late when you already have it in memory, so you +might want to check the size before you accept the string. Third, JSON::XS recurses using the C stack when decoding objects and arrays. The C stack is a limited resource: for instance, on my amd64 @@ -751,15 +804,15 @@ =cut -our $true = do { bless \(my $dummy = 1), "JSON::XS::Boolean" }; -our $false = do { bless \(my $dummy = 0), "JSON::XS::Boolean" }; +our $true = do { bless \(my $dummy = "1"), "JSON::XS::Boolean" }; +our $false = do { bless \(my $dummy = "0"), "JSON::XS::Boolean" }; sub true() { $true } sub false() { $false } sub is_bool($) { UNIVERSAL::isa $_[0], "JSON::XS::Boolean" - or UNIVERSAL::isa $_[0], "JSON::Literal" +# or UNIVERSAL::isa $_[0], "JSON::Literal" } XSLoader::load "JSON::XS", $VERSION;