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

Comparing JSON-XS/XS.pm (file contents):
Revision 1.38 by root, Wed Jun 6 18:16:52 2007 UTC vs.
Revision 1.49 by root, Sun Jul 1 14:08:03 2007 UTC

  # 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;
- # 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;
  $pretty_printed_unencoded = $coder->encode ($perl_scalar);
 package JSON::XS;
 use strict;
-BEGIN {
-   our $VERSION = '1.23';
+our $VERSION = '1.4';
-   our @ISA = qw(Exporter);
+our @ISA = qw(Exporter);
-   our @EXPORT = qw(to_json from_json objToJson jsonToObj);
+our @EXPORT = qw(to_json from_json);
-   require Exporter;
-   require XSLoader;
+use Exporter;
-   XSLoader::load JSON::XS::, $VERSION;
+use XSLoader;
-}
 =head1 FUNCTIONAL INTERFACE
 The following convinience methods are provided by this module. They are
 exported by default:
 This function call is functionally identical to:
    $perl_scalar = JSON::XS->new->utf8->decode ($json_text)
 except being faster.
+=item $is_boolean = JSON::XS::is_bool $scalar
+Returns true if the passed scalar represents either JSON::XS::true or
+JSON::XS::false, two constants that act like C<1> and C<0>, respectively
+and are used to represent JSON C<true> and C<false> values in Perl.
+See MAPPING, below, for more information on how JSON values are mapped to
+Perl.
 =back
 =head1 OBJECT-ORIENTED INTERFACE
 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)
 For the more enlightened: note that in the following descriptions,
 lowercase I<perl> refers to the Perl interpreter, while uppcercase I<Perl>
 refers to the abstract Perl language itself.
 =head2 JSON -> PERL
 =over 4
 =item object
 conversion details, but an integer may take slightly less memory and might
 represent more values exactly than (floating point) numbers.
 =item true, false
-These JSON atoms become C<0>, C<1>, respectively. Information is lost in
+These JSON atoms become C<JSON::XS::true> and C<JSON::XS::false>,
-this process. Future versions might represent those values differently,
+respectively. They are overloaded to act almost exactly like the numbers
-but they will be guarenteed to act like these integers would normally in
+C<1> and C<0>. You can check wether a scalar is a JSON boolean by using
-Perl.
+the C<JSON::XS::is_bool> function.
 =item null
 A JSON null atom becomes C<undef> in Perl.
 =back
 =head2 PERL -> JSON
 The mapping from Perl to JSON is slightly more difficult, as Perl is a
 truly typeless language, so we can only guess which JSON type is meant by
 C<1>, which get turned into C<false> and C<true> atoms in JSON. You can
 also use C<JSON::XS::false> and C<JSON::XS::true> to improve readability.
    to_json [\0,JSON::XS::true]      # yields [false,true]
+=item JSON::XS::true, JSON::XS::false
+These special values become JSON true and JSON false values,
+respectively. You cna alos use C<\1> and C<\0> directly if you want.
 =item blessed objects
 Blessed objects are not allowed. JSON::XS currently tries to encode their
 underlying representation (hash- or arrayref), but this behaviour might
 change in future versions.
 Does not check input for validity.
 =back
+=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.
+If you really must use JSON::XS to generate YAML, you should use this
+algorithm (subject to change in future versions):
+   my $to_yaml = JSON::XS->new->utf8->space_after (1);
+   my $yaml = $to_yaml->encode ($ref) . "\n";
+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 noticably shorter than the 1024 characters YAML allows.
+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.
 =head2 SPEED
 It seems that JSON::XS is surprisingly fast, as shown in the following
 tables. They have been generated with the help of the C<eg/bench> program
 in the JSON::XS distribution, to make it easy to compare on your own
 single-line JSON string:
    {"method": "handleMessage", "params": ["user1", "we were just talking"], \
    "id": null, "array":[1,11,234,-5,1e5,1e7, true,  false]}
-It shows the number of encodes/decodes per second (JSON::XS uses the
+It shows the number of encodes/decodes per second (JSON::XS uses
-functional interface, while JSON::XS/2 uses the OO interface with
+the functional interface, while JSON::XS/2 uses the OO interface
-pretty-printing and hashkey sorting enabled). Higher is better:
+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       |   4990.842 |   4088.813 |
-   JSON::DWIW |  68534.379 |  79437.576 |
+   JSON::DWIW |  51653.990 |  71575.154 |
-   JSON::PC   |  65948.176 |  78251.940 |
+   JSON::PC   |  65948.176 |  74631.744 |
-   JSON::Syck |  23379.621 |  28416.694 |
+   JSON::PP   |   8931.652 |   3817.168 |
+   JSON::Syck |  24877.248 |  27776.848 |
-   JSON::XS   | 388361.481 | 199728.762 |
+   JSON::XS   | 388361.481 | 227951.304 |
-   JSON::XS/2 | 218453.333 | 192399.266 |
+   JSON::XS/2 | 227951.304 | 218453.333 |
-   JSON::XS/3 | 338250.323 | 192399.266 |
+   JSON::XS/3 | 338250.323 | 218453.333 |
-   Storable   |  15732.573 |  28571.553 |
+   Storable   |  16500.016 | 135300.129 |
    -----------+------------+------------+
 That is, JSON::XS is about five times faster than JSON::DWIW on encoding,
 about three times faster on decoding, and over fourty times faster
 than JSON, even with pretty-printing and key sorting. It also compares
 Using a longer test string (roughly 18KB, generated from Yahoo! Locals
 search API (http://nanoref.com/yahooapis/mgPdGg):
    module     |     encode |     decode |
    -----------|------------|------------|
-   JSON       |    254.685 |     37.665 |
+   JSON       |     55.260 |     34.971 |
-   JSON::DWIW |   1014.244 |   1087.678 |
+   JSON::DWIW |    825.228 |   1082.513 |
-   JSON::PC   |   3602.116 |   2307.352 |
+   JSON::PC   |   3571.444 |   2394.829 |
-   JSON::Syck |    558.035 |    776.263 |
+   JSON::PP   |    210.987 |     32.574 |
-   JSON::XS   |   5747.196 |   3543.684 |
+   JSON::Syck |    552.551 |    787.544 |
-   JSON::XS/2 |   3968.121 |   3589.170 |
+   JSON::XS   |   5780.463 |   4854.519 |
-   JSON::XS/3 |   6105.246 |   3561.134 |
+   JSON::XS/2 |   3869.998 |   4798.975 |
-   Storable   |   4456.337 |   5320.020 |
+   JSON::XS/3 |   5862.880 |   4798.975 |
+   Storable   |   4445.002 |   5235.027 |
    -----------+------------+------------+
-Again, JSON::XS leads by far.
+Again, JSON::XS leads by far (except for Storable which non-surprisingly
+decodes faster).
 On large strings containing lots of high unicode characters, some modules
 (such as JSON::PC) seem to decode faster than JSON::XS, but the result
 will be broken due to missing (or wrong) unicode handling. Others refuse
 to decode or encode properly, so it was impossible to prepare a fair
 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
 And last but least, something else could bomb you that I forgot to think
 of. In that case, you get to keep the pieces. I am always open for hints,
 though...
+If you are using JSON::XS to return packets to consumption
+by javascript scripts in a browser you should have a look at
+L<http://jpsykes.com/47/practical-csrf-and-json-security> to see wether
+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
+right).
 =head1 BUGS
 While the goal of this module is to be correct, that unfortunately does
 not mean its bug-free, only that I think its design is bug-free. It is
 still relatively early in its development. If you keep reporting bugs they
 will be fixed swiftly, though.
 =cut
+our $true  = do { bless \(my $dummy = 1), "JSON::XS::Boolean" };
+our $false = do { bless \(my $dummy = 0), "JSON::XS::Boolean" };
-sub true()  { \1 }
+sub true()  { $true  }
-sub false() { \0 }
+sub false() { $false }
+sub is_bool($) {
+   UNIVERSAL::isa $_[0], "JSON::XS::Boolean"
+#      or UNIVERSAL::isa $_[0], "JSON::Literal"
+}
+XSLoader::load "JSON::XS", $VERSION;
+package JSON::XS::Boolean;
+use overload
+   "0+"     => sub { ${$_[0]} },
+   "++"     => sub { $_[0] = ${$_[0]} + 1 },
+   "--"     => sub { $_[0] = ${$_[0]} - 1 },
+   fallback => 1;
 1;
 =head1 AUTHOR

Diff Legend

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

Comparing JSON-XS/XS.pm (file contents): Revision 1.38 by root, Wed Jun 6 18:16:52 2007 UTC vs. Revision 1.49 by root, Sun Jul 1 14:08:03 2007 UTC

Diff Legend

Comparing JSON-XS/XS.pm (file contents):
Revision 1.38 by root, Wed Jun 6 18:16:52 2007 UTC vs.
Revision 1.49 by root, Sun Jul 1 14:08:03 2007 UTC