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.32 by root, Thu Apr 12 07:25:29 2007 UTC vs.
Revision 1.48 by root, Mon Jun 25 22:11:39 2007 UTC

… …
85 85
86package JSON::XS; 86package JSON::XS;
87 87
88use strict; 88use strict;
89 89
90BEGIN {
91 our $VERSION = '1.12'; 90our $VERSION = '1.4';
92 our @ISA = qw(Exporter); 91our @ISA = qw(Exporter);
93 92
94 our @EXPORT = qw(to_json from_json objToJson jsonToObj); 93our @EXPORT = qw(to_json from_json objToJson jsonToObj);
95 require Exporter;
96 94
97 require XSLoader; 95use Exporter;
98 XSLoader::load JSON::XS::, $VERSION; 96use XSLoader;
99}
100 97
101=head1 FUNCTIONAL INTERFACE 98=head1 FUNCTIONAL INTERFACE
102 99
103The following convinience methods are provided by this module. They are 100The following convinience methods are provided by this module. They are
104exported by default: 101exported by default:
… …
126This function call is functionally identical to: 123This function call is functionally identical to:
127 124
128 $perl_scalar = JSON::XS->new->utf8->decode ($json_text) 125 $perl_scalar = JSON::XS->new->utf8->decode ($json_text)
129 126
130except being faster. 127except being faster.
128
129=item $is_boolean = JSON::XS::is_bool $scalar
130
131Returns true if the passed scalar represents either JSON::XS::true or
132JSON::XS::false, two constants that act like C<1> and C<0>, respectively
133and are used to represent JSON C<true> and C<false> values in Perl.
134
135See MAPPING, below, for more information on how JSON values are mapped to
136Perl.
131 137
132=back 138=back
133 139
134 140
135=head1 OBJECT-ORIENTED INTERFACE 141=head1 OBJECT-ORIENTED INTERFACE
… …
159as per RFC4627. The resulting encoded JSON text can be treated as a native 165as per RFC4627. The resulting encoded JSON text can be treated as a native
160unicode string, an ascii-encoded, latin1-encoded or UTF-8 encoded string, 166unicode string, an ascii-encoded, latin1-encoded or UTF-8 encoded string,
161or any other superset of ASCII. 167or any other superset of ASCII.
162 168
163If C<$enable> is false, then the C<encode> method will not escape Unicode 169If C<$enable> is false, then the C<encode> method will not escape Unicode
164characters unless required by the JSON syntax. This results in a faster 170characters unless required by the JSON syntax or other flags. This results
165and more compact format. 171in a faster and more compact format.
172
173The main use for this flag is to produce JSON texts that can be
174transmitted over a 7-bit channel, as the encoded JSON texts will not
175contain any 8 bit characters.
166 176
167 JSON::XS->new->ascii (1)->encode ([chr 0x10401]) 177 JSON::XS->new->ascii (1)->encode ([chr 0x10401])
168 => ["\ud801\udc01"] 178 => ["\ud801\udc01"]
179
180=item $json = $json->latin1 ([$enable])
181
182If C<$enable> is true (or missing), then the C<encode> method will encode
183the resulting JSON text as latin1 (or iso-8859-1), escaping any characters
184outside the code range C<0..255>. The resulting string can be treated as a
185latin1-encoded JSON text or a native unicode string. The C<decode> method
186will not be affected in any way by this flag, as C<decode> by default
187expects unicode, which is a strict superset of latin1.
188
189If C<$enable> is false, then the C<encode> method will not escape Unicode
190characters unless required by the JSON syntax or other flags.
191
192The main use for this flag is efficiently encoding binary data as JSON
193text, as most octets will not be escaped, resulting in a smaller encoded
194size. The disadvantage is that the resulting JSON text is encoded
195in latin1 (and must correctly be treated as such when storing and
196transfering), a rare encoding for JSON. It is therefore most useful when
197you want to store data structures known to contain binary data efficiently
198in files or databases, not when talking to other JSON encoders/decoders.
199
200 JSON::XS->new->latin1->encode (["\x{89}\x{abc}"]
201 => ["\x{89}\\u0abc"] # (perl syntax, U+abc escaped, U+89 not)
169 202
170=item $json = $json->utf8 ([$enable]) 203=item $json = $json->utf8 ([$enable])
171 204
172If C<$enable> is true (or missing), then the C<encode> method will encode 205If C<$enable> is true (or missing), then the C<encode> method will encode
173the JSON result into UTF-8, as required by many protocols, while the 206the JSON result into UTF-8, as required by many protocols, while the
… …
282Example, encode a Perl scalar as JSON value with enabled C<allow_nonref>, 315Example, encode a Perl scalar as JSON value with enabled C<allow_nonref>,
283resulting in an invalid JSON text: 316resulting in an invalid JSON text:
284 317
285 JSON::XS->new->allow_nonref->encode ("Hello, World!") 318 JSON::XS->new->allow_nonref->encode ("Hello, World!")
286 => "Hello, World!" 319 => "Hello, World!"
320
321=item $json = $json->allow_blessed ([$enable])
322
323If C<$enable> is true (or missing), then the C<encode> method will not
324barf when it encounters a blessed reference. Instead, the value of the
325B<convert_blessed> option will decide wether C<null> (C<convert_blessed>
326disabled or no C<to_json> method found) or a representation of the
327object (C<convert_blessed> enabled and C<to_json> method found) is being
328encoded. Has no effect on C<decode>.
329
330If C<$enable> is false (the default), then C<encode> will throw an
331exception when it encounters a blessed object.
332
333=item $json = $json->convert_blessed ([$enable])
334
335If C<$enable> is true (or missing), then C<encode>, upon encountering a
336blessed object, will check for the availability of the C<TO_JSON> method
337on the object's class. If found, it will be called in scalar context
338and the resulting scalar will be encoded instead of the object. If no
339C<TO_JSON> method is found, the value of C<allow_blessed> will decide what
340to do.
341
342The 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
344way. 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
346methods 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>
348function.
349
350This setting does not yet influence C<decode> in any way, but in the
351future, global hooks might get installed that influence C<decode> and are
352enabled by this setting.
353
354If C<$enable> is false, then the C<allow_blessed> setting will decide what
355to do when a blessed object is found.
287 356
288=item $json = $json->shrink ([$enable]) 357=item $json = $json->shrink ([$enable])
289 358
290Perl usually over-allocates memory a bit when allocating space for 359Perl usually over-allocates memory a bit when allocating space for
291strings. This flag optionally resizes strings generated by either 360strings. This flag optionally resizes strings generated by either
… …
324given character in a string. 393given character in a string.
325 394
326Setting the maximum depth to one disallows any nesting, so that ensures 395Setting the maximum depth to one disallows any nesting, so that ensures
327that the object is only a single hash/object or array. 396that the object is only a single hash/object or array.
328 397
329The argument to C<max_depth> will be rounded up to the next nearest power 398The argument to C<max_depth> will be rounded up to the next highest power
330of two. 399of two. If no argument is given, the highest possible setting will be
400used, which is rarely useful.
401
402See SECURITY CONSIDERATIONS, below, for more info on why this is useful.
403
404=item $json = $json->max_size ([$maximum_string_size])
405
406Set the maximum length a JSON text may have (in bytes) where decoding is
407being attempted. The default is C<0>, meaning no limit. When C<decode>
408is called on a string longer then this number of characters it will not
409attempt to decode the string but throw an exception. This setting has no
410effect on C<encode> (yet).
411
412The argument to C<max_size> will be rounded up to the next B<highest>
413power of two (so may be more than requested). If no argument is given, the
414limit check will be deactivated (same as when C<0> is specified).
331 415
332See SECURITY CONSIDERATIONS, below, for more info on why this is useful. 416See SECURITY CONSIDERATIONS, below, for more info on why this is useful.
333 417
334=item $json_text = $json->encode ($perl_scalar) 418=item $json_text = $json->encode ($perl_scalar)
335 419
… …
347 431
348JSON numbers and strings become simple Perl scalars. JSON arrays become 432JSON numbers and strings become simple Perl scalars. JSON arrays become
349Perl arrayrefs and JSON objects become Perl hashrefs. C<true> becomes 433Perl arrayrefs and JSON objects become Perl hashrefs. C<true> becomes
350C<1>, C<false> becomes C<0> and C<null> becomes C<undef>. 434C<1>, C<false> becomes C<0> and C<null> becomes C<undef>.
351 435
436=item ($perl_scalar, $characters) = $json->decode_prefix ($json_text)
437
438This works like the C<decode> method, but instead of raising an exception
439when there is trailing garbage after the first JSON object, it will
440silently stop parsing there and return the number of characters consumed
441so far.
442
443This is useful if your JSON texts are not delimited by an outer protocol
444(which is not the brightest thing to do in the first place) and you need
445to know where the JSON text ends.
446
447 JSON::XS->new->decode_prefix ("[1] the tail")
448 => ([], 3)
449
352=back 450=back
353 451
354 452
355=head1 MAPPING 453=head1 MAPPING
356 454
… …
360(what you put in comes out as something equivalent). 458(what you put in comes out as something equivalent).
361 459
362For the more enlightened: note that in the following descriptions, 460For the more enlightened: note that in the following descriptions,
363lowercase I<perl> refers to the Perl interpreter, while uppcercase I<Perl> 461lowercase I<perl> refers to the Perl interpreter, while uppcercase I<Perl>
364refers to the abstract Perl language itself. 462refers to the abstract Perl language itself.
463
365 464
366=head2 JSON -> PERL 465=head2 JSON -> PERL
367 466
368=over 4 467=over 4
369 468
… …
390conversion details, but an integer may take slightly less memory and might 489conversion details, but an integer may take slightly less memory and might
391represent more values exactly than (floating point) numbers. 490represent more values exactly than (floating point) numbers.
392 491
393=item true, false 492=item true, false
394 493
395These JSON atoms become C<0>, C<1>, respectively. Information is lost in 494These JSON atoms become C<JSON::XS::true> and C<JSON::XS::false>,
396this process. Future versions might represent those values differently, 495respectively. They are overloaded to act almost exactly like the numbers
397but they will be guarenteed to act like these integers would normally in 496C<1> and C<0>. You can check wether a scalar is a JSON boolean by using
398Perl. 497the C<JSON::XS::is_bool> function.
399 498
400=item null 499=item null
401 500
402A JSON null atom becomes C<undef> in Perl. 501A JSON null atom becomes C<undef> in Perl.
403 502
404=back 503=back
504
405 505
406=head2 PERL -> JSON 506=head2 PERL -> JSON
407 507
408The mapping from Perl to JSON is slightly more difficult, as Perl is a 508The mapping from Perl to JSON is slightly more difficult, as Perl is a
409truly typeless language, so we can only guess which JSON type is meant by 509truly typeless language, so we can only guess which JSON type is meant by
… …
434C<1>, which get turned into C<false> and C<true> atoms in JSON. You can 534C<1>, which get turned into C<false> and C<true> atoms in JSON. You can
435also use C<JSON::XS::false> and C<JSON::XS::true> to improve readability. 535also use C<JSON::XS::false> and C<JSON::XS::true> to improve readability.
436 536
437 to_json [\0,JSON::XS::true] # yields [false,true] 537 to_json [\0,JSON::XS::true] # yields [false,true]
438 538
539=item JSON::XS::true, JSON::XS::false
540
541These special values become JSON true and JSON false values,
542respectively. You cna alos use C<\1> and C<\0> directly if you want.
543
439=item blessed objects 544=item blessed objects
440 545
441Blessed objects are not allowed. JSON::XS currently tries to encode their 546Blessed objects are not allowed. JSON::XS currently tries to encode their
442underlying representation (hash- or arrayref), but this behaviour might 547underlying representation (hash- or arrayref), but this behaviour might
443change in future versions. 548change in future versions.
… …
564 669
565Does not check input for validity. 670Does not check input for validity.
566 671
567=back 672=back
568 673
674
675=head2 JSON and YAML
676
677You often hear that JSON is a subset (or a close subset) of YAML. This is,
678however, a mass hysteria and very far from the truth. In general, there is
679no way to configure JSON::XS to output a data structure as valid YAML.
680
681If you really must use JSON::XS to generate YAML, you should use this
682algorithm (subject to change in future versions):
683
684 my $to_yaml = JSON::XS->new->utf8->space_after (1);
685 my $yaml = $to_yaml->encode ($ref) . "\n";
686
687This will usually generate JSON texts that also parse as valid
688YAML. Please note that YAML has hardcoded limits on (simple) object key
689lengths that JSON doesn't have, so you should make sure that your hash
690keys are noticably shorter than the 1024 characters YAML allows.
691
692There might be other incompatibilities that I am not aware of. In general
693you should not try to generate YAML with a JSON generator or vice versa,
694or try to parse JSON with a YAML parser or vice versa: chances are high
695that you will run into severe interoperability problems.
696
697
569=head2 SPEED 698=head2 SPEED
570 699
571It seems that JSON::XS is surprisingly fast, as shown in the following 700It seems that JSON::XS is surprisingly fast, as shown in the following
572tables. They have been generated with the help of the C<eg/bench> program 701tables. They have been generated with the help of the C<eg/bench> program
573in the JSON::XS distribution, to make it easy to compare on your own 702in the JSON::XS distribution, to make it easy to compare on your own
574system. 703system.
575 704
576First comes a comparison between various modules using a very short JSON 705First comes a comparison between various modules using a very short
577string: 706single-line JSON string:
578 707
579 {"method": "handleMessage", "params": ["user1", "we were just talking"], "id": null} 708 {"method": "handleMessage", "params": ["user1", "we were just talking"], \
709 "id": null, "array":[1,11,234,-5,1e5,1e7, true, false]}
580 710
581It shows the number of encodes/decodes per second (JSON::XS uses the 711It shows the number of encodes/decodes per second (JSON::XS uses
582functional interface, while JSON::XS/2 uses the OO interface with 712the functional interface, while JSON::XS/2 uses the OO interface
583pretty-printing and hashkey sorting enabled). Higher is better: 713with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables
714shrink). Higher is better:
584 715
716 Storable | 15779.925 | 14169.946 |
717 -----------+------------+------------+
585 module | encode | decode | 718 module | encode | decode |
586 -----------|------------|------------| 719 -----------|------------|------------|
587 JSON | 11488.516 | 7823.035 | 720 JSON | 4990.842 | 4088.813 |
588 JSON::DWIW | 94708.054 | 129094.260 | 721 JSON::DWIW | 51653.990 | 71575.154 |
589 JSON::PC | 63884.157 | 128528.212 | 722 JSON::PC | 65948.176 | 74631.744 |
590 JSON::Syck | 34898.677 | 42096.911 | 723 JSON::PP | 8931.652 | 3817.168 |
591 JSON::XS | 654027.064 | 396423.669 | 724 JSON::Syck | 24877.248 | 27776.848 |
592 JSON::XS/2 | 371564.190 | 371725.613 | 725 JSON::XS | 388361.481 | 227951.304 |
726 JSON::XS/2 | 227951.304 | 218453.333 |
727 JSON::XS/3 | 338250.323 | 218453.333 |
728 Storable | 16500.016 | 135300.129 |
593 -----------+------------+------------+ 729 -----------+------------+------------+
594 730
595That is, JSON::XS is more than six times faster than JSON::DWIW on 731That is, JSON::XS is about five times faster than JSON::DWIW on encoding,
596encoding, more than three times faster on decoding, and about thirty times 732about three times faster on decoding, and over fourty times faster
597faster than JSON, even with pretty-printing and key sorting. 733than JSON, even with pretty-printing and key sorting. It also compares
734favourably to Storable for small amounts of data.
598 735
599Using a longer test string (roughly 18KB, generated from Yahoo! Locals 736Using a longer test string (roughly 18KB, generated from Yahoo! Locals
600search API (http://nanoref.com/yahooapis/mgPdGg): 737search API (http://nanoref.com/yahooapis/mgPdGg):
601 738
602 module | encode | decode | 739 module | encode | decode |
603 -----------|------------|------------| 740 -----------|------------|------------|
604 JSON | 273.023 | 44.674 | 741 JSON | 55.260 | 34.971 |
605 JSON::DWIW | 1089.383 | 1145.704 | 742 JSON::DWIW | 825.228 | 1082.513 |
606 JSON::PC | 3097.419 | 2393.921 | 743 JSON::PC | 3571.444 | 2394.829 |
607 JSON::Syck | 514.060 | 843.053 | 744 JSON::PP | 210.987 | 32.574 |
608 JSON::XS | 6479.668 | 3636.364 | 745 JSON::Syck | 552.551 | 787.544 |
609 JSON::XS/2 | 3774.221 | 3599.124 | 746 JSON::XS | 5780.463 | 4854.519 |
747 JSON::XS/2 | 3869.998 | 4798.975 |
748 JSON::XS/3 | 5862.880 | 4798.975 |
749 Storable | 4445.002 | 5235.027 |
610 -----------+------------+------------+ 750 -----------+------------+------------+
611 751
612Again, JSON::XS leads by far. 752Again, JSON::XS leads by far (except for Storable which non-surprisingly
753decodes faster).
613 754
614On large strings containing lots of high unicode characters, some modules 755On large strings containing lots of high unicode characters, some modules
615(such as JSON::PC) seem to decode faster than JSON::XS, but the result 756(such as JSON::PC) seem to decode faster than JSON::XS, but the result
616will be broken due to missing (or wrong) unicode handling. Others refuse 757will be broken due to missing (or wrong) unicode handling. Others refuse
617to decode or encode properly, so it was impossible to prepare a fair 758to decode or encode properly, so it was impossible to prepare a fair
… …
630Second, you need to avoid resource-starving attacks. That means you should 771Second, you need to avoid resource-starving attacks. That means you should
631limit the size of JSON texts you accept, or make sure then when your 772limit the size of JSON texts you accept, or make sure then when your
632resources run out, thats just fine (e.g. by using a separate process that 773resources run out, thats just fine (e.g. by using a separate process that
633can crash safely). The size of a JSON text in octets or characters is 774can crash safely). The size of a JSON text in octets or characters is
634usually a good indication of the size of the resources required to decode 775usually a good indication of the size of the resources required to decode
635it into a Perl structure. 776it into a Perl structure. While JSON::XS can check the size of the JSON
777text, it might be too late when you already have it in memory, so you
778might want to check the size before you accept the string.
636 779
637Third, JSON::XS recurses using the C stack when decoding objects and 780Third, JSON::XS recurses using the C stack when decoding objects and
638arrays. The C stack is a limited resource: for instance, on my amd64 781arrays. The C stack is a limited resource: for instance, on my amd64
639machine with 8MB of stack size I can decode around 180k nested arrays but 782machine with 8MB of stack size I can decode around 180k nested arrays but
640only 14k nested JSON objects (due to perl itself recursing deeply on croak 783only 14k nested JSON objects (due to perl itself recursing deeply on croak
… …
645 788
646And last but least, something else could bomb you that I forgot to think 789And last but least, something else could bomb you that I forgot to think
647of. In that case, you get to keep the pieces. I am always open for hints, 790of. In that case, you get to keep the pieces. I am always open for hints,
648though... 791though...
649 792
793If you are using JSON::XS to return packets to consumption
794by javascript scripts in a browser you should have a look at
795L<http://jpsykes.com/47/practical-csrf-and-json-security> to see wether
796you are vulnerable to some common attack vectors (which really are browser
797design bugs, but it is still you who will have to deal with it, as major
798browser developers care only for features, not about doing security
799right).
800
650 801
651=head1 BUGS 802=head1 BUGS
652 803
653While the goal of this module is to be correct, that unfortunately does 804While the goal of this module is to be correct, that unfortunately does
654not mean its bug-free, only that I think its design is bug-free. It is 805not mean its bug-free, only that I think its design is bug-free. It is
655still relatively early in its development. If you keep reporting bugs they 806still relatively early in its development. If you keep reporting bugs they
656will be fixed swiftly, though. 807will be fixed swiftly, though.
657 808
658=cut 809=cut
659 810
811our $true = do { bless \(my $dummy = 1), "JSON::XS::Boolean" };
812our $false = do { bless \(my $dummy = 0), "JSON::XS::Boolean" };
813
660sub true() { \1 } 814sub true() { $true }
661sub false() { \0 } 815sub false() { $false }
816
817sub is_bool($) {
818 UNIVERSAL::isa $_[0], "JSON::XS::Boolean"
819# or UNIVERSAL::isa $_[0], "JSON::Literal"
820}
821
822XSLoader::load "JSON::XS", $VERSION;
823
824package JSON::XS::Boolean;
825
826use overload
827 "0+" => sub { ${$_[0]} },
828 "++" => sub { $_[0] = ${$_[0]} + 1 },
829 "--" => sub { $_[0] = ${$_[0]} - 1 },
830 fallback => 1;
662 831
6631; 8321;
664 833
665=head1 AUTHOR 834=head1 AUTHOR
666 835

Diff Legend

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