--- JSON-XS/XS.pm 2007/11/13 22:59:08 1.70 +++ JSON-XS/XS.pm 2007/12/29 17:33:38 1.81 @@ -12,8 +12,8 @@ # exported functions, they croak on error # and expect/generate UTF-8 - $utf8_encoded_json_text = to_json $perl_hash_or_arrayref; - $perl_hash_or_arrayref = from_json $utf8_encoded_json_text; + $utf8_encoded_json_text = encode_json $perl_hash_or_arrayref; + $perl_hash_or_arrayref = decode_json $utf8_encoded_json_text; # OO-interface @@ -21,12 +21,28 @@ $pretty_printed_unencoded = $coder->encode ($perl_scalar); $perl_scalar = $coder->decode ($unicode_json_text); + # Note that JSON version 2.0 and above will automatically use JSON::XS + # if available, at virtually no speed overhead either, so you should + # be able to just: + + use JSON; + + # and do the same things, except that you have a pure-perl fallback now. + =head1 DESCRIPTION This module converts Perl data structures to JSON and vice versa. Its primary goal is to be I and its secondary goal is to be I. To reach the latter goal it was written in C. +Beginning with version 2.0 of the JSON module, when both JSON and +JSON::XS are installed, then JSON will fall back on JSON::XS (this can be +overriden) with no overhead due to emulation (by inheritign constructor +and methods). If JSON::XS is not available, it will fall back to the +compatible JSON::PP module as backend, so using JSON instead of JSON::XS +gives you a portable JSON API that can be fast when you need and doesn't +require a C compiler when that is a problem. + As this is the n-th-something JSON module on CPAN, what was the reason to write yet another JSON module? While it seems there are many JSON modules, none of them correctly handle all corner cases, and in most cases @@ -86,10 +102,20 @@ use strict; -our $VERSION = '1.53'; +our $VERSION = '2.01'; our @ISA = qw(Exporter); -our @EXPORT = qw(to_json from_json); +our @EXPORT = qw(encode_json decode_json to_json from_json); + +sub to_json($) { + require Carp; + Carp::croak ("JSON::XS::to_json has been renamed to encode_json, either downgrade to pre-2.0 versions of JSON::XS or rename the call"); +} + +sub from_json($) { + require Carp; + Carp::croak ("JSON::XS::from_json has been renamed to decode_json, either downgrade to pre-2.0 versions of JSON::XS or rename the call"); +} use Exporter; use XSLoader; @@ -101,7 +127,7 @@ =over 4 -=item $json_text = to_json $perl_scalar +=item $json_text = encode_json $perl_scalar Converts the given Perl data structure to a UTF-8 encoded, binary string (that is, the string contains octets only). Croaks on error. @@ -112,9 +138,9 @@ except being faster. -=item $perl_scalar = from_json $json_text +=item $perl_scalar = decode_json $json_text -The opposite of C: expects an UTF-8 (binary) string and tries +The opposite of C: expects an UTF-8 (binary) string and tries to parse that as an UTF-8 encoded JSON text, returning the resulting reference. Croaks on error. @@ -204,6 +230,8 @@ =item $json = $json->ascii ([$enable]) +=item $enabled = $json->get_ascii + If C<$enable> is true (or missing), then the C method will not generate characters outside the code range C<0..127> (which is ASCII). Any Unicode characters outside that range will be escaped using either a @@ -225,6 +253,8 @@ =item $json = $json->latin1 ([$enable]) +=item $enabled = $json->get_latin1 + If C<$enable> is true (or missing), then the C method will encode the resulting JSON text as latin1 (or iso-8859-1), escaping any characters outside the code range C<0..255>. The resulting string can be treated as a @@ -248,6 +278,8 @@ =item $json = $json->utf8 ([$enable]) +=item $enabled = $json->get_utf8 + If C<$enable> is true (or missing), then the C method will encode the JSON result into UTF-8, as required by many protocols, while the C method expects to be handled an UTF-8-encoded string. Please @@ -290,6 +322,8 @@ =item $json = $json->indent ([$enable]) +=item $enabled = $json->get_indent + If C<$enable> is true (or missing), then the C method will use a multiline format as output, putting every array member or object/hash key-value pair into its own line, indenting them properly. @@ -301,6 +335,8 @@ =item $json = $json->space_before ([$enable]) +=item $enabled = $json->get_space_before + If C<$enable> is true (or missing), then the C method will add an extra optional space before the C<:> separating keys from values in JSON objects. @@ -316,6 +352,8 @@ =item $json = $json->space_after ([$enable]) +=item $enabled = $json->get_space_after + If C<$enable> is true (or missing), then the C method will add an extra optional space after the C<:> separating keys from values in JSON objects and extra whitespace after the C<,> separating key-value pairs and array @@ -332,6 +370,8 @@ =item $json = $json->relaxed ([$enable]) +=item $enabled = $json->get_relaxed + If C<$enable> is true (or missing), then C will accept some extensions to normal JSON syntax (see below). C will not be affected in anyway. Icanonical ([$enable]) +=item $enabled = $json->get_canonical + If C<$enable> is true (or missing), then the C method will output JSON objects by sorting their keys. This is adding a comparatively high overhead. @@ -393,6 +435,8 @@ =item $json = $json->allow_nonref ([$enable]) +=item $enabled = $json->get_allow_nonref + If C<$enable> is true (or missing), then the C method can convert a non-reference into its corresponding string, number or null JSON value, which is an extension to RFC4627. Likewise, C will accept those JSON @@ -411,11 +455,13 @@ =item $json = $json->allow_blessed ([$enable]) +=item $enabled = $json->get_allow_blessed + 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 whether C (C -disabled or no C method found) or a representation of the -object (C enabled and C method found) is being +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 @@ -423,6 +469,8 @@ =item $json = $json->convert_blessed ([$enable]) +=item $enabled = $json->get_convert_blessed + 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 @@ -435,8 +483,8 @@ 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. +usually in upper case letters and to avoid collisions with any C +function or method. This setting does not yet influence C in any way, but in the future, global hooks might get installed that influence C and are @@ -523,6 +571,8 @@ =item $json = $json->shrink ([$enable]) +=item $enabled = $json->get_shrink + Perl usually over-allocates memory a bit when allocating space for strings. This flag optionally resizes strings generated by either C or C to their minimum size possible. This can save @@ -549,6 +599,8 @@ =item $json = $json->max_depth ([$maximum_nesting_depth]) +=item $max_depth = $json->get_max_depth + Sets the maximum nesting level (default C<512>) accepted while encoding or decoding. If the JSON text or Perl data structure has an equal or higher nesting level then this limit, then the encoder and decoder will @@ -570,6 +622,8 @@ =item $json = $json->max_size ([$maximum_string_size]) +=item $max_size = $json->get_max_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 @@ -713,7 +767,7 @@ C<1>, which get turned into C and C atoms in JSON. You can also use C and C to improve readability. - to_json [\0,JSON::XS::true] # yields [false,true] + encode_json [\0,JSON::XS::true] # yields [false,true] =item JSON::XS::true, JSON::XS::false @@ -734,16 +788,16 @@ before encoding as JSON strings and anything else as number value: # dump as number - to_json [2] # yields [2] - to_json [-3.0e17] # yields [-3e+17] - my $value = 5; to_json [$value] # yields [5] + encode_json [2] # yields [2] + encode_json [-3.0e17] # yields [-3e+17] + my $value = 5; encode_json [$value] # yields [5] # used as string, so dump as string print $value; - to_json [$value] # yields ["5"] + encode_json [$value] # yields ["5"] # undef becomes null - to_json [undef] # yields [null] + encode_json [undef] # yields [null] You can force the type to be a JSON string by stringifying it: @@ -853,9 +907,10 @@ =head2 JSON and YAML -You often hear that JSON is a subset (or a close subset) of YAML. This is, -however, a mass hysteria and very far from the truth. In general, there is -no way to configure JSON::XS to output a data structure as valid YAML. +You often hear that JSON is a subset of YAML. This is, however, a mass +hysteria and very far from the truth. In general, there is no way to +configure JSON::XS to output a data structure as valid YAML that works for +all cases. If you really must use JSON::XS to generate YAML, you should use this algorithm (subject to change in future versions): @@ -865,13 +920,18 @@ This will usually generate JSON texts that also parse as valid YAML. Please note that YAML has hardcoded limits on (simple) object key -lengths that JSON doesn't have, so you should make sure that your hash -keys are noticeably shorter than the 1024 characters YAML allows. +lengths that JSON doesn't have and also has different and incompatible +unicode handling, so you should make sure that your hash keys are +noticeably shorter than the 1024 "stream characters" YAML allows and that +you do not have codepoints with values outside the Unicode BMP (basic +multilingual page). YAML also does not allow C<\/> sequences in strings +(which JSON::XS does not I generate). There might be other incompatibilities that I am not aware of. In general you should not try to generate YAML with a JSON generator or vice versa, or try to parse JSON with a YAML parser or vice versa: chances are high -that you will run into severe interoperability problems. +that you will run into severe interoperability problems when you least +expect it. =head2 SPEED @@ -892,11 +952,9 @@ with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables shrink). Higher is better: - Storable | 15779.925 | 14169.946 | - -----------+------------+------------+ module | encode | decode | -----------|------------|------------| - JSON | 4990.842 | 4088.813 | + JSON 1.x | 4990.842 | 4088.813 | JSON::DWIW | 51653.990 | 71575.154 | JSON::PC | 65948.176 | 74631.744 | JSON::PP | 8931.652 | 3817.168 | @@ -917,7 +975,7 @@ module | encode | decode | -----------|------------|------------| - JSON | 55.260 | 34.971 | + JSON 1.x | 55.260 | 34.971 | JSON::DWIW | 825.228 | 1082.513 | JSON::PC | 3571.444 | 2394.829 | JSON::PP | 210.987 | 32.574 | @@ -960,7 +1018,7 @@ arrays. The C stack is a limited resource: for instance, on my amd64 machine with 8MB of stack size I can decode around 180k nested arrays but only 14k nested JSON objects (due to perl itself recursing deeply on croak -to free the temporary). If that is exceeded, the program crashes. to be +to free the temporary). If that is exceeded, the program crashes. To be conservative, the default nesting limit is set to 512. If your process has a smaller stack, you should adjust this setting accordingly with the C method. @@ -974,7 +1032,7 @@ L to see whether you are vulnerable to some common attack vectors (which really are browser design bugs, but it is still you who will have to deal with it, as major -browser developers care only for features, not about doing security +browser developers care only for features, not about getting security right).