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.39 by root, Mon Jun 11 02:58:10 2007 UTC vs.
Revision 1.58 by root, Sun Aug 26 21:56:47 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
90BEGIN {
91 our $VERSION = '1.23'; 86our $VERSION = '1.5';
92 our @ISA = qw(Exporter); 87our @ISA = qw(Exporter);
93 88
94 our @EXPORT = qw(to_json from_json objToJson jsonToObj); 89our @EXPORT = qw(to_json from_json);
95 require Exporter;
96 90
97 require XSLoader; 91use Exporter;
98 XSLoader::load JSON::XS::, $VERSION; 92use XSLoader;
99}
100 93
101=head1 FUNCTIONAL INTERFACE 94=head1 FUNCTIONAL INTERFACE
102 95
103The following convinience methods are provided by this module. They are 96The following convinience methods are provided by this module. They are
104exported by default: 97exported by default:
… …
126This function call is functionally identical to: 119This function call is functionally identical to:
127 120
128 $perl_scalar = JSON::XS->new->utf8->decode ($json_text) 121 $perl_scalar = JSON::XS->new->utf8->decode ($json_text)
129 122
130except being faster. 123except being faster.
124
125=item $is_boolean = JSON::XS::is_bool $scalar
126
127Returns true if the passed scalar represents either JSON::XS::true or
128JSON::XS::false, two constants that act like C<1> and C<0>, respectively
129and are used to represent JSON C<true> and C<false> values in Perl.
130
131See MAPPING, below, for more information on how JSON values are mapped to
132Perl.
131 133
132=back 134=back
133 135
134 136
135=head1 OBJECT-ORIENTED INTERFACE 137=head1 OBJECT-ORIENTED INTERFACE
… …
309Example, encode a Perl scalar as JSON value with enabled C<allow_nonref>, 311Example, encode a Perl scalar as JSON value with enabled C<allow_nonref>,
310resulting in an invalid JSON text: 312resulting in an invalid JSON text:
311 313
312 JSON::XS->new->allow_nonref->encode ("Hello, World!") 314 JSON::XS->new->allow_nonref->encode ("Hello, World!")
313 => "Hello, World!" 315 => "Hello, World!"
316
317=item $json = $json->allow_blessed ([$enable])
318
319If C<$enable> is true (or missing), then the C<encode> method will not
320barf when it encounters a blessed reference. Instead, the value of the
321B<convert_blessed> option will decide wether C<null> (C<convert_blessed>
322disabled or no C<to_json> method found) or a representation of the
323object (C<convert_blessed> enabled and C<to_json> method found) is being
324encoded. Has no effect on C<decode>.
325
326If C<$enable> is false (the default), then C<encode> will throw an
327exception when it encounters a blessed object.
328
329=item $json = $json->convert_blessed ([$enable])
330
331If C<$enable> is true (or missing), then C<encode>, upon encountering a
332blessed object, will check for the availability of the C<TO_JSON> method
333on the object's class. If found, it will be called in scalar context
334and the resulting scalar will be encoded instead of the object. If no
335C<TO_JSON> method is found, the value of C<allow_blessed> will decide what
336to do.
337
338The C<TO_JSON> method may safely call die if it wants. If C<TO_JSON>
339returns other blessed objects, those will be handled in the same
340way. C<TO_JSON> must take care of not causing an endless recursion cycle
341(== crash) in this case. The name of C<TO_JSON> was chosen because other
342methods called by the Perl core (== not by the user of the object) are
343usually in upper case letters and to avoid collisions with the C<to_json>
344function.
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
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 }
314 428
315=item $json = $json->shrink ([$enable]) 429=item $json = $json->shrink ([$enable])
316 430
317Perl usually over-allocates memory a bit when allocating space for 431Perl usually over-allocates memory a bit when allocating space for
318strings. This flag optionally resizes strings generated by either 432strings. This flag optionally resizes strings generated by either
… …
351given character in a string. 465given character in a string.
352 466
353Setting the maximum depth to one disallows any nesting, so that ensures 467Setting the maximum depth to one disallows any nesting, so that ensures
354that the object is only a single hash/object or array. 468that the object is only a single hash/object or array.
355 469
356The 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
357of 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).
358 487
359See SECURITY CONSIDERATIONS, below, for more info on why this is useful. 488See SECURITY CONSIDERATIONS, below, for more info on why this is useful.
360 489
361=item $json_text = $json->encode ($perl_scalar) 490=item $json_text = $json->encode ($perl_scalar)
362 491
… …
424are represented by the same codepoints in the Perl string, so no manual 553are represented by the same codepoints in the Perl string, so no manual
425decoding is necessary. 554decoding is necessary.
426 555
427=item number 556=item number
428 557
429A JSON number becomes either an integer or numeric (floating point) 558A JSON number becomes either an integer, numeric (floating point) or
430scalar in perl, depending on its range and any fractional parts. On the 559string scalar in perl, depending on its range and any fractional parts. On
431Perl level, there is no difference between those as Perl handles all the 560the Perl level, there is no difference between those as Perl handles all
432conversion details, but an integer may take slightly less memory and might 561the conversion details, but an integer may take slightly less memory and
433represent more values exactly than (floating point) numbers. 562might represent more values exactly than (floating point) numbers.
563
564If the number consists of digits only, JSON::XS will try to represent
565it as an integer value. If that fails, it will try to represent it as
566a numeric (floating point) value if that is possible without loss of
567precision. Otherwise it will preserve the number as a string value.
568
569Numbers containing a fractional or exponential part will always be
570represented as numeric (floating point) values, possibly at a loss of
571precision.
572
573This might create round-tripping problems as numbers might become strings,
574but as Perl is typeless there is no other way to do it.
434 575
435=item true, false 576=item true, false
436 577
437These JSON atoms become C<0>, C<1>, respectively. Information is lost in 578These JSON atoms become C<JSON::XS::true> and C<JSON::XS::false>,
438this process. Future versions might represent those values differently, 579respectively. They are overloaded to act almost exactly like the numbers
439but they will be guarenteed to act like these integers would normally in 580C<1> and C<0>. You can check wether a scalar is a JSON boolean by using
440Perl. 581the C<JSON::XS::is_bool> function.
441 582
442=item null 583=item null
443 584
444A JSON null atom becomes C<undef> in Perl. 585A JSON null atom becomes C<undef> in Perl.
445 586
… …
477C<1>, which get turned into C<false> and C<true> atoms in JSON. You can 618C<1>, which get turned into C<false> and C<true> atoms in JSON. You can
478also use C<JSON::XS::false> and C<JSON::XS::true> to improve readability. 619also use C<JSON::XS::false> and C<JSON::XS::true> to improve readability.
479 620
480 to_json [\0,JSON::XS::true] # yields [false,true] 621 to_json [\0,JSON::XS::true] # yields [false,true]
481 622
623=item JSON::XS::true, JSON::XS::false
624
625These special values become JSON true and JSON false values,
626respectively. You cna alos use C<\1> and C<\0> directly if you want.
627
482=item blessed objects 628=item blessed objects
483 629
484Blessed objects are not allowed. JSON::XS currently tries to encode their 630Blessed objects are not allowed. JSON::XS currently tries to encode their
485underlying representation (hash- or arrayref), but this behaviour might 631underlying representation (hash- or arrayref), but this behaviour might
486change in future versions. 632change in future versions.
… …
614 760
615You often hear that JSON is a subset (or a close subset) of YAML. This is, 761You often hear that JSON is a subset (or a close subset) of YAML. This is,
616however, a mass hysteria and very far from the truth. In general, there is 762however, a mass hysteria and very far from the truth. In general, there is
617no way to configure JSON::XS to output a data structure as valid YAML. 763no way to configure JSON::XS to output a data structure as valid YAML.
618 764
619If you really must use JSON::XS to generate YAML, you should this 765If you really must use JSON::XS to generate YAML, you should use this
620algorithm (subject to change in future versions): 766algorithm (subject to change in future versions):
621 767
622 my $to_yaml = JSON::XS->new->utf8->space_after (1); 768 my $to_yaml = JSON::XS->new->utf8->space_after (1);
623 my $yaml = $to_yaml->encode ($ref) . "\n"; 769 my $yaml = $to_yaml->encode ($ref) . "\n";
624 770
625This will usually generate JSON texts that also parse as valid 771This will usually generate JSON texts that also parse as valid
626YAML. Please note that YAML has hardcoded limits on object key lengths 772YAML. Please note that YAML has hardcoded limits on (simple) object key
627that JSON doesn't have, so you should make sure that your hash keys are 773lengths that JSON doesn't have, so you should make sure that your hash
628noticably shorter than 1024 characters. 774keys are noticably shorter than the 1024 characters YAML allows.
629 775
630There might be other incompatibilities that I am not aware of. In general 776There might be other incompatibilities that I am not aware of. In general
631you should not try to generate YAML with a JSON generator or vice versa, 777you should not try to generate YAML with a JSON generator or vice versa,
632or try to parse JSON with a YAML parser or vice versa. 778or try to parse JSON with a YAML parser or vice versa: chances are high
779that you will run into severe interoperability problems.
633 780
634 781
635=head2 SPEED 782=head2 SPEED
636 783
637It seems that JSON::XS is surprisingly fast, as shown in the following 784It seems that JSON::XS is surprisingly fast, as shown in the following
… …
648It shows the number of encodes/decodes per second (JSON::XS uses 795It shows the number of encodes/decodes per second (JSON::XS uses
649the functional interface, while JSON::XS/2 uses the OO interface 796the functional interface, while JSON::XS/2 uses the OO interface
650with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables 797with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables
651shrink). Higher is better: 798shrink). Higher is better:
652 799
800 Storable | 15779.925 | 14169.946 |
801 -----------+------------+------------+
653 module | encode | decode | 802 module | encode | decode |
654 -----------|------------|------------| 803 -----------|------------|------------|
655 JSON | 7645.468 | 4208.613 | 804 JSON | 4990.842 | 4088.813 |
656 JSON::DWIW | 68534.379 | 79437.576 | 805 JSON::DWIW | 51653.990 | 71575.154 |
657 JSON::PC | 65948.176 | 78251.940 | 806 JSON::PC | 65948.176 | 74631.744 |
658 JSON::Syck | 23379.621 | 28416.694 | 807 JSON::PP | 8931.652 | 3817.168 |
808 JSON::Syck | 24877.248 | 27776.848 |
659 JSON::XS | 388361.481 | 199728.762 | 809 JSON::XS | 388361.481 | 227951.304 |
660 JSON::XS/2 | 218453.333 | 192399.266 | 810 JSON::XS/2 | 227951.304 | 218453.333 |
661 JSON::XS/3 | 338250.323 | 192399.266 | 811 JSON::XS/3 | 338250.323 | 218453.333 |
662 Storable | 15732.573 | 28571.553 | 812 Storable | 16500.016 | 135300.129 |
663 -----------+------------+------------+ 813 -----------+------------+------------+
664 814
665That is, JSON::XS is about five times faster than JSON::DWIW on encoding, 815That is, JSON::XS is about five times faster than JSON::DWIW on encoding,
666about three times faster on decoding, and over fourty times faster 816about three times faster on decoding, and over fourty times faster
667than JSON, even with pretty-printing and key sorting. It also compares 817than JSON, even with pretty-printing and key sorting. It also compares
… …
670Using a longer test string (roughly 18KB, generated from Yahoo! Locals 820Using a longer test string (roughly 18KB, generated from Yahoo! Locals
671search API (http://nanoref.com/yahooapis/mgPdGg): 821search API (http://nanoref.com/yahooapis/mgPdGg):
672 822
673 module | encode | decode | 823 module | encode | decode |
674 -----------|------------|------------| 824 -----------|------------|------------|
675 JSON | 254.685 | 37.665 | 825 JSON | 55.260 | 34.971 |
676 JSON::DWIW | 1014.244 | 1087.678 | 826 JSON::DWIW | 825.228 | 1082.513 |
677 JSON::PC | 3602.116 | 2307.352 | 827 JSON::PC | 3571.444 | 2394.829 |
678 JSON::Syck | 558.035 | 776.263 | 828 JSON::PP | 210.987 | 32.574 |
679 JSON::XS | 5747.196 | 3543.684 | 829 JSON::Syck | 552.551 | 787.544 |
680 JSON::XS/2 | 3968.121 | 3589.170 | 830 JSON::XS | 5780.463 | 4854.519 |
681 JSON::XS/3 | 6105.246 | 3561.134 | 831 JSON::XS/2 | 3869.998 | 4798.975 |
682 Storable | 4456.337 | 5320.020 | 832 JSON::XS/3 | 5862.880 | 4798.975 |
833 Storable | 4445.002 | 5235.027 |
683 -----------+------------+------------+ 834 -----------+------------+------------+
684 835
685Again, JSON::XS leads by far. 836Again, JSON::XS leads by far (except for Storable which non-surprisingly
837decodes faster).
686 838
687On large strings containing lots of high unicode characters, some modules 839On large strings containing lots of high unicode characters, some modules
688(such as JSON::PC) seem to decode faster than JSON::XS, but the result 840(such as JSON::PC) seem to decode faster than JSON::XS, but the result
689will be broken due to missing (or wrong) unicode handling. Others refuse 841will be broken due to missing (or wrong) unicode handling. Others refuse
690to decode or encode properly, so it was impossible to prepare a fair 842to decode or encode properly, so it was impossible to prepare a fair
… …
703Second, you need to avoid resource-starving attacks. That means you should 855Second, you need to avoid resource-starving attacks. That means you should
704limit the size of JSON texts you accept, or make sure then when your 856limit the size of JSON texts you accept, or make sure then when your
705resources run out, thats just fine (e.g. by using a separate process that 857resources run out, thats just fine (e.g. by using a separate process that
706can crash safely). The size of a JSON text in octets or characters is 858can crash safely). The size of a JSON text in octets or characters is
707usually a good indication of the size of the resources required to decode 859usually a good indication of the size of the resources required to decode
708it into a Perl structure. 860it into a Perl structure. While JSON::XS can check the size of the JSON
861text, it might be too late when you already have it in memory, so you
862might want to check the size before you accept the string.
709 863
710Third, JSON::XS recurses using the C stack when decoding objects and 864Third, JSON::XS recurses using the C stack when decoding objects and
711arrays. The C stack is a limited resource: for instance, on my amd64 865arrays. The C stack is a limited resource: for instance, on my amd64
712machine with 8MB of stack size I can decode around 180k nested arrays but 866machine with 8MB of stack size I can decode around 180k nested arrays but
713only 14k nested JSON objects (due to perl itself recursing deeply on croak 867only 14k nested JSON objects (due to perl itself recursing deeply on croak
… …
718 872
719And last but least, something else could bomb you that I forgot to think 873And last but least, something else could bomb you that I forgot to think
720of. In that case, you get to keep the pieces. I am always open for hints, 874of. In that case, you get to keep the pieces. I am always open for hints,
721though... 875though...
722 876
877If you are using JSON::XS to return packets to consumption
878by javascript scripts in a browser you should have a look at
879L<http://jpsykes.com/47/practical-csrf-and-json-security> to see wether
880you are vulnerable to some common attack vectors (which really are browser
881design bugs, but it is still you who will have to deal with it, as major
882browser developers care only for features, not about doing security
883right).
884
723 885
724=head1 BUGS 886=head1 BUGS
725 887
726While the goal of this module is to be correct, that unfortunately does 888While the goal of this module is to be correct, that unfortunately does
727not mean its bug-free, only that I think its design is bug-free. It is 889not mean its bug-free, only that I think its design is bug-free. It is
728still relatively early in its development. If you keep reporting bugs they 890still relatively early in its development. If you keep reporting bugs they
729will be fixed swiftly, though. 891will be fixed swiftly, though.
730 892
731=cut 893=cut
732 894
895our $true = do { bless \(my $dummy = 1), "JSON::XS::Boolean" };
896our $false = do { bless \(my $dummy = 0), "JSON::XS::Boolean" };
897
733sub true() { \1 } 898sub true() { $true }
734sub false() { \0 } 899sub false() { $false }
900
901sub is_bool($) {
902 UNIVERSAL::isa $_[0], "JSON::XS::Boolean"
903# or UNIVERSAL::isa $_[0], "JSON::Literal"
904}
905
906XSLoader::load "JSON::XS", $VERSION;
907
908package JSON::XS::Boolean;
909
910use overload
911 "0+" => sub { ${$_[0]} },
912 "++" => sub { $_[0] = ${$_[0]} + 1 },
913 "--" => sub { $_[0] = ${$_[0]} - 1 },
914 fallback => 1;
735 915
7361; 9161;
737 917
738=head1 AUTHOR 918=head1 AUTHOR
739 919

Diff Legend

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