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.47 by root, Mon Jun 25 06:57:42 2007 UTC vs.
Revision 1.55 by root, Mon Jul 23 22:57:40 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);
… …
85 81
86package JSON::XS; 82package JSON::XS;
87 83
88use strict; 84use strict;
89 85
90our $VERSION = '1.4'; 86our $VERSION = '1.42';
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
… …
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->($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 }
356 428
357=item $json = $json->shrink ([$enable]) 429=item $json = $json->shrink ([$enable])
358 430
359Perl usually over-allocates memory a bit when allocating space for 431Perl usually over-allocates memory a bit when allocating space for
360strings. This flag optionally resizes strings generated by either 432strings. This flag optionally resizes strings generated by either
… …
711It shows the number of encodes/decodes per second (JSON::XS uses 783It shows the number of encodes/decodes per second (JSON::XS uses
712the functional interface, while JSON::XS/2 uses the OO interface 784the functional interface, while JSON::XS/2 uses the OO interface
713with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables 785with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables
714shrink). Higher is better: 786shrink). Higher is better:
715 787
788 Storable | 15779.925 | 14169.946 |
789 -----------+------------+------------+
716 module | encode | decode | 790 module | encode | decode |
717 -----------|------------|------------| 791 -----------|------------|------------|
718 JSON | 7645.468 | 4208.613 | 792 JSON | 4990.842 | 4088.813 |
719 JSON::DWIW | 40721.398 | 77101.176 | 793 JSON::DWIW | 51653.990 | 71575.154 |
720 JSON::PC | 65948.176 | 78251.940 | 794 JSON::PC | 65948.176 | 74631.744 |
721 JSON::Syck | 22844.793 | 26479.192 | 795 JSON::PP | 8931.652 | 3817.168 |
796 JSON::Syck | 24877.248 | 27776.848 |
722 JSON::XS | 388361.481 | 199728.762 | 797 JSON::XS | 388361.481 | 227951.304 |
723 JSON::XS/2 | 218453.333 | 192399.266 | 798 JSON::XS/2 | 227951.304 | 218453.333 |
724 JSON::XS/3 | 338250.323 | 192399.266 | 799 JSON::XS/3 | 338250.323 | 218453.333 |
725 Storable | 15779.925 | 14169.946 | 800 Storable | 16500.016 | 135300.129 |
726 -----------+------------+------------+ 801 -----------+------------+------------+
727 802
728That 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,
729about three times faster on decoding, and over fourty times faster 804about three times faster on decoding, and over fourty times faster
730than JSON, even with pretty-printing and key sorting. It also compares 805than JSON, even with pretty-printing and key sorting. It also compares
… …
733Using a longer test string (roughly 18KB, generated from Yahoo! Locals 808Using a longer test string (roughly 18KB, generated from Yahoo! Locals
734search API (http://nanoref.com/yahooapis/mgPdGg): 809search API (http://nanoref.com/yahooapis/mgPdGg):
735 810
736 module | encode | decode | 811 module | encode | decode |
737 -----------|------------|------------| 812 -----------|------------|------------|
738 JSON | 254.685 | 37.665 | 813 JSON | 55.260 | 34.971 |
739 JSON::DWIW | 843.343 | 1049.731 | 814 JSON::DWIW | 825.228 | 1082.513 |
740 JSON::PC | 3602.116 | 2307.352 | 815 JSON::PC | 3571.444 | 2394.829 |
816 JSON::PP | 210.987 | 32.574 |
741 JSON::Syck | 505.107 | 787.899 | 817 JSON::Syck | 552.551 | 787.544 |
742 JSON::XS | 5747.196 | 3690.220 | 818 JSON::XS | 5780.463 | 4854.519 |
743 JSON::XS/2 | 3968.121 | 3676.634 | 819 JSON::XS/2 | 3869.998 | 4798.975 |
744 JSON::XS/3 | 6105.246 | 3662.508 | 820 JSON::XS/3 | 5862.880 | 4798.975 |
745 Storable | 4417.337 | 5285.161 | 821 Storable | 4445.002 | 5235.027 |
746 -----------+------------+------------+ 822 -----------+------------+------------+
747 823
748Again, JSON::XS leads by far (except for Storable which non-surprisingly 824Again, JSON::XS leads by far (except for Storable which non-surprisingly
749decodes faster). 825decodes faster).
750 826

Diff Legend

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