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.25 by root, Thu Mar 29 02:45:49 2007 UTC vs.
Revision 1.50 by root, Mon Jul 2 00:29:38 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.0'; 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
… …
154 156
155If C<$enable> is true (or missing), then the C<encode> method will not 157If C<$enable> is true (or missing), then the C<encode> method will not
156generate characters outside the code range C<0..127> (which is ASCII). Any 158generate characters outside the code range C<0..127> (which is ASCII). Any
157unicode characters outside that range will be escaped using either a 159unicode characters outside that range will be escaped using either a
158single \uXXXX (BMP characters) or a double \uHHHH\uLLLLL escape sequence, 160single \uXXXX (BMP characters) or a double \uHHHH\uLLLLL escape sequence,
159as per RFC4627. 161as per RFC4627. The resulting encoded JSON text can be treated as a native
162unicode string, an ascii-encoded, latin1-encoded or UTF-8 encoded string,
163or any other superset of ASCII.
160 164
161If C<$enable> is false, then the C<encode> method will not escape Unicode 165If C<$enable> is false, then the C<encode> method will not escape Unicode
162characters unless required by the JSON syntax. This results in a faster 166characters unless required by the JSON syntax or other flags. This results
163and more compact format. 167in a faster and more compact format.
168
169The main use for this flag is to produce JSON texts that can be
170transmitted over a 7-bit channel, as the encoded JSON texts will not
171contain any 8 bit characters.
164 172
165 JSON::XS->new->ascii (1)->encode ([chr 0x10401]) 173 JSON::XS->new->ascii (1)->encode ([chr 0x10401])
166 => ["\ud801\udc01"] 174 => ["\ud801\udc01"]
175
176=item $json = $json->latin1 ([$enable])
177
178If C<$enable> is true (or missing), then the C<encode> method will encode
179the resulting JSON text as latin1 (or iso-8859-1), escaping any characters
180outside the code range C<0..255>. The resulting string can be treated as a
181latin1-encoded JSON text or a native unicode string. The C<decode> method
182will not be affected in any way by this flag, as C<decode> by default
183expects unicode, which is a strict superset of latin1.
184
185If C<$enable> is false, then the C<encode> method will not escape Unicode
186characters unless required by the JSON syntax or other flags.
187
188The main use for this flag is efficiently encoding binary data as JSON
189text, as most octets will not be escaped, resulting in a smaller encoded
190size. The disadvantage is that the resulting JSON text is encoded
191in latin1 (and must correctly be treated as such when storing and
192transfering), a rare encoding for JSON. It is therefore most useful when
193you want to store data structures known to contain binary data efficiently
194in files or databases, not when talking to other JSON encoders/decoders.
195
196 JSON::XS->new->latin1->encode (["\x{89}\x{abc}"]
197 => ["\x{89}\\u0abc"] # (perl syntax, U+abc escaped, U+89 not)
167 198
168=item $json = $json->utf8 ([$enable]) 199=item $json = $json->utf8 ([$enable])
169 200
170If C<$enable> is true (or missing), then the C<encode> method will encode 201If C<$enable> is true (or missing), then the C<encode> method will encode
171the JSON result into UTF-8, as required by many protocols, while the 202the JSON result into UTF-8, as required by many protocols, while the
… …
280Example, 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>,
281resulting in an invalid JSON text: 312resulting in an invalid JSON text:
282 313
283 JSON::XS->new->allow_nonref->encode ("Hello, World!") 314 JSON::XS->new->allow_nonref->encode ("Hello, World!")
284 => "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.
285 352
286=item $json = $json->shrink ([$enable]) 353=item $json = $json->shrink ([$enable])
287 354
288Perl usually over-allocates memory a bit when allocating space for 355Perl usually over-allocates memory a bit when allocating space for
289strings. This flag optionally resizes strings generated by either 356strings. This flag optionally resizes strings generated by either
… …
309strings that look like integers or floats into integers or floats 376strings that look like integers or floats into integers or floats
310internally (there is no difference on the Perl level), saving space. 377internally (there is no difference on the Perl level), saving space.
311 378
312=item $json = $json->max_depth ([$maximum_nesting_depth]) 379=item $json = $json->max_depth ([$maximum_nesting_depth])
313 380
314Sets the maximum nesting level (default C<4096>) accepted while encoding 381Sets the maximum nesting level (default C<512>) accepted while encoding
315or decoding. If the JSON text or Perl data structure has an equal or 382or decoding. If the JSON text or Perl data structure has an equal or
316higher nesting level then this limit, then the encoder and decoder will 383higher nesting level then this limit, then the encoder and decoder will
317stop and croak at that point. 384stop and croak at that point.
318 385
319Nesting level is defined by number of hash- or arrayrefs that the encoder 386Nesting level is defined by number of hash- or arrayrefs that the encoder
… …
322given character in a string. 389given character in a string.
323 390
324Setting the maximum depth to one disallows any nesting, so that ensures 391Setting the maximum depth to one disallows any nesting, so that ensures
325that the object is only a single hash/object or array. 392that the object is only a single hash/object or array.
326 393
327The argument to C<max_depth> will be rounded up to the next nearest power 394The argument to C<max_depth> will be rounded up to the next highest power
328of two. 395of two. If no argument is given, the highest possible setting will be
396used, which is rarely useful.
397
398See SECURITY CONSIDERATIONS, below, for more info on why this is useful.
399
400=item $json = $json->max_size ([$maximum_string_size])
401
402Set the maximum length a JSON text may have (in bytes) where decoding is
403being attempted. The default is C<0>, meaning no limit. When C<decode>
404is called on a string longer then this number of characters it will not
405attempt to decode the string but throw an exception. This setting has no
406effect on C<encode> (yet).
407
408The argument to C<max_size> will be rounded up to the next B<highest>
409power of two (so may be more than requested). If no argument is given, the
410limit check will be deactivated (same as when C<0> is specified).
329 411
330See SECURITY CONSIDERATIONS, below, for more info on why this is useful. 412See SECURITY CONSIDERATIONS, below, for more info on why this is useful.
331 413
332=item $json_text = $json->encode ($perl_scalar) 414=item $json_text = $json->encode ($perl_scalar)
333 415
… …
345 427
346JSON numbers and strings become simple Perl scalars. JSON arrays become 428JSON numbers and strings become simple Perl scalars. JSON arrays become
347Perl arrayrefs and JSON objects become Perl hashrefs. C<true> becomes 429Perl arrayrefs and JSON objects become Perl hashrefs. C<true> becomes
348C<1>, C<false> becomes C<0> and C<null> becomes C<undef>. 430C<1>, C<false> becomes C<0> and C<null> becomes C<undef>.
349 431
432=item ($perl_scalar, $characters) = $json->decode_prefix ($json_text)
433
434This works like the C<decode> method, but instead of raising an exception
435when there is trailing garbage after the first JSON object, it will
436silently stop parsing there and return the number of characters consumed
437so far.
438
439This is useful if your JSON texts are not delimited by an outer protocol
440(which is not the brightest thing to do in the first place) and you need
441to know where the JSON text ends.
442
443 JSON::XS->new->decode_prefix ("[1] the tail")
444 => ([], 3)
445
350=back 446=back
351 447
352 448
353=head1 MAPPING 449=head1 MAPPING
354 450
… …
358(what you put in comes out as something equivalent). 454(what you put in comes out as something equivalent).
359 455
360For the more enlightened: note that in the following descriptions, 456For the more enlightened: note that in the following descriptions,
361lowercase I<perl> refers to the Perl interpreter, while uppcercase I<Perl> 457lowercase I<perl> refers to the Perl interpreter, while uppcercase I<Perl>
362refers to the abstract Perl language itself. 458refers to the abstract Perl language itself.
459
363 460
364=head2 JSON -> PERL 461=head2 JSON -> PERL
365 462
366=over 4 463=over 4
367 464
… …
388conversion details, but an integer may take slightly less memory and might 485conversion details, but an integer may take slightly less memory and might
389represent more values exactly than (floating point) numbers. 486represent more values exactly than (floating point) numbers.
390 487
391=item true, false 488=item true, false
392 489
393These JSON atoms become C<0>, C<1>, respectively. Information is lost in 490These JSON atoms become C<JSON::XS::true> and C<JSON::XS::false>,
394this process. Future versions might represent those values differently, 491respectively. They are overloaded to act almost exactly like the numbers
395but they will be guarenteed to act like these integers would normally in 492C<1> and C<0>. You can check wether a scalar is a JSON boolean by using
396Perl. 493the C<JSON::XS::is_bool> function.
397 494
398=item null 495=item null
399 496
400A JSON null atom becomes C<undef> in Perl. 497A JSON null atom becomes C<undef> in Perl.
401 498
402=back 499=back
500
403 501
404=head2 PERL -> JSON 502=head2 PERL -> JSON
405 503
406The mapping from Perl to JSON is slightly more difficult, as Perl is a 504The mapping from Perl to JSON is slightly more difficult, as Perl is a
407truly typeless language, so we can only guess which JSON type is meant by 505truly typeless language, so we can only guess which JSON type is meant by
… …
432C<1>, which get turned into C<false> and C<true> atoms in JSON. You can 530C<1>, which get turned into C<false> and C<true> atoms in JSON. You can
433also use C<JSON::XS::false> and C<JSON::XS::true> to improve readability. 531also use C<JSON::XS::false> and C<JSON::XS::true> to improve readability.
434 532
435 to_json [\0,JSON::XS::true] # yields [false,true] 533 to_json [\0,JSON::XS::true] # yields [false,true]
436 534
535=item JSON::XS::true, JSON::XS::false
536
537These special values become JSON true and JSON false values,
538respectively. You cna alos use C<\1> and C<\0> directly if you want.
539
437=item blessed objects 540=item blessed objects
438 541
439Blessed objects are not allowed. JSON::XS currently tries to encode their 542Blessed objects are not allowed. JSON::XS currently tries to encode their
440underlying representation (hash- or arrayref), but this behaviour might 543underlying representation (hash- or arrayref), but this behaviour might
441change in future versions. 544change in future versions.
… …
472 $x += 0; # numify it, ensuring it will be dumped as a number 575 $x += 0; # numify it, ensuring it will be dumped as a number
473 $x *= 1; # same thing, the choise is yours. 576 $x *= 1; # same thing, the choise is yours.
474 577
475You can not currently output JSON booleans or force the type in other, 578You can not currently output JSON booleans or force the type in other,
476less obscure, ways. Tell me if you need this capability. 579less obscure, ways. Tell me if you need this capability.
477
478=item circular data structures
479
480Those will be encoded until memory or stackspace runs out.
481 580
482=back 581=back
483 582
484 583
485=head1 COMPARISON 584=head1 COMPARISON
… …
566 665
567Does not check input for validity. 666Does not check input for validity.
568 667
569=back 668=back
570 669
670
671=head2 JSON and YAML
672
673You often hear that JSON is a subset (or a close subset) of YAML. This is,
674however, a mass hysteria and very far from the truth. In general, there is
675no way to configure JSON::XS to output a data structure as valid YAML.
676
677If you really must use JSON::XS to generate YAML, you should use this
678algorithm (subject to change in future versions):
679
680 my $to_yaml = JSON::XS->new->utf8->space_after (1);
681 my $yaml = $to_yaml->encode ($ref) . "\n";
682
683This will usually generate JSON texts that also parse as valid
684YAML. Please note that YAML has hardcoded limits on (simple) object key
685lengths that JSON doesn't have, so you should make sure that your hash
686keys are noticably shorter than the 1024 characters YAML allows.
687
688There might be other incompatibilities that I am not aware of. In general
689you should not try to generate YAML with a JSON generator or vice versa,
690or try to parse JSON with a YAML parser or vice versa: chances are high
691that you will run into severe interoperability problems.
692
693
571=head2 SPEED 694=head2 SPEED
572 695
573It seems that JSON::XS is surprisingly fast, as shown in the following 696It seems that JSON::XS is surprisingly fast, as shown in the following
574tables. They have been generated with the help of the C<eg/bench> program 697tables. They have been generated with the help of the C<eg/bench> program
575in the JSON::XS distribution, to make it easy to compare on your own 698in the JSON::XS distribution, to make it easy to compare on your own
576system. 699system.
577 700
578First comes a comparison between various modules using a very short JSON 701First comes a comparison between various modules using a very short
579string: 702single-line JSON string:
580 703
581 {"method": "handleMessage", "params": ["user1", "we were just talking"], "id": null} 704 {"method": "handleMessage", "params": ["user1", "we were just talking"], \
705 "id": null, "array":[1,11,234,-5,1e5,1e7, true, false]}
582 706
583It shows the number of encodes/decodes per second (JSON::XS uses the 707It shows the number of encodes/decodes per second (JSON::XS uses
584functional interface, while JSON::XS/2 uses the OO interface with 708the functional interface, while JSON::XS/2 uses the OO interface
585pretty-printing and hashkey sorting enabled). Higher is better: 709with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables
710shrink). Higher is better:
586 711
712 Storable | 15779.925 | 14169.946 |
713 -----------+------------+------------+
587 module | encode | decode | 714 module | encode | decode |
588 -----------|------------|------------| 715 -----------|------------|------------|
589 JSON | 11488.516 | 7823.035 | 716 JSON | 4990.842 | 4088.813 |
590 JSON::DWIW | 94708.054 | 129094.260 | 717 JSON::DWIW | 51653.990 | 71575.154 |
591 JSON::PC | 63884.157 | 128528.212 | 718 JSON::PC | 65948.176 | 74631.744 |
592 JSON::Syck | 34898.677 | 42096.911 | 719 JSON::PP | 8931.652 | 3817.168 |
593 JSON::XS | 654027.064 | 396423.669 | 720 JSON::Syck | 24877.248 | 27776.848 |
594 JSON::XS/2 | 371564.190 | 371725.613 | 721 JSON::XS | 388361.481 | 227951.304 |
722 JSON::XS/2 | 227951.304 | 218453.333 |
723 JSON::XS/3 | 338250.323 | 218453.333 |
724 Storable | 16500.016 | 135300.129 |
595 -----------+------------+------------+ 725 -----------+------------+------------+
596 726
597That is, JSON::XS is more than six times faster than JSON::DWIW on 727That is, JSON::XS is about five times faster than JSON::DWIW on encoding,
598encoding, more than three times faster on decoding, and about thirty times 728about three times faster on decoding, and over fourty times faster
599faster than JSON, even with pretty-printing and key sorting. 729than JSON, even with pretty-printing and key sorting. It also compares
730favourably to Storable for small amounts of data.
600 731
601Using a longer test string (roughly 18KB, generated from Yahoo! Locals 732Using a longer test string (roughly 18KB, generated from Yahoo! Locals
602search API (http://nanoref.com/yahooapis/mgPdGg): 733search API (http://nanoref.com/yahooapis/mgPdGg):
603 734
604 module | encode | decode | 735 module | encode | decode |
605 -----------|------------|------------| 736 -----------|------------|------------|
606 JSON | 273.023 | 44.674 | 737 JSON | 55.260 | 34.971 |
607 JSON::DWIW | 1089.383 | 1145.704 | 738 JSON::DWIW | 825.228 | 1082.513 |
608 JSON::PC | 3097.419 | 2393.921 | 739 JSON::PC | 3571.444 | 2394.829 |
609 JSON::Syck | 514.060 | 843.053 | 740 JSON::PP | 210.987 | 32.574 |
610 JSON::XS | 6479.668 | 3636.364 | 741 JSON::Syck | 552.551 | 787.544 |
611 JSON::XS/2 | 3774.221 | 3599.124 | 742 JSON::XS | 5780.463 | 4854.519 |
743 JSON::XS/2 | 3869.998 | 4798.975 |
744 JSON::XS/3 | 5862.880 | 4798.975 |
745 Storable | 4445.002 | 5235.027 |
612 -----------+------------+------------+ 746 -----------+------------+------------+
613 747
614Again, JSON::XS leads by far. 748Again, JSON::XS leads by far (except for Storable which non-surprisingly
749decodes faster).
615 750
616On large strings containing lots of high unicode characters, some modules 751On large strings containing lots of high unicode characters, some modules
617(such as JSON::PC) seem to decode faster than JSON::XS, but the result 752(such as JSON::PC) seem to decode faster than JSON::XS, but the result
618will be broken due to missing (or wrong) unicode handling. Others refuse 753will be broken due to missing (or wrong) unicode handling. Others refuse
619to decode or encode properly, so it was impossible to prepare a fair 754to decode or encode properly, so it was impossible to prepare a fair
… …
632Second, you need to avoid resource-starving attacks. That means you should 767Second, you need to avoid resource-starving attacks. That means you should
633limit the size of JSON texts you accept, or make sure then when your 768limit the size of JSON texts you accept, or make sure then when your
634resources run out, thats just fine (e.g. by using a separate process that 769resources run out, thats just fine (e.g. by using a separate process that
635can crash safely). The size of a JSON text in octets or characters is 770can crash safely). The size of a JSON text in octets or characters is
636usually a good indication of the size of the resources required to decode 771usually a good indication of the size of the resources required to decode
637it into a Perl structure. 772it into a Perl structure. While JSON::XS can check the size of the JSON
773text, it might be too late when you already have it in memory, so you
774might want to check the size before you accept the string.
638 775
639Third, JSON::XS recurses using the C stack when decoding objects and 776Third, JSON::XS recurses using the C stack when decoding objects and
640arrays. The C stack is a limited resource: for instance, on my amd64 777arrays. The C stack is a limited resource: for instance, on my amd64
641machine with 8MB of stack size I can decode around 180k nested arrays 778machine with 8MB of stack size I can decode around 180k nested arrays but
642but only 14k nested JSON objects. If that is exceeded, the program 779only 14k nested JSON objects (due to perl itself recursing deeply on croak
643crashes. Thats why the default nesting limit is set to 4096. If your 780to free the temporary). If that is exceeded, the program crashes. to be
781conservative, the default nesting limit is set to 512. If your process
644process has a smaller stack, you should adjust this setting accordingly 782has a smaller stack, you should adjust this setting accordingly with the
645with the C<max_depth> method. 783C<max_depth> method.
646 784
647And last but least, something else could bomb you that I forgot to think 785And last but least, something else could bomb you that I forgot to think
648of. In that case, you get to keep the pieces. I am alway sopen for hints, 786of. In that case, you get to keep the pieces. I am always open for hints,
649though... 787though...
788
789If you are using JSON::XS to return packets to consumption
790by javascript scripts in a browser you should have a look at
791L<http://jpsykes.com/47/practical-csrf-and-json-security> to see wether
792you are vulnerable to some common attack vectors (which really are browser
793design bugs, but it is still you who will have to deal with it, as major
794browser developers care only for features, not about doing security
795right).
650 796
651 797
652=head1 BUGS 798=head1 BUGS
653 799
654While the goal of this module is to be correct, that unfortunately does 800While the goal of this module is to be correct, that unfortunately does
… …
656still relatively early in its development. If you keep reporting bugs they 802still relatively early in its development. If you keep reporting bugs they
657will be fixed swiftly, though. 803will be fixed swiftly, though.
658 804
659=cut 805=cut
660 806
807our $true = do { bless \(my $dummy = "1"), "JSON::XS::Boolean" };
808our $false = do { bless \(my $dummy = "0"), "JSON::XS::Boolean" };
809
661sub true() { \1 } 810sub true() { $true }
662sub false() { \0 } 811sub false() { $false }
812
813sub is_bool($) {
814 UNIVERSAL::isa $_[0], "JSON::XS::Boolean"
815# or UNIVERSAL::isa $_[0], "JSON::Literal"
816}
817
818XSLoader::load "JSON::XS", $VERSION;
819
820package JSON::XS::Boolean;
821
822use overload
823 "0+" => sub { ${$_[0]} },
824 "++" => sub { $_[0] = ${$_[0]} + 1 },
825 "--" => sub { $_[0] = ${$_[0]} - 1 },
826 fallback => 1;
663 827
6641; 8281;
665 829
666=head1 AUTHOR 830=head1 AUTHOR
667 831

Diff Legend

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