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.61 by root, Wed Sep 12 17:42:36 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.5';
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
… …
282 278
283Example, space_before and indent disabled, space_after enabled: 279Example, space_before and indent disabled, space_after enabled:
284 280
285 {"key": "value"} 281 {"key": "value"}
286 282
283=item $json = $json->relaxed ([$enable])
284
285If C<$enable> is true (or missing), then C<decode> will accept some
286extensions to normal JSON syntax (see below). C<encode> will not be
287affected in anyway. I<Be aware that this option makes you accept invalid
288JSON texts as if they were valid!>. I suggest only to use this option to
289parse application-specific files written by humans (configuration files,
290resource files etc.)
291
292If C<$enable> is false (the default), then C<decode> will only accept
293valid JSON texts.
294
295Currently accepted extensions are:
296
297=over 4
298
299=item * list items can have an end-comma
300
301JSON I<separates> array elements and key-value pairs with commas. This
302can be annoying if you write JSON texts manually and want to be able to
303quickly append elements, so this extension accepts comma at the end of
304such items not just between them:
305
306 [
307 1,
308 2, <- this comma not normally allowed
309 ]
310 {
311 "k1": "v1",
312 "k2": "v2", <- this comma not normally allowed
313 }
314
315=item * shell-style '#'-comments
316
317Whenever JSON allows whitespace, shell-style comments are additionally
318allowed. They are terminated by the first carriage-return or line-feed
319character, after which more white-space and comments are allowed.
320
321 [
322 1, # this comment not allowed in JSON
323 # neither this one...
324 ]
325
326=back
327
287=item $json = $json->canonical ([$enable]) 328=item $json = $json->canonical ([$enable])
288 329
289If C<$enable> is true (or missing), then the C<encode> method will output JSON objects 330If C<$enable> is true (or missing), then the C<encode> method will output JSON objects
290by sorting their keys. This is adding a comparatively high overhead. 331by sorting their keys. This is adding a comparatively high overhead.
291 332
… …
351future, global hooks might get installed that influence C<decode> and are 392future, global hooks might get installed that influence C<decode> and are
352enabled by this setting. 393enabled by this setting.
353 394
354If C<$enable> is false, then the C<allow_blessed> setting will decide what 395If C<$enable> is false, then the C<allow_blessed> setting will decide what
355to do when a blessed object is found. 396to do when a blessed object is found.
397
398=item $json = $json->filter_json_object ([$coderef->($hashref)])
399
400When C<$coderef> is specified, it will be called from C<decode> each
401time it decodes a JSON object. The only argument is a reference to the
402newly-created hash. If the code references returns a single scalar (which
403need not be a reference), this value (i.e. a copy of that scalar to avoid
404aliasing) is inserted into the deserialised data structure. If it returns
405an empty list (NOTE: I<not> C<undef>, which is a valid scalar), the
406original deserialised hash will be inserted. This setting can slow down
407decoding considerably.
408
409When C<$coderef> is omitted or undefined, any existing callback will
410be removed and C<decode> will not change the deserialised hash in any
411way.
412
413Example, convert all JSON objects into the integer 5:
414
415 my $js = JSON::XS->new->filter_json_object (sub { 5 });
416 # returns [5]
417 $js->decode ('[{}]')
418 # throw an exception because allow_nonref is not enabled
419 # so a lone 5 is not allowed.
420 $js->decode ('{"a":1, "b":2}');
421
422=item $json = $json->filter_json_single_key_object ($key [=> $coderef->($value)])
423
424Works remotely similar to C<filter_json_object>, but is only called for
425JSON objects having a single key named C<$key>.
426
427This C<$coderef> is called before the one specified via
428C<filter_json_object>, if any. It gets passed the single value in the JSON
429object. If it returns a single value, it will be inserted into the data
430structure. If it returns nothing (not even C<undef> but the empty list),
431the callback from C<filter_json_object> will be called next, as if no
432single-key callback were specified.
433
434If C<$coderef> is omitted or undefined, the corresponding callback will be
435disabled. There can only ever be one callback for a given key.
436
437As this callback gets called less often then the C<filter_json_object>
438one, decoding speed will not usually suffer as much. Therefore, single-key
439objects make excellent targets to serialise Perl objects into, especially
440as single-key JSON objects are as close to the type-tagged value concept
441as JSON gets (its basically an ID/VALUE tuple). Of course, JSON does not
442support this in any way, so you need to make sure your data never looks
443like a serialised Perl hash.
444
445Typical names for the single object key are C<__class_whatever__>, or
446C<$__dollars_are_rarely_used__$> or C<}ugly_brace_placement>, or even
447things like C<__class_md5sum(classname)__>, to reduce the risk of clashing
448with real hashes.
449
450Example, decode JSON objects of the form C<< { "__widget__" => <id> } >>
451into the corresponding C<< $WIDGET{<id>} >> object:
452
453 # return whatever is in $WIDGET{5}:
454 JSON::XS
455 ->new
456 ->filter_json_single_key_object (__widget__ => sub {
457 $WIDGET{ $_[0] }
458 })
459 ->decode ('{"__widget__": 5')
460
461 # this can be used with a TO_JSON method in some "widget" class
462 # for serialisation to json:
463 sub WidgetBase::TO_JSON {
464 my ($self) = @_;
465
466 unless ($self->{id}) {
467 $self->{id} = ..get..some..id..;
468 $WIDGET{$self->{id}} = $self;
469 }
470
471 { __widget__ => $self->{id} }
472 }
356 473
357=item $json = $json->shrink ([$enable]) 474=item $json = $json->shrink ([$enable])
358 475
359Perl usually over-allocates memory a bit when allocating space for 476Perl usually over-allocates memory a bit when allocating space for
360strings. This flag optionally resizes strings generated by either 477strings. This flag optionally resizes strings generated by either
… …
481are represented by the same codepoints in the Perl string, so no manual 598are represented by the same codepoints in the Perl string, so no manual
482decoding is necessary. 599decoding is necessary.
483 600
484=item number 601=item number
485 602
486A JSON number becomes either an integer or numeric (floating point) 603A JSON number becomes either an integer, numeric (floating point) or
487scalar in perl, depending on its range and any fractional parts. On the 604string scalar in perl, depending on its range and any fractional parts. On
488Perl level, there is no difference between those as Perl handles all the 605the Perl level, there is no difference between those as Perl handles all
489conversion details, but an integer may take slightly less memory and might 606the conversion details, but an integer may take slightly less memory and
490represent more values exactly than (floating point) numbers. 607might represent more values exactly than (floating point) numbers.
608
609If the number consists of digits only, JSON::XS will try to represent
610it as an integer value. If that fails, it will try to represent it as
611a numeric (floating point) value if that is possible without loss of
612precision. Otherwise it will preserve the number as a string value.
613
614Numbers containing a fractional or exponential part will always be
615represented as numeric (floating point) values, possibly at a loss of
616precision.
617
618This might create round-tripping problems as numbers might become strings,
619but as Perl is typeless there is no other way to do it.
491 620
492=item true, false 621=item true, false
493 622
494These JSON atoms become C<JSON::XS::true> and C<JSON::XS::false>, 623These JSON atoms become C<JSON::XS::true> and C<JSON::XS::false>,
495respectively. They are overloaded to act almost exactly like the numbers 624respectively. They are overloaded to act almost exactly like the numbers
… …
537 to_json [\0,JSON::XS::true] # yields [false,true] 666 to_json [\0,JSON::XS::true] # yields [false,true]
538 667
539=item JSON::XS::true, JSON::XS::false 668=item JSON::XS::true, JSON::XS::false
540 669
541These special values become JSON true and JSON false values, 670These special values become JSON true and JSON false values,
542respectively. You cna alos use C<\1> and C<\0> directly if you want. 671respectively. You can also use C<\1> and C<\0> directly if you want.
543 672
544=item blessed objects 673=item blessed objects
545 674
546Blessed objects are not allowed. JSON::XS currently tries to encode their 675Blessed objects are not allowed. JSON::XS currently tries to encode their
547underlying representation (hash- or arrayref), but this behaviour might 676underlying representation (hash- or arrayref), but this behaviour might
… …
711It shows the number of encodes/decodes per second (JSON::XS uses 840It shows the number of encodes/decodes per second (JSON::XS uses
712the functional interface, while JSON::XS/2 uses the OO interface 841the functional interface, while JSON::XS/2 uses the OO interface
713with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables 842with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables
714shrink). Higher is better: 843shrink). Higher is better:
715 844
845 Storable | 15779.925 | 14169.946 |
846 -----------+------------+------------+
716 module | encode | decode | 847 module | encode | decode |
717 -----------|------------|------------| 848 -----------|------------|------------|
718 JSON | 7645.468 | 4208.613 | 849 JSON | 4990.842 | 4088.813 |
719 JSON::DWIW | 40721.398 | 77101.176 | 850 JSON::DWIW | 51653.990 | 71575.154 |
720 JSON::PC | 65948.176 | 78251.940 | 851 JSON::PC | 65948.176 | 74631.744 |
721 JSON::Syck | 22844.793 | 26479.192 | 852 JSON::PP | 8931.652 | 3817.168 |
853 JSON::Syck | 24877.248 | 27776.848 |
722 JSON::XS | 388361.481 | 199728.762 | 854 JSON::XS | 388361.481 | 227951.304 |
723 JSON::XS/2 | 218453.333 | 192399.266 | 855 JSON::XS/2 | 227951.304 | 218453.333 |
724 JSON::XS/3 | 338250.323 | 192399.266 | 856 JSON::XS/3 | 338250.323 | 218453.333 |
725 Storable | 15779.925 | 14169.946 | 857 Storable | 16500.016 | 135300.129 |
726 -----------+------------+------------+ 858 -----------+------------+------------+
727 859
728That is, JSON::XS is about five times faster than JSON::DWIW on encoding, 860That is, JSON::XS is about five times faster than JSON::DWIW on encoding,
729about three times faster on decoding, and over fourty times faster 861about three times faster on decoding, and over fourty times faster
730than JSON, even with pretty-printing and key sorting. It also compares 862than JSON, even with pretty-printing and key sorting. It also compares
… …
733Using a longer test string (roughly 18KB, generated from Yahoo! Locals 865Using a longer test string (roughly 18KB, generated from Yahoo! Locals
734search API (http://nanoref.com/yahooapis/mgPdGg): 866search API (http://nanoref.com/yahooapis/mgPdGg):
735 867
736 module | encode | decode | 868 module | encode | decode |
737 -----------|------------|------------| 869 -----------|------------|------------|
738 JSON | 254.685 | 37.665 | 870 JSON | 55.260 | 34.971 |
739 JSON::DWIW | 843.343 | 1049.731 | 871 JSON::DWIW | 825.228 | 1082.513 |
740 JSON::PC | 3602.116 | 2307.352 | 872 JSON::PC | 3571.444 | 2394.829 |
873 JSON::PP | 210.987 | 32.574 |
741 JSON::Syck | 505.107 | 787.899 | 874 JSON::Syck | 552.551 | 787.544 |
742 JSON::XS | 5747.196 | 3690.220 | 875 JSON::XS | 5780.463 | 4854.519 |
743 JSON::XS/2 | 3968.121 | 3676.634 | 876 JSON::XS/2 | 3869.998 | 4798.975 |
744 JSON::XS/3 | 6105.246 | 3662.508 | 877 JSON::XS/3 | 5862.880 | 4798.975 |
745 Storable | 4417.337 | 5285.161 | 878 Storable | 4445.002 | 5235.027 |
746 -----------+------------+------------+ 879 -----------+------------+------------+
747 880
748Again, JSON::XS leads by far (except for Storable which non-surprisingly 881Again, JSON::XS leads by far (except for Storable which non-surprisingly
749decodes faster). 882decodes faster).
750 883

Diff Legend

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