ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/JSON-XS/XS.pm
(Generate patch)

Comparing JSON-XS/XS.pm (file contents):
Revision 1.45 by root, Mon Jun 25 04:16:46 2007 UTC vs.
Revision 1.51 by root, Mon Jul 2 01:12:27 2007 UTC

… …
9 # exported functions, they croak on error 9 # exported functions, they croak on error
10 # and expect/generate UTF-8 10 # and expect/generate UTF-8
11 11
12 $utf8_encoded_json_text = to_json $perl_hash_or_arrayref; 12 $utf8_encoded_json_text = to_json $perl_hash_or_arrayref;
13 $perl_hash_or_arrayref = from_json $utf8_encoded_json_text; 13 $perl_hash_or_arrayref = from_json $utf8_encoded_json_text;
14
15 # objToJson and jsonToObj aliases to to_json and from_json
16 # are exported for compatibility to the JSON module,
17 # but should not be used in new code.
18 14
19 # OO-interface 15 # OO-interface
20 16
21 $coder = JSON::XS->new->ascii->pretty->allow_nonref; 17 $coder = JSON::XS->new->ascii->pretty->allow_nonref;
22 $pretty_printed_unencoded = $coder->encode ($perl_scalar); 18 $pretty_printed_unencoded = $coder->encode ($perl_scalar);
… …
88use strict; 84use strict;
89 85
90our $VERSION = '1.4'; 86our $VERSION = '1.4';
91our @ISA = qw(Exporter); 87our @ISA = qw(Exporter);
92 88
93our @EXPORT = qw(to_json from_json objToJson jsonToObj); 89our @EXPORT = qw(to_json from_json);
94 90
95use Exporter; 91use Exporter;
96use XSLoader; 92use XSLoader;
97 93
98=head1 FUNCTIONAL INTERFACE 94=head1 FUNCTIONAL INTERFACE
… …
341 337
342The C<TO_JSON> method may safely call die if it wants. If C<TO_JSON> 338The C<TO_JSON> method may safely call die if it wants. If C<TO_JSON>
343returns other blessed objects, those will be handled in the same 339returns other blessed objects, those will be handled in the same
344way. C<TO_JSON> must take care of not causing an endless recursion cycle 340way. C<TO_JSON> must take care of not causing an endless recursion cycle
345(== crash) in this case. The name of C<TO_JSON> was chosen because other 341(== crash) in this case. The name of C<TO_JSON> was chosen because other
346methods called by the Perl core (== not the user of the object) are 342methods called by the Perl core (== not by the user of the object) are
347usually in upper case letters and to avoid collisions with the C<to_json> 343usually in upper case letters and to avoid collisions with the C<to_json>
348function. 344function.
349 345
350This setting does not yet influence C<decode> in any way, but in the 346This setting does not yet influence C<decode> in any way, but in the
351future, global hooks might get installed that influence C<decode> and are 347future, global hooks might get installed that influence C<decode> and are
352enabled by this setting. 348enabled by this setting.
353 349
354If C<$enable> is false, then the C<allow_blessed> setting will decide what 350If C<$enable> is false, then the C<allow_blessed> setting will decide what
355to do when a blessed object is found. 351to do when a blessed object is found.
352
353=item $json = $json->filter_json_object ([$coderef])
354
355When C<$coderef> is specified, it will be called from C<decode> each
356time it decodes a JSON object. The only argument is a reference to the
357newly-created hash. If the code references returns a single scalar (which
358need not be a reference), this value (i.e. a copy of that scalar to avoid
359aliasing) is inserted into the deserialised data structure. If it returns
360an empty list (NOTE: I<not> C<undef>, which is a valid scalar), the
361original deserialised hash will be inserted. This setting can slow down
362decoding considerably.
363
364When C<$coderef> is omitted or undefined, C<decode> will not change the
365deserialised hash in any way. This is maximally fast.
366
367Example, convert all JSON objects into the integer 5:
368
369 my $js = JSON::XS->new->filter_json_object (sub { 5 });
370 # returns [5]
371 $js->decode ('[{}]')
372 # throw an exception because allow_nonref is not enabled:
373 $js->decode ('{"a":1, "b":2}');
374
375=item $json = $json->filter_json_single_key_object ([$coderef])
376
377Works like C<filter_json_object>, but is only called for JSON objects
378having only a single key.
379
380This C<$coderef> is called before the one specified via
381C<filter_json_object>, if any. If it returns something, that will be
382inserted into the data structure. If it returns nothing, the callback
383from C<filter_json_object> will be called next. If you want to force
384insertion of single-key objects even in the presence of a mutating
385C<filter_json_object> callback, simply return the passed hash.
386
387As this callback gets called less often then the C<filter_json_object>
388one, decoding speed will not usually suffer as much. Therefore, single-key
389objects make excellent targets to serialise Perl objects into, especially
390as single-key JSON objects are as close to the type-tagged value concept
391as JSON gets (its basically an ID/VALUE tuple). Of course, JSON does not
392support this in any way, so you need to make sure your data never looks
393like a serialised Perl hash.
394
395Typical names for the single object key are C<__class_whatever__>, or
396C<$__dollars_are_rarely_used__$> or C<}ugly_brace_placement>, or even
397things like C<__class_md5sum(classname)__>, to reduce the risk of clashing
398with real hashes.
399
400Example, decode JSON objects of the form C<< { "__widget__" => <id> } >>
401into the corresponding C<< $WIDGET{<id>} >> object:
402
403 # return whatever is in $WIDGET{5}:
404 JSON::XS
405 ->new
406 ->filter_json_single_key_object (sub {
407 exists $_[0]{__widget__}
408 ? $WIDGET{ $_[0]{__widget__} }
409 : ()
410 })
411 ->decode ('{"__widget__": 5')
412
413 # this can be used with a TO_JSON method in some "widget" class
414 # for serialisation to json:
415 sub WidgetBase::TO_JSON {
416 my ($self) = @_;
417
418 unless ($self->{id}) {
419 $self->{id} = ..get..some..id..;
420 $WIDGET{$self->{id}} = $self;
421 }
422
423 { __widget__ => $self->{id} }
424 }
356 425
357=item $json = $json->shrink ([$enable]) 426=item $json = $json->shrink ([$enable])
358 427
359Perl usually over-allocates memory a bit when allocating space for 428Perl usually over-allocates memory a bit when allocating space for
360strings. This flag optionally resizes strings generated by either 429strings. This flag optionally resizes strings generated by either
… …
393given character in a string. 462given character in a string.
394 463
395Setting the maximum depth to one disallows any nesting, so that ensures 464Setting the maximum depth to one disallows any nesting, so that ensures
396that the object is only a single hash/object or array. 465that the object is only a single hash/object or array.
397 466
398The argument to C<max_depth> will be rounded up to the next nearest power 467The argument to C<max_depth> will be rounded up to the next highest power
399of two. 468of two. If no argument is given, the highest possible setting will be
469used, which is rarely useful.
470
471See SECURITY CONSIDERATIONS, below, for more info on why this is useful.
472
473=item $json = $json->max_size ([$maximum_string_size])
474
475Set the maximum length a JSON text may have (in bytes) where decoding is
476being attempted. The default is C<0>, meaning no limit. When C<decode>
477is called on a string longer then this number of characters it will not
478attempt to decode the string but throw an exception. This setting has no
479effect on C<encode> (yet).
480
481The argument to C<max_size> will be rounded up to the next B<highest>
482power of two (so may be more than requested). If no argument is given, the
483limit check will be deactivated (same as when C<0> is specified).
400 484
401See SECURITY CONSIDERATIONS, below, for more info on why this is useful. 485See SECURITY CONSIDERATIONS, below, for more info on why this is useful.
402 486
403=item $json_text = $json->encode ($perl_scalar) 487=item $json_text = $json->encode ($perl_scalar)
404 488
… …
696It shows the number of encodes/decodes per second (JSON::XS uses 780It shows the number of encodes/decodes per second (JSON::XS uses
697the functional interface, while JSON::XS/2 uses the OO interface 781the functional interface, while JSON::XS/2 uses the OO interface
698with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables 782with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables
699shrink). Higher is better: 783shrink). Higher is better:
700 784
785 Storable | 15779.925 | 14169.946 |
786 -----------+------------+------------+
701 module | encode | decode | 787 module | encode | decode |
702 -----------|------------|------------| 788 -----------|------------|------------|
703 JSON | 7645.468 | 4208.613 | 789 JSON | 4990.842 | 4088.813 |
704 JSON::DWIW | 40721.398 | 77101.176 | 790 JSON::DWIW | 51653.990 | 71575.154 |
705 JSON::PC | 65948.176 | 78251.940 | 791 JSON::PC | 65948.176 | 74631.744 |
706 JSON::Syck | 22844.793 | 26479.192 | 792 JSON::PP | 8931.652 | 3817.168 |
793 JSON::Syck | 24877.248 | 27776.848 |
707 JSON::XS | 388361.481 | 199728.762 | 794 JSON::XS | 388361.481 | 227951.304 |
708 JSON::XS/2 | 218453.333 | 192399.266 | 795 JSON::XS/2 | 227951.304 | 218453.333 |
709 JSON::XS/3 | 338250.323 | 192399.266 | 796 JSON::XS/3 | 338250.323 | 218453.333 |
710 Storable | 15779.925 | 14169.946 | 797 Storable | 16500.016 | 135300.129 |
711 -----------+------------+------------+ 798 -----------+------------+------------+
712 799
713That is, JSON::XS is about five times faster than JSON::DWIW on encoding, 800That is, JSON::XS is about five times faster than JSON::DWIW on encoding,
714about three times faster on decoding, and over fourty times faster 801about three times faster on decoding, and over fourty times faster
715than JSON, even with pretty-printing and key sorting. It also compares 802than JSON, even with pretty-printing and key sorting. It also compares
… …
718Using a longer test string (roughly 18KB, generated from Yahoo! Locals 805Using a longer test string (roughly 18KB, generated from Yahoo! Locals
719search API (http://nanoref.com/yahooapis/mgPdGg): 806search API (http://nanoref.com/yahooapis/mgPdGg):
720 807
721 module | encode | decode | 808 module | encode | decode |
722 -----------|------------|------------| 809 -----------|------------|------------|
723 JSON | 254.685 | 37.665 | 810 JSON | 55.260 | 34.971 |
724 JSON::DWIW | 843.343 | 1049.731 | 811 JSON::DWIW | 825.228 | 1082.513 |
725 JSON::PC | 3602.116 | 2307.352 | 812 JSON::PC | 3571.444 | 2394.829 |
813 JSON::PP | 210.987 | 32.574 |
726 JSON::Syck | 505.107 | 787.899 | 814 JSON::Syck | 552.551 | 787.544 |
727 JSON::XS | 5747.196 | 3690.220 | 815 JSON::XS | 5780.463 | 4854.519 |
728 JSON::XS/2 | 3968.121 | 3676.634 | 816 JSON::XS/2 | 3869.998 | 4798.975 |
729 JSON::XS/3 | 6105.246 | 3662.508 | 817 JSON::XS/3 | 5862.880 | 4798.975 |
730 Storable | 4417.337 | 5285.161 | 818 Storable | 4445.002 | 5235.027 |
731 -----------+------------+------------+ 819 -----------+------------+------------+
732 820
733Again, JSON::XS leads by far (except for Storable which non-surprisingly 821Again, JSON::XS leads by far (except for Storable which non-surprisingly
734decodes faster). 822decodes faster).
735 823
… …
752Second, you need to avoid resource-starving attacks. That means you should 840Second, you need to avoid resource-starving attacks. That means you should
753limit the size of JSON texts you accept, or make sure then when your 841limit the size of JSON texts you accept, or make sure then when your
754resources run out, thats just fine (e.g. by using a separate process that 842resources run out, thats just fine (e.g. by using a separate process that
755can crash safely). The size of a JSON text in octets or characters is 843can crash safely). The size of a JSON text in octets or characters is
756usually a good indication of the size of the resources required to decode 844usually a good indication of the size of the resources required to decode
757it into a Perl structure. 845it into a Perl structure. While JSON::XS can check the size of the JSON
846text, it might be too late when you already have it in memory, so you
847might want to check the size before you accept the string.
758 848
759Third, JSON::XS recurses using the C stack when decoding objects and 849Third, JSON::XS recurses using the C stack when decoding objects and
760arrays. The C stack is a limited resource: for instance, on my amd64 850arrays. The C stack is a limited resource: for instance, on my amd64
761machine with 8MB of stack size I can decode around 180k nested arrays but 851machine with 8MB of stack size I can decode around 180k nested arrays but
762only 14k nested JSON objects (due to perl itself recursing deeply on croak 852only 14k nested JSON objects (due to perl itself recursing deeply on croak
… …
785still relatively early in its development. If you keep reporting bugs they 875still relatively early in its development. If you keep reporting bugs they
786will be fixed swiftly, though. 876will be fixed swiftly, though.
787 877
788=cut 878=cut
789 879
790our $true = do { bless \(my $dummy = 1), "JSON::XS::Boolean" }; 880our $true = do { bless \(my $dummy = "1"), "JSON::XS::Boolean" };
791our $false = do { bless \(my $dummy = 0), "JSON::XS::Boolean" }; 881our $false = do { bless \(my $dummy = "0"), "JSON::XS::Boolean" };
792 882
793sub true() { $true } 883sub true() { $true }
794sub false() { $false } 884sub false() { $false }
795 885
796sub is_bool($) { 886sub is_bool($) {

Diff Legend

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