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.23 by root, Sun Mar 25 21:19:13 2007 UTC vs.
Revision 1.43 by root, Sat Jun 23 23:49:29 2007 UTC

… …
85 85
86package JSON::XS; 86package JSON::XS;
87 87
88use strict; 88use strict;
89 89
90BEGIN {
91 our $VERSION = '0.8'; 90our $VERSION = '1.3';
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
… …
154 160
155If C<$enable> is true (or missing), then the C<encode> method will not 161If 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 162generate characters outside the code range C<0..127> (which is ASCII). Any
157unicode characters outside that range will be escaped using either a 163unicode characters outside that range will be escaped using either a
158single \uXXXX (BMP characters) or a double \uHHHH\uLLLLL escape sequence, 164single \uXXXX (BMP characters) or a double \uHHHH\uLLLLL escape sequence,
159as per RFC4627. 165as per RFC4627. The resulting encoded JSON text can be treated as a native
166unicode string, an ascii-encoded, latin1-encoded or UTF-8 encoded string,
167or any other superset of ASCII.
160 168
161If 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
162characters unless required by the JSON syntax. This results in a faster 170characters unless required by the JSON syntax or other flags. This results
163and 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.
164 176
165 JSON::XS->new->ascii (1)->encode ([chr 0x10401]) 177 JSON::XS->new->ascii (1)->encode ([chr 0x10401])
166 => ["\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)
167 202
168=item $json = $json->utf8 ([$enable]) 203=item $json = $json->utf8 ([$enable])
169 204
170If 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
171the 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
… …
284 => "Hello, World!" 319 => "Hello, World!"
285 320
286=item $json = $json->shrink ([$enable]) 321=item $json = $json->shrink ([$enable])
287 322
288Perl usually over-allocates memory a bit when allocating space for 323Perl usually over-allocates memory a bit when allocating space for
289strings. This flag optionally resizes strings generated by either 324strings. This flag optionally resizes strings generated by either
290C<encode> or C<decode> to their minimum size possible. This can save 325C<encode> or C<decode> to their minimum size possible. This can save
291memory when your JSON texts are either very very long or you have many 326memory when your JSON texts are either very very long or you have many
292short strings. It will also try to downgrade any strings to octet-form 327short strings. It will also try to downgrade any strings to octet-form
293if possible: perl stores strings internally either in an encoding called 328if possible: perl stores strings internally either in an encoding called
294UTF-X or in octet-form. The latter cannot store everything but uses less 329UTF-X or in octet-form. The latter cannot store everything but uses less
295space in general. 330space in general (and some buggy Perl or C code might even rely on that
331internal representation being used).
296 332
333The actual definition of what shrink does might change in future versions,
334but it will always try to save space at the expense of time.
335
297If C<$enable> is true (or missing), the string returned by C<encode> will be shrunk-to-fit, 336If C<$enable> is true (or missing), the string returned by C<encode> will
298while all strings generated by C<decode> will also be shrunk-to-fit. 337be shrunk-to-fit, while all strings generated by C<decode> will also be
338shrunk-to-fit.
299 339
300If C<$enable> is false, then the normal perl allocation algorithms are used. 340If C<$enable> is false, then the normal perl allocation algorithms are used.
301If you work with your data, then this is likely to be faster. 341If you work with your data, then this is likely to be faster.
302 342
303In the future, this setting might control other things, such as converting 343In the future, this setting might control other things, such as converting
304strings that look like integers or floats into integers or floats 344strings that look like integers or floats into integers or floats
305internally (there is no difference on the Perl level), saving space. 345internally (there is no difference on the Perl level), saving space.
306 346
307=item $json = $json->max_depth ([$maximum_nesting_depth]) 347=item $json = $json->max_depth ([$maximum_nesting_depth])
308 348
309Sets the maximum nesting level (default C<8192>) accepted while encoding 349Sets the maximum nesting level (default C<512>) accepted while encoding
310or decoding. If the JSON text or Perl data structure has an equal or 350or decoding. If the JSON text or Perl data structure has an equal or
311higher nesting level then this limit, then the encoder and decoder will 351higher nesting level then this limit, then the encoder and decoder will
312stop and croak at that point. 352stop and croak at that point.
313 353
314Nesting level is defined by number of hash- or arrayrefs that the encoder 354Nesting level is defined by number of hash- or arrayrefs that the encoder
… …
340 380
341JSON numbers and strings become simple Perl scalars. JSON arrays become 381JSON numbers and strings become simple Perl scalars. JSON arrays become
342Perl arrayrefs and JSON objects become Perl hashrefs. C<true> becomes 382Perl arrayrefs and JSON objects become Perl hashrefs. C<true> becomes
343C<1>, C<false> becomes C<0> and C<null> becomes C<undef>. 383C<1>, C<false> becomes C<0> and C<null> becomes C<undef>.
344 384
385=item ($perl_scalar, $characters) = $json->decode_prefix ($json_text)
386
387This works like the C<decode> method, but instead of raising an exception
388when there is trailing garbage after the first JSON object, it will
389silently stop parsing there and return the number of characters consumed
390so far.
391
392This is useful if your JSON texts are not delimited by an outer protocol
393(which is not the brightest thing to do in the first place) and you need
394to know where the JSON text ends.
395
396 JSON::XS->new->decode_prefix ("[1] the tail")
397 => ([], 3)
398
345=back 399=back
346 400
347 401
348=head1 MAPPING 402=head1 MAPPING
349 403
… …
353(what you put in comes out as something equivalent). 407(what you put in comes out as something equivalent).
354 408
355For the more enlightened: note that in the following descriptions, 409For the more enlightened: note that in the following descriptions,
356lowercase I<perl> refers to the Perl interpreter, while uppcercase I<Perl> 410lowercase I<perl> refers to the Perl interpreter, while uppcercase I<Perl>
357refers to the abstract Perl language itself. 411refers to the abstract Perl language itself.
412
358 413
359=head2 JSON -> PERL 414=head2 JSON -> PERL
360 415
361=over 4 416=over 4
362 417
… …
383conversion details, but an integer may take slightly less memory and might 438conversion details, but an integer may take slightly less memory and might
384represent more values exactly than (floating point) numbers. 439represent more values exactly than (floating point) numbers.
385 440
386=item true, false 441=item true, false
387 442
388These JSON atoms become C<0>, C<1>, respectively. Information is lost in 443These JSON atoms become C<JSON::XS::true> and C<JSON::XS::false>,
389this process. Future versions might represent those values differently, 444respectively. They are overloaded to act almost exactly like the numbers
390but they will be guarenteed to act like these integers would normally in 445C<1> and C<0>. You can check wether a scalar is a JSON boolean by using
391Perl. 446the C<JSON::XS::is_bool> function.
392 447
393=item null 448=item null
394 449
395A JSON null atom becomes C<undef> in Perl. 450A JSON null atom becomes C<undef> in Perl.
396 451
397=back 452=back
453
398 454
399=head2 PERL -> JSON 455=head2 PERL -> JSON
400 456
401The mapping from Perl to JSON is slightly more difficult, as Perl is a 457The mapping from Perl to JSON is slightly more difficult, as Perl is a
402truly typeless language, so we can only guess which JSON type is meant by 458truly typeless language, so we can only guess which JSON type is meant by
… …
405=over 4 461=over 4
406 462
407=item hash references 463=item hash references
408 464
409Perl hash references become JSON objects. As there is no inherent ordering 465Perl hash references become JSON objects. As there is no inherent ordering
410in hash keys, they will usually be encoded in a pseudo-random order that 466in hash keys (or JSON objects), they will usually be encoded in a
411can change between runs of the same program but stays generally the same 467pseudo-random order that can change between runs of the same program but
412within a single run of a program. JSON::XS can optionally sort the hash 468stays generally the same within a single run of a program. JSON::XS can
413keys (determined by the I<canonical> flag), so the same datastructure 469optionally sort the hash keys (determined by the I<canonical> flag), so
414will serialise to the same JSON text (given same settings and version of 470the same datastructure will serialise to the same JSON text (given same
415JSON::XS), but this incurs a runtime overhead. 471settings and version of JSON::XS), but this incurs a runtime overhead
472and is only rarely useful, e.g. when you want to compare some JSON text
473against another for equality.
416 474
417=item array references 475=item array references
418 476
419Perl array references become JSON arrays. 477Perl array references become JSON arrays.
478
479=item other references
480
481Other unblessed references are generally not allowed and will cause an
482exception to be thrown, except for references to the integers C<0> and
483C<1>, which get turned into C<false> and C<true> atoms in JSON. You can
484also use C<JSON::XS::false> and C<JSON::XS::true> to improve readability.
485
486 to_json [\0,JSON::XS::true] # yields [false,true]
487
488=item JSON::XS::true, JSON::XS::false
489
490These special values become JSON true and JSON false values,
491respectively. You cna alos use C<\1> and C<\0> directly if you want.
420 492
421=item blessed objects 493=item blessed objects
422 494
423Blessed objects are not allowed. JSON::XS currently tries to encode their 495Blessed objects are not allowed. JSON::XS currently tries to encode their
424underlying representation (hash- or arrayref), but this behaviour might 496underlying representation (hash- or arrayref), but this behaviour might
… …
456 $x += 0; # numify it, ensuring it will be dumped as a number 528 $x += 0; # numify it, ensuring it will be dumped as a number
457 $x *= 1; # same thing, the choise is yours. 529 $x *= 1; # same thing, the choise is yours.
458 530
459You can not currently output JSON booleans or force the type in other, 531You can not currently output JSON booleans or force the type in other,
460less obscure, ways. Tell me if you need this capability. 532less obscure, ways. Tell me if you need this capability.
461
462=item circular data structures
463
464Those will be encoded until memory or stackspace runs out.
465 533
466=back 534=back
467 535
468 536
469=head1 COMPARISON 537=head1 COMPARISON
… …
550 618
551Does not check input for validity. 619Does not check input for validity.
552 620
553=back 621=back
554 622
623
624=head2 JSON and YAML
625
626You often hear that JSON is a subset (or a close subset) of YAML. This is,
627however, a mass hysteria and very far from the truth. In general, there is
628no way to configure JSON::XS to output a data structure as valid YAML.
629
630If you really must use JSON::XS to generate YAML, you should use this
631algorithm (subject to change in future versions):
632
633 my $to_yaml = JSON::XS->new->utf8->space_after (1);
634 my $yaml = $to_yaml->encode ($ref) . "\n";
635
636This will usually generate JSON texts that also parse as valid
637YAML. Please note that YAML has hardcoded limits on (simple) object key
638lengths that JSON doesn't have, so you should make sure that your hash
639keys are noticably shorter than the 1024 characters YAML allows.
640
641There might be other incompatibilities that I am not aware of. In general
642you should not try to generate YAML with a JSON generator or vice versa,
643or try to parse JSON with a YAML parser or vice versa: chances are high
644that you will run into severe interoperability problems.
645
646
555=head2 SPEED 647=head2 SPEED
556 648
557It seems that JSON::XS is surprisingly fast, as shown in the following 649It seems that JSON::XS is surprisingly fast, as shown in the following
558tables. They have been generated with the help of the C<eg/bench> program 650tables. They have been generated with the help of the C<eg/bench> program
559in the JSON::XS distribution, to make it easy to compare on your own 651in the JSON::XS distribution, to make it easy to compare on your own
560system. 652system.
561 653
562First comes a comparison between various modules using a very short JSON 654First comes a comparison between various modules using a very short
563string: 655single-line JSON string:
564 656
565 {"method": "handleMessage", "params": ["user1", "we were just talking"], "id": null} 657 {"method": "handleMessage", "params": ["user1", "we were just talking"], \
658 "id": null, "array":[1,11,234,-5,1e5,1e7, true, false]}
566 659
567It shows the number of encodes/decodes per second (JSON::XS uses the 660It shows the number of encodes/decodes per second (JSON::XS uses
568functional interface, while JSON::XS/2 uses the OO interface with 661the functional interface, while JSON::XS/2 uses the OO interface
569pretty-printing and hashkey sorting enabled). Higher is better: 662with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables
663shrink). Higher is better:
570 664
571 module | encode | decode | 665 module | encode | decode |
572 -----------|------------|------------| 666 -----------|------------|------------|
573 JSON | 11488.516 | 7823.035 | 667 JSON | 7645.468 | 4208.613 |
574 JSON::DWIW | 94708.054 | 129094.260 | 668 JSON::DWIW | 40721.398 | 77101.176 |
575 JSON::PC | 63884.157 | 128528.212 | 669 JSON::PC | 65948.176 | 78251.940 |
576 JSON::Syck | 34898.677 | 42096.911 | 670 JSON::Syck | 22844.793 | 26479.192 |
577 JSON::XS | 654027.064 | 396423.669 | 671 JSON::XS | 388361.481 | 199728.762 |
578 JSON::XS/2 | 371564.190 | 371725.613 | 672 JSON::XS/2 | 218453.333 | 192399.266 |
673 JSON::XS/3 | 338250.323 | 192399.266 |
674 Storable | 15779.925 | 14169.946 |
579 -----------+------------+------------+ 675 -----------+------------+------------+
580 676
581That is, JSON::XS is more than six times faster than JSON::DWIW on 677That is, JSON::XS is about five times faster than JSON::DWIW on encoding,
582encoding, more than three times faster on decoding, and about thirty times 678about three times faster on decoding, and over fourty times faster
583faster than JSON, even with pretty-printing and key sorting. 679than JSON, even with pretty-printing and key sorting. It also compares
680favourably to Storable for small amounts of data.
584 681
585Using a longer test string (roughly 18KB, generated from Yahoo! Locals 682Using a longer test string (roughly 18KB, generated from Yahoo! Locals
586search API (http://nanoref.com/yahooapis/mgPdGg): 683search API (http://nanoref.com/yahooapis/mgPdGg):
587 684
588 module | encode | decode | 685 module | encode | decode |
589 -----------|------------|------------| 686 -----------|------------|------------|
590 JSON | 273.023 | 44.674 | 687 JSON | 254.685 | 37.665 |
591 JSON::DWIW | 1089.383 | 1145.704 | 688 JSON::DWIW | 843.343 | 1049.731 |
592 JSON::PC | 3097.419 | 2393.921 | 689 JSON::PC | 3602.116 | 2307.352 |
593 JSON::Syck | 514.060 | 843.053 | 690 JSON::Syck | 505.107 | 787.899 |
594 JSON::XS | 6479.668 | 3636.364 | 691 JSON::XS | 5747.196 | 3690.220 |
595 JSON::XS/2 | 3774.221 | 3599.124 | 692 JSON::XS/2 | 3968.121 | 3676.634 |
693 JSON::XS/3 | 6105.246 | 3662.508 |
694 Storable | 4417.337 | 5285.161 |
596 -----------+------------+------------+ 695 -----------+------------+------------+
597 696
598Again, JSON::XS leads by far. 697Again, JSON::XS leads by far (except for Storable which non-surprisingly
698decodes faster).
599 699
600On large strings containing lots of high unicode characters, some modules 700On large strings containing lots of high unicode characters, some modules
601(such as JSON::PC) seem to decode faster than JSON::XS, but the result 701(such as JSON::PC) seem to decode faster than JSON::XS, but the result
602will be broken due to missing (or wrong) unicode handling. Others refuse 702will be broken due to missing (or wrong) unicode handling. Others refuse
603to decode or encode properly, so it was impossible to prepare a fair 703to decode or encode properly, so it was impossible to prepare a fair
… …
620usually a good indication of the size of the resources required to decode 720usually a good indication of the size of the resources required to decode
621it into a Perl structure. 721it into a Perl structure.
622 722
623Third, JSON::XS recurses using the C stack when decoding objects and 723Third, JSON::XS recurses using the C stack when decoding objects and
624arrays. The C stack is a limited resource: for instance, on my amd64 724arrays. The C stack is a limited resource: for instance, on my amd64
625machine with 8MB of stack size I can decode around 180k nested arrays 725machine with 8MB of stack size I can decode around 180k nested arrays but
626but only 14k nested JSON objects. If that is exceeded, the program 726only 14k nested JSON objects (due to perl itself recursing deeply on croak
727to free the temporary). If that is exceeded, the program crashes. to be
627crashes. Thats why the default nesting limit is set to 8192. If your 728conservative, the default nesting limit is set to 512. If your process
628process has a smaller stack, you should adjust this setting accordingly 729has a smaller stack, you should adjust this setting accordingly with the
629with the C<max_depth> method. 730C<max_depth> method.
630 731
631And last but least, something else could bomb you that I forgot to think 732And last but least, something else could bomb you that I forgot to think
632of. In that case, you get to keep the pieces. I am alway sopen for hints, 733of. In that case, you get to keep the pieces. I am always open for hints,
633though... 734though...
735
736If you are using JSON::XS to return packets to consumption
737by javascript scripts in a browser you should have a look at
738L<http://jpsykes.com/47/practical-csrf-and-json-security> to see wether
739you are vulnerable to some common attack vectors (which really are browser
740design bugs, but it is still you who will have to deal with it, as major
741browser developers care only for features, not about doing security
742right).
634 743
635 744
636=head1 BUGS 745=head1 BUGS
637 746
638While the goal of this module is to be correct, that unfortunately does 747While the goal of this module is to be correct, that unfortunately does
… …
640still relatively early in its development. If you keep reporting bugs they 749still relatively early in its development. If you keep reporting bugs they
641will be fixed swiftly, though. 750will be fixed swiftly, though.
642 751
643=cut 752=cut
644 753
754our $true = do { bless \(my $dummy = 1), "JSON::XS::Boolean" };
755our $false = do { bless \(my $dummy = 0), "JSON::XS::Boolean" };
756
757sub true() { $true }
758sub false() { $false }
759
760sub is_bool($) {
761 UNIVERSAL::isa $_[0], "JSON::XS::Boolean"
762 or UNIVERSAL::isa $_[0], "JSON::Literal"
763}
764
765XSLoader::load "JSON::XS", $VERSION;
766
767package JSON::XS::Boolean;
768
769use overload
770 "0+" => sub { ${$_[0]} },
771 "++" => sub { $_[0] = ${$_[0]} + 1 },
772 "--" => sub { $_[0] = ${$_[0]} - 1 },
773 fallback => 1;
774
6451; 7751;
646 776
647=head1 AUTHOR 777=head1 AUTHOR
648 778
649 Marc Lehmann <schmorp@schmorp.de> 779 Marc Lehmann <schmorp@schmorp.de>

Diff Legend

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