[ViewVC] Diff of: cvs/JSON-XS/XS.pm

Comparing JSON-XS/XS.pm (file contents):
Revision 1.43 by root, Sat Jun 23 23:49:29 2007 UTC vs.
Revision 1.47 by root, Mon Jun 25 06:57:42 2007 UTC

 package JSON::XS;
 use strict;
-our $VERSION = '1.3';
+our $VERSION = '1.4';
 our @ISA = qw(Exporter);
 our @EXPORT = qw(to_json from_json objToJson jsonToObj);
 use Exporter;
 Example, encode a Perl scalar as JSON value with enabled C<allow_nonref>,
 resulting in an invalid JSON text:
    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<encode> method will not
+barf when it encounters a blessed reference. Instead, the value of the
+B<convert_blessed> option will decide wether C<null> (C<convert_blessed>
+disabled or no C<to_json> method found) or a representation of the
+object (C<convert_blessed> enabled and C<to_json> method found) is being
+encoded. Has no effect on C<decode>.
+If C<$enable> is false (the default), then C<encode> 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<encode>, upon encountering a
+blessed object, will check for the availability of the C<TO_JSON> 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<TO_JSON> method is found, the value of C<allow_blessed> will decide what
+to do.
+The C<TO_JSON> method may safely call die if it wants. If C<TO_JSON>
+returns other blessed objects, those will be handled in the same
+way. C<TO_JSON> must take care of not causing an endless recursion cycle
+(== crash) in this case. The name of C<TO_JSON> 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<to_json>
+function.
+This setting does not yet influence C<decode> in any way, but in the
+future, global hooks might get installed that influence C<decode> and are
+enabled by this setting.
+If C<$enable> is false, then the C<allow_blessed> 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
 strings. This flag optionally resizes strings generated by either
 given character in a string.
 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<max_depth> will be rounded up to the next nearest power
+The argument to C<max_depth> will be rounded up to the next highest power
-of two.
+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<decode>
+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<encode> (yet).
+The argument to C<max_size> will be rounded up to the next B<highest>
+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.
 =item $json_text = $json->encode ($perl_scalar)
 Second, you need to avoid resource-starving attacks. That means you should
 limit the size of JSON texts you accept, or make sure then when your
 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
 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
 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;
 package JSON::XS::Boolean;

Diff Legend

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

Comparing JSON-XS/XS.pm (file contents): Revision 1.43 by root, Sat Jun 23 23:49:29 2007 UTC vs. Revision 1.47 by root, Mon Jun 25 06:57:42 2007 UTC

Diff Legend

Comparing JSON-XS/XS.pm (file contents):
Revision 1.43 by root, Sat Jun 23 23:49:29 2007 UTC vs.
Revision 1.47 by root, Mon Jun 25 06:57:42 2007 UTC