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.44 by root, Mon Jun 25 04:08:17 2007 UTC vs.
Revision 1.52 by root, Mon Jul 2 02:57:11 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
346This setting does not yet influence C<decode> in any way, but in the
347future, global hooks might get installed that influence C<decode> and are
348enabled by this setting.
349
350If 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
351to do when a blessed object is found. 351to do when a blessed object is found.
352
353=item $json = $json->filter_json_object ([$coderef->($hashref)])
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, any existing callback will
365be removed and C<decode> will not change the deserialised hash in any
366way.
367
368Example, convert all JSON objects into the integer 5:
369
370 my $js = JSON::XS->new->filter_json_object (sub { 5 });
371 # returns [5]
372 $js->decode ('[{}]')
373 # throw an exception because allow_nonref is not enabled
374 # so a lone 5 is not allowed.
375 $js->decode ('{"a":1, "b":2}');
376
377=item $json = $json->filter_json_single_key_object ($key [=> $coderef->($value)])
378
379Works remotely similar to C<filter_json_object>, but is only called for
380JSON objects having a single key named C<$key>.
381
382This C<$coderef> is called before the one specified via
383C<filter_json_object>, if any. It gets passed the single value in the JSON
384object. If it returns a single value, it will be inserted into the data
385structure. If it returns nothing (not even C<undef> but the empty list),
386the callback from C<filter_json_object> will be called next, as if no
387single-key callback were specified.
388
389If C<$coderef> is omitted or undefined, the corresponding callback will be
390disabled. There can only ever be one callback for a given key.
391
392As this callback gets called less often then the C<filter_json_object>
393one, decoding speed will not usually suffer as much. Therefore, single-key
394objects make excellent targets to serialise Perl objects into, especially
395as single-key JSON objects are as close to the type-tagged value concept
396as JSON gets (its basically an ID/VALUE tuple). Of course, JSON does not
397support this in any way, so you need to make sure your data never looks
398like a serialised Perl hash.
399
400Typical names for the single object key are C<__class_whatever__>, or
401C<$__dollars_are_rarely_used__$> or C<}ugly_brace_placement>, or even
402things like C<__class_md5sum(classname)__>, to reduce the risk of clashing
403with real hashes.
404
405Example, decode JSON objects of the form C<< { "__widget__" => <id> } >>
406into the corresponding C<< $WIDGET{<id>} >> object:
407
408 # return whatever is in $WIDGET{5}:
409 JSON::XS
410 ->new
411 ->filter_json_single_key_object (__widget__ => sub {
412 $WIDGET{ $_[0] }
413 })
414 ->decode ('{"__widget__": 5')
415
416 # this can be used with a TO_JSON method in some "widget" class
417 # for serialisation to json:
418 sub WidgetBase::TO_JSON {
419 my ($self) = @_;
420
421 unless ($self->{id}) {
422 $self->{id} = ..get..some..id..;
423 $WIDGET{$self->{id}} = $self;
424 }
425
426 { __widget__ => $self->{id} }
427 }
352 428
353=item $json = $json->shrink ([$enable]) 429=item $json = $json->shrink ([$enable])
354 430
355Perl usually over-allocates memory a bit when allocating space for 431Perl usually over-allocates memory a bit when allocating space for
356strings. This flag optionally resizes strings generated by either 432strings. This flag optionally resizes strings generated by either
… …
389given character in a string. 465given character in a string.
390 466
391Setting the maximum depth to one disallows any nesting, so that ensures 467Setting the maximum depth to one disallows any nesting, so that ensures
392that the object is only a single hash/object or array. 468that the object is only a single hash/object or array.
393 469
394The argument to C<max_depth> will be rounded up to the next nearest power 470The argument to C<max_depth> will be rounded up to the next highest power
395of two. 471of two. If no argument is given, the highest possible setting will be
472used, which is rarely useful.
473
474See SECURITY CONSIDERATIONS, below, for more info on why this is useful.
475
476=item $json = $json->max_size ([$maximum_string_size])
477
478Set the maximum length a JSON text may have (in bytes) where decoding is
479being attempted. The default is C<0>, meaning no limit. When C<decode>
480is called on a string longer then this number of characters it will not
481attempt to decode the string but throw an exception. This setting has no
482effect on C<encode> (yet).
483
484The argument to C<max_size> will be rounded up to the next B<highest>
485power of two (so may be more than requested). If no argument is given, the
486limit check will be deactivated (same as when C<0> is specified).
396 487
397See SECURITY CONSIDERATIONS, below, for more info on why this is useful. 488See SECURITY CONSIDERATIONS, below, for more info on why this is useful.
398 489
399=item $json_text = $json->encode ($perl_scalar) 490=item $json_text = $json->encode ($perl_scalar)
400 491
… …
692It shows the number of encodes/decodes per second (JSON::XS uses 783It shows the number of encodes/decodes per second (JSON::XS uses
693the functional interface, while JSON::XS/2 uses the OO interface 784the functional interface, while JSON::XS/2 uses the OO interface
694with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables 785with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables
695shrink). Higher is better: 786shrink). Higher is better:
696 787
788 Storable | 15779.925 | 14169.946 |
789 -----------+------------+------------+
697 module | encode | decode | 790 module | encode | decode |
698 -----------|------------|------------| 791 -----------|------------|------------|
699 JSON | 7645.468 | 4208.613 | 792 JSON | 4990.842 | 4088.813 |
700 JSON::DWIW | 40721.398 | 77101.176 | 793 JSON::DWIW | 51653.990 | 71575.154 |
701 JSON::PC | 65948.176 | 78251.940 | 794 JSON::PC | 65948.176 | 74631.744 |
702 JSON::Syck | 22844.793 | 26479.192 | 795 JSON::PP | 8931.652 | 3817.168 |
796 JSON::Syck | 24877.248 | 27776.848 |
703 JSON::XS | 388361.481 | 199728.762 | 797 JSON::XS | 388361.481 | 227951.304 |
704 JSON::XS/2 | 218453.333 | 192399.266 | 798 JSON::XS/2 | 227951.304 | 218453.333 |
705 JSON::XS/3 | 338250.323 | 192399.266 | 799 JSON::XS/3 | 338250.323 | 218453.333 |
706 Storable | 15779.925 | 14169.946 | 800 Storable | 16500.016 | 135300.129 |
707 -----------+------------+------------+ 801 -----------+------------+------------+
708 802
709That is, JSON::XS is about five times faster than JSON::DWIW on encoding, 803That is, JSON::XS is about five times faster than JSON::DWIW on encoding,
710about three times faster on decoding, and over fourty times faster 804about three times faster on decoding, and over fourty times faster
711than JSON, even with pretty-printing and key sorting. It also compares 805than JSON, even with pretty-printing and key sorting. It also compares
… …
714Using a longer test string (roughly 18KB, generated from Yahoo! Locals 808Using a longer test string (roughly 18KB, generated from Yahoo! Locals
715search API (http://nanoref.com/yahooapis/mgPdGg): 809search API (http://nanoref.com/yahooapis/mgPdGg):
716 810
717 module | encode | decode | 811 module | encode | decode |
718 -----------|------------|------------| 812 -----------|------------|------------|
719 JSON | 254.685 | 37.665 | 813 JSON | 55.260 | 34.971 |
720 JSON::DWIW | 843.343 | 1049.731 | 814 JSON::DWIW | 825.228 | 1082.513 |
721 JSON::PC | 3602.116 | 2307.352 | 815 JSON::PC | 3571.444 | 2394.829 |
816 JSON::PP | 210.987 | 32.574 |
722 JSON::Syck | 505.107 | 787.899 | 817 JSON::Syck | 552.551 | 787.544 |
723 JSON::XS | 5747.196 | 3690.220 | 818 JSON::XS | 5780.463 | 4854.519 |
724 JSON::XS/2 | 3968.121 | 3676.634 | 819 JSON::XS/2 | 3869.998 | 4798.975 |
725 JSON::XS/3 | 6105.246 | 3662.508 | 820 JSON::XS/3 | 5862.880 | 4798.975 |
726 Storable | 4417.337 | 5285.161 | 821 Storable | 4445.002 | 5235.027 |
727 -----------+------------+------------+ 822 -----------+------------+------------+
728 823
729Again, JSON::XS leads by far (except for Storable which non-surprisingly 824Again, JSON::XS leads by far (except for Storable which non-surprisingly
730decodes faster). 825decodes faster).
731 826
… …
748Second, you need to avoid resource-starving attacks. That means you should 843Second, you need to avoid resource-starving attacks. That means you should
749limit the size of JSON texts you accept, or make sure then when your 844limit the size of JSON texts you accept, or make sure then when your
750resources run out, thats just fine (e.g. by using a separate process that 845resources run out, thats just fine (e.g. by using a separate process that
751can crash safely). The size of a JSON text in octets or characters is 846can crash safely). The size of a JSON text in octets or characters is
752usually a good indication of the size of the resources required to decode 847usually a good indication of the size of the resources required to decode
753it into a Perl structure. 848it into a Perl structure. While JSON::XS can check the size of the JSON
849text, it might be too late when you already have it in memory, so you
850might want to check the size before you accept the string.
754 851
755Third, JSON::XS recurses using the C stack when decoding objects and 852Third, JSON::XS recurses using the C stack when decoding objects and
756arrays. The C stack is a limited resource: for instance, on my amd64 853arrays. The C stack is a limited resource: for instance, on my amd64
757machine with 8MB of stack size I can decode around 180k nested arrays but 854machine with 8MB of stack size I can decode around 180k nested arrays but
758only 14k nested JSON objects (due to perl itself recursing deeply on croak 855only 14k nested JSON objects (due to perl itself recursing deeply on croak
… …
781still relatively early in its development. If you keep reporting bugs they 878still relatively early in its development. If you keep reporting bugs they
782will be fixed swiftly, though. 879will be fixed swiftly, though.
783 880
784=cut 881=cut
785 882
786our $true = do { bless \(my $dummy = 1), "JSON::XS::Boolean" }; 883our $true = do { bless \(my $dummy = "1"), "JSON::XS::Boolean" };
787our $false = do { bless \(my $dummy = 0), "JSON::XS::Boolean" }; 884our $false = do { bless \(my $dummy = "0"), "JSON::XS::Boolean" };
788 885
789sub true() { $true } 886sub true() { $true }
790sub false() { $false } 887sub false() { $false }
791 888
792sub is_bool($) { 889sub is_bool($) {

Diff Legend

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