--- JSON-XS/XS.pm 2007/10/23 03:30:02 1.68 +++ JSON-XS/XS.pm 2007/11/25 19:11:07 1.72 @@ -86,7 +86,7 @@ use strict; -our $VERSION = '1.52'; +our $VERSION = '1.53'; our @ISA = qw(Exporter); our @EXPORT = qw(to_json from_json); @@ -204,6 +204,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 +227,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 +252,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 @@ -273,6 +279,8 @@ =item $json = $json->pretty ([$enable]) +=item $enabled = $json->get_pretty + This enables (or disables) all of the C, C and C (and in the future possibly more) flags in one call to generate the most readable (or most compact) form possible. @@ -290,6 +298,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 +311,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 +328,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 +346,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 +411,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,6 +431,8 @@ =item $json = $json->allow_blessed ([$enable]) +=item $enabled = $json->get_allow_bless + 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 @@ -423,6 +445,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 @@ -523,6 +547,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 +575,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 +598,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 @@ -782,7 +812,7 @@ undocumented. One can get far by feeding it Unicode strings and doing en-/decoding oneself, but Unicode escapes are not working properly). -No roundtripping (strings get clobbered if they look like numbers, e.g. +No round-tripping (strings get clobbered if they look like numbers, e.g. the string C<2.0> will encode to C<2.0> instead of C<"2.0">, and that will decode into the number 2. @@ -792,7 +822,7 @@ Undocumented/buggy Unicode handling. -No roundtripping. +No round-tripping. Has problems handling many Perl values (e.g. regex results and other magic values will make it croak). @@ -816,7 +846,7 @@ escapes are not working properly, you need to set ImplicitUnicode to I values on en- and decoding to get symmetric behaviour). -No roundtripping (simple cases work, but this depends on whether the scalar +No round-tripping (simple cases work, but this depends on whether the scalar value was used in a numeric context or not). Dumping hashes may skip hash values depending on iterator state. @@ -841,7 +871,7 @@ Very inflexible. -No roundtripping. +No round-tripping. Does not generate valid JSON texts (key strings are often unquoted, empty keys result in nothing being output) @@ -892,11 +922,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 +945,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 |