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.40 by root, Mon Jun 11 03:42:57 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);
… …
85 81
86package JSON::XS; 82package JSON::XS;
87 83
88use strict; 84use strict;
89 85
90BEGIN {
91 our $VERSION = '1.24'; 86our $VERSION = '1.4';
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])
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 }
314 425
315=item $json = $json->shrink ([$enable]) 426=item $json = $json->shrink ([$enable])
316 427
317Perl usually over-allocates memory a bit when allocating space for 428Perl usually over-allocates memory a bit when allocating space for
318strings. This flag optionally resizes strings generated by either 429strings. This flag optionally resizes strings generated by either
… …
351given character in a string. 462given character in a string.
352 463
353Setting the maximum depth to one disallows any nesting, so that ensures 464Setting the maximum depth to one disallows any nesting, so that ensures
354that the object is only a single hash/object or array. 465that the object is only a single hash/object or array.
355 466
356The 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
357of 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).
358 484
359See SECURITY CONSIDERATIONS, below, for more info on why this is useful. 485See SECURITY CONSIDERATIONS, below, for more info on why this is useful.
360 486
361=item $json_text = $json->encode ($perl_scalar) 487=item $json_text = $json->encode ($perl_scalar)
362 488
… …
432conversion details, but an integer may take slightly less memory and might 558conversion details, but an integer may take slightly less memory and might
433represent more values exactly than (floating point) numbers. 559represent more values exactly than (floating point) numbers.
434 560
435=item true, false 561=item true, false
436 562
437These JSON atoms become C<0>, C<1>, respectively. Information is lost in 563These JSON atoms become C<JSON::XS::true> and C<JSON::XS::false>,
438this process. Future versions might represent those values differently, 564respectively. They are overloaded to act almost exactly like the numbers
439but they will be guarenteed to act like these integers would normally in 565C<1> and C<0>. You can check wether a scalar is a JSON boolean by using
440Perl. 566the C<JSON::XS::is_bool> function.
441 567
442=item null 568=item null
443 569
444A JSON null atom becomes C<undef> in Perl. 570A JSON null atom becomes C<undef> in Perl.
445 571
… …
477C<1>, which get turned into C<false> and C<true> atoms in JSON. You can 603C<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. 604also use C<JSON::XS::false> and C<JSON::XS::true> to improve readability.
479 605
480 to_json [\0,JSON::XS::true] # yields [false,true] 606 to_json [\0,JSON::XS::true] # yields [false,true]
481 607
608=item JSON::XS::true, JSON::XS::false
609
610These special values become JSON true and JSON false values,
611respectively. You cna alos use C<\1> and C<\0> directly if you want.
612
482=item blessed objects 613=item blessed objects
483 614
484Blessed objects are not allowed. JSON::XS currently tries to encode their 615Blessed objects are not allowed. JSON::XS currently tries to encode their
485underlying representation (hash- or arrayref), but this behaviour might 616underlying representation (hash- or arrayref), but this behaviour might
486change in future versions. 617change in future versions.
… …
614 745
615You often hear that JSON is a subset (or a close subset) of YAML. This is, 746You 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 747however, 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. 748no way to configure JSON::XS to output a data structure as valid YAML.
618 749
619If you really must use JSON::XS to generate YAML, you should this 750If you really must use JSON::XS to generate YAML, you should use this
620algorithm (subject to change in future versions): 751algorithm (subject to change in future versions):
621 752
622 my $to_yaml = JSON::XS->new->utf8->space_after (1); 753 my $to_yaml = JSON::XS->new->utf8->space_after (1);
623 my $yaml = $to_yaml->encode ($ref) . "\n"; 754 my $yaml = $to_yaml->encode ($ref) . "\n";
624 755
625This will usually generate JSON texts that also parse as valid 756This will usually generate JSON texts that also parse as valid
626YAML. Please note that YAML has hardcoded limits on object key lengths 757YAML. 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 758lengths that JSON doesn't have, so you should make sure that your hash
628noticably shorter than 1024 characters. 759keys are noticably shorter than the 1024 characters YAML allows.
629 760
630There might be other incompatibilities that I am not aware of. In general 761There 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, 762you 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. 763or try to parse JSON with a YAML parser or vice versa: chances are high
764that you will run into severe interoperability problems.
633 765
634 766
635=head2 SPEED 767=head2 SPEED
636 768
637It seems that JSON::XS is surprisingly fast, as shown in the following 769It seems that JSON::XS is surprisingly fast, as shown in the following
… …
648It shows the number of encodes/decodes per second (JSON::XS uses 780It shows the number of encodes/decodes per second (JSON::XS uses
649the functional interface, while JSON::XS/2 uses the OO interface 781the functional interface, while JSON::XS/2 uses the OO interface
650with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables 782with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables
651shrink). Higher is better: 783shrink). Higher is better:
652 784
785 Storable | 15779.925 | 14169.946 |
786 -----------+------------+------------+
653 module | encode | decode | 787 module | encode | decode |
654 -----------|------------|------------| 788 -----------|------------|------------|
655 JSON | 7645.468 | 4208.613 | 789 JSON | 4990.842 | 4088.813 |
656 JSON::DWIW | 40721.398 | 77101.176 | 790 JSON::DWIW | 51653.990 | 71575.154 |
657 JSON::PC | 65948.176 | 78251.940 | 791 JSON::PC | 65948.176 | 74631.744 |
658 JSON::Syck | 22844.793 | 26479.192 | 792 JSON::PP | 8931.652 | 3817.168 |
793 JSON::Syck | 24877.248 | 27776.848 |
659 JSON::XS | 388361.481 | 199728.762 | 794 JSON::XS | 388361.481 | 227951.304 |
660 JSON::XS/2 | 218453.333 | 192399.266 | 795 JSON::XS/2 | 227951.304 | 218453.333 |
661 JSON::XS/3 | 338250.323 | 192399.266 | 796 JSON::XS/3 | 338250.323 | 218453.333 |
662 Storable | 15779.925 | 14169.946 | 797 Storable | 16500.016 | 135300.129 |
663 -----------+------------+------------+ 798 -----------+------------+------------+
664 799
665That 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,
666about three times faster on decoding, and over fourty times faster 801about three times faster on decoding, and over fourty times faster
667than JSON, even with pretty-printing and key sorting. It also compares 802than JSON, even with pretty-printing and key sorting. It also compares
… …
670Using a longer test string (roughly 18KB, generated from Yahoo! Locals 805Using a longer test string (roughly 18KB, generated from Yahoo! Locals
671search API (http://nanoref.com/yahooapis/mgPdGg): 806search API (http://nanoref.com/yahooapis/mgPdGg):
672 807
673 module | encode | decode | 808 module | encode | decode |
674 -----------|------------|------------| 809 -----------|------------|------------|
675 JSON | 254.685 | 37.665 | 810 JSON | 55.260 | 34.971 |
676 JSON::DWIW | 843.343 | 1049.731 | 811 JSON::DWIW | 825.228 | 1082.513 |
677 JSON::PC | 3602.116 | 2307.352 | 812 JSON::PC | 3571.444 | 2394.829 |
813 JSON::PP | 210.987 | 32.574 |
678 JSON::Syck | 505.107 | 787.899 | 814 JSON::Syck | 552.551 | 787.544 |
679 JSON::XS | 5747.196 | 3690.220 | 815 JSON::XS | 5780.463 | 4854.519 |
680 JSON::XS/2 | 3968.121 | 3676.634 | 816 JSON::XS/2 | 3869.998 | 4798.975 |
681 JSON::XS/3 | 6105.246 | 3662.508 | 817 JSON::XS/3 | 5862.880 | 4798.975 |
682 Storable | 4417.337 | 5285.161 | 818 Storable | 4445.002 | 5235.027 |
683 -----------+------------+------------+ 819 -----------+------------+------------+
684 820
685Again, JSON::XS leads by far (except for Storable which non-surprisingly 821Again, JSON::XS leads by far (except for Storable which non-surprisingly
686decodes faster). 822decodes faster).
687 823
… …
704Second, you need to avoid resource-starving attacks. That means you should 840Second, you need to avoid resource-starving attacks. That means you should
705limit 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
706resources 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
707can 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
708usually 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
709it 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.
710 848
711Third, JSON::XS recurses using the C stack when decoding objects and 849Third, JSON::XS recurses using the C stack when decoding objects and
712arrays. 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
713machine 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
714only 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
… …
719 857
720And last but least, something else could bomb you that I forgot to think 858And last but least, something else could bomb you that I forgot to think
721of. In that case, you get to keep the pieces. I am always open for hints, 859of. In that case, you get to keep the pieces. I am always open for hints,
722though... 860though...
723 861
862If you are using JSON::XS to return packets to consumption
863by javascript scripts in a browser you should have a look at
864L<http://jpsykes.com/47/practical-csrf-and-json-security> to see wether
865you are vulnerable to some common attack vectors (which really are browser
866design bugs, but it is still you who will have to deal with it, as major
867browser developers care only for features, not about doing security
868right).
869
724 870
725=head1 BUGS 871=head1 BUGS
726 872
727While the goal of this module is to be correct, that unfortunately does 873While the goal of this module is to be correct, that unfortunately does
728not mean its bug-free, only that I think its design is bug-free. It is 874not mean its bug-free, only that I think its design is bug-free. It is
729still relatively early in its development. If you keep reporting bugs they 875still relatively early in its development. If you keep reporting bugs they
730will be fixed swiftly, though. 876will be fixed swiftly, though.
731 877
732=cut 878=cut
733 879
880our $true = do { bless \(my $dummy = "1"), "JSON::XS::Boolean" };
881our $false = do { bless \(my $dummy = "0"), "JSON::XS::Boolean" };
882
734sub true() { \1 } 883sub true() { $true }
735sub false() { \0 } 884sub false() { $false }
885
886sub is_bool($) {
887 UNIVERSAL::isa $_[0], "JSON::XS::Boolean"
888# or UNIVERSAL::isa $_[0], "JSON::Literal"
889}
890
891XSLoader::load "JSON::XS", $VERSION;
892
893package JSON::XS::Boolean;
894
895use overload
896 "0+" => sub { ${$_[0]} },
897 "++" => sub { $_[0] = ${$_[0]} + 1 },
898 "--" => sub { $_[0] = ${$_[0]} - 1 },
899 fallback => 1;
736 900
7371; 9011;
738 902
739=head1 AUTHOR 903=head1 AUTHOR
740 904

Diff Legend

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