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

Comparing JSON-XS/XS.pm (file contents):
Revision 1.39 by root, Mon Jun 11 02:58:10 2007 UTC vs.
Revision 1.44 by root, Mon Jun 25 04:08:17 2007 UTC

 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 objToJson jsonToObj);
-   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 the user of the object) are
+usually in upper case letters and to avoid collisions with the C<to_json>
+function.
+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
 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.
 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.
 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 this
+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 object key lengths
+YAML. Please note that YAML has hardcoded limits on (simple) object key
-that JSON doesn't have, so you should make sure that your hash keys are
+lengths that JSON doesn't have, so you should make sure that your hash
-noticably shorter than 1024 characters.
+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.
+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
 shrink). Higher is better:
    module     |     encode |     decode |
    -----------|------------|------------|
    JSON       |   7645.468 |   4208.613 |
-   JSON::DWIW |  68534.379 |  79437.576 |
+   JSON::DWIW |  40721.398 |  77101.176 |
    JSON::PC   |  65948.176 |  78251.940 |
-   JSON::Syck |  23379.621 |  28416.694 |
+   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   |  15732.573 |  28571.553 |
+   Storable   |  15779.925 |  14169.946 |
    -----------+------------+------------+
 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
 search API (http://nanoref.com/yahooapis/mgPdGg):
    module     |     encode |     decode |
    -----------|------------|------------|
    JSON       |    254.685 |     37.665 |
-   JSON::DWIW |   1014.244 |   1087.678 |
+   JSON::DWIW |    843.343 |   1049.731 |
    JSON::PC   |   3602.116 |   2307.352 |
-   JSON::Syck |    558.035 |    776.263 |
+   JSON::Syck |    505.107 |    787.899 |
-   JSON::XS   |   5747.196 |   3543.684 |
+   JSON::XS   |   5747.196 |   3690.220 |
-   JSON::XS/2 |   3968.121 |   3589.170 |
+   JSON::XS/2 |   3968.121 |   3676.634 |
-   JSON::XS/3 |   6105.246 |   3561.134 |
+   JSON::XS/3 |   6105.246 |   3662.508 |
-   Storable   |   4456.337 |   5320.020 |
+   Storable   |   4417.337 |   5285.161 |
    -----------+------------+------------+
-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
 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.39 by root, Mon Jun 11 02:58:10 2007 UTC vs. Revision 1.44 by root, Mon Jun 25 04:08:17 2007 UTC

Diff Legend

Comparing JSON-XS/XS.pm (file contents):
Revision 1.39 by root, Mon Jun 11 02:58:10 2007 UTC vs.
Revision 1.44 by root, Mon Jun 25 04:08:17 2007 UTC