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.30 by root, Mon Apr 9 06:37:40 2007 UTC vs.
Revision 1.44 by root, Mon Jun 25 04:08:17 2007 UTC

… …
85 85
86package JSON::XS; 86package JSON::XS;
87 87
88use strict; 88use strict;
89 89
90BEGIN {
91 our $VERSION = '1.11'; 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
… …
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
… …
280Example, 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>,
281resulting in an invalid JSON text: 316resulting in an invalid JSON text:
282 317
283 JSON::XS->new->allow_nonref->encode ("Hello, World!") 318 JSON::XS->new->allow_nonref->encode ("Hello, World!")
284 => "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 the user of the object) are
347usually in upper case letters and to avoid collisions with the C<to_json>
348function.
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
… …
345 412
346JSON numbers and strings become simple Perl scalars. JSON arrays become 413JSON numbers and strings become simple Perl scalars. JSON arrays become
347Perl arrayrefs and JSON objects become Perl hashrefs. C<true> becomes 414Perl arrayrefs and JSON objects become Perl hashrefs. C<true> becomes
348C<1>, C<false> becomes C<0> and C<null> becomes C<undef>. 415C<1>, C<false> becomes C<0> and C<null> becomes C<undef>.
349 416
417=item ($perl_scalar, $characters) = $json->decode_prefix ($json_text)
418
419This works like the C<decode> method, but instead of raising an exception
420when there is trailing garbage after the first JSON object, it will
421silently stop parsing there and return the number of characters consumed
422so far.
423
424This is useful if your JSON texts are not delimited by an outer protocol
425(which is not the brightest thing to do in the first place) and you need
426to know where the JSON text ends.
427
428 JSON::XS->new->decode_prefix ("[1] the tail")
429 => ([], 3)
430
350=back 431=back
351 432
352 433
353=head1 MAPPING 434=head1 MAPPING
354 435
… …
358(what you put in comes out as something equivalent). 439(what you put in comes out as something equivalent).
359 440
360For the more enlightened: note that in the following descriptions, 441For the more enlightened: note that in the following descriptions,
361lowercase I<perl> refers to the Perl interpreter, while uppcercase I<Perl> 442lowercase I<perl> refers to the Perl interpreter, while uppcercase I<Perl>
362refers to the abstract Perl language itself. 443refers to the abstract Perl language itself.
444
363 445
364=head2 JSON -> PERL 446=head2 JSON -> PERL
365 447
366=over 4 448=over 4
367 449
… …
388conversion details, but an integer may take slightly less memory and might 470conversion details, but an integer may take slightly less memory and might
389represent more values exactly than (floating point) numbers. 471represent more values exactly than (floating point) numbers.
390 472
391=item true, false 473=item true, false
392 474
393These JSON atoms become C<0>, C<1>, respectively. Information is lost in 475These JSON atoms become C<JSON::XS::true> and C<JSON::XS::false>,
394this process. Future versions might represent those values differently, 476respectively. They are overloaded to act almost exactly like the numbers
395but they will be guarenteed to act like these integers would normally in 477C<1> and C<0>. You can check wether a scalar is a JSON boolean by using
396Perl. 478the C<JSON::XS::is_bool> function.
397 479
398=item null 480=item null
399 481
400A JSON null atom becomes C<undef> in Perl. 482A JSON null atom becomes C<undef> in Perl.
401 483
402=back 484=back
485
403 486
404=head2 PERL -> JSON 487=head2 PERL -> JSON
405 488
406The mapping from Perl to JSON is slightly more difficult, as Perl is a 489The 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 490truly 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 515C<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. 516also use C<JSON::XS::false> and C<JSON::XS::true> to improve readability.
434 517
435 to_json [\0,JSON::XS::true] # yields [false,true] 518 to_json [\0,JSON::XS::true] # yields [false,true]
436 519
520=item JSON::XS::true, JSON::XS::false
521
522These special values become JSON true and JSON false values,
523respectively. You cna alos use C<\1> and C<\0> directly if you want.
524
437=item blessed objects 525=item blessed objects
438 526
439Blessed objects are not allowed. JSON::XS currently tries to encode their 527Blessed objects are not allowed. JSON::XS currently tries to encode their
440underlying representation (hash- or arrayref), but this behaviour might 528underlying representation (hash- or arrayref), but this behaviour might
441change in future versions. 529change in future versions.
… …
562 650
563Does not check input for validity. 651Does not check input for validity.
564 652
565=back 653=back
566 654
655
656=head2 JSON and YAML
657
658You often hear that JSON is a subset (or a close subset) of YAML. This is,
659however, a mass hysteria and very far from the truth. In general, there is
660no way to configure JSON::XS to output a data structure as valid YAML.
661
662If you really must use JSON::XS to generate YAML, you should use this
663algorithm (subject to change in future versions):
664
665 my $to_yaml = JSON::XS->new->utf8->space_after (1);
666 my $yaml = $to_yaml->encode ($ref) . "\n";
667
668This will usually generate JSON texts that also parse as valid
669YAML. Please note that YAML has hardcoded limits on (simple) object key
670lengths that JSON doesn't have, so you should make sure that your hash
671keys are noticably shorter than the 1024 characters YAML allows.
672
673There might be other incompatibilities that I am not aware of. In general
674you should not try to generate YAML with a JSON generator or vice versa,
675or try to parse JSON with a YAML parser or vice versa: chances are high
676that you will run into severe interoperability problems.
677
678
567=head2 SPEED 679=head2 SPEED
568 680
569It seems that JSON::XS is surprisingly fast, as shown in the following 681It seems that JSON::XS is surprisingly fast, as shown in the following
570tables. They have been generated with the help of the C<eg/bench> program 682tables. They have been generated with the help of the C<eg/bench> program
571in the JSON::XS distribution, to make it easy to compare on your own 683in the JSON::XS distribution, to make it easy to compare on your own
572system. 684system.
573 685
574First comes a comparison between various modules using a very short JSON 686First comes a comparison between various modules using a very short
575string: 687single-line JSON string:
576 688
577 {"method": "handleMessage", "params": ["user1", "we were just talking"], "id": null} 689 {"method": "handleMessage", "params": ["user1", "we were just talking"], \
690 "id": null, "array":[1,11,234,-5,1e5,1e7, true, false]}
578 691
579It shows the number of encodes/decodes per second (JSON::XS uses the 692It shows the number of encodes/decodes per second (JSON::XS uses
580functional interface, while JSON::XS/2 uses the OO interface with 693the functional interface, while JSON::XS/2 uses the OO interface
581pretty-printing and hashkey sorting enabled). Higher is better: 694with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables
695shrink). Higher is better:
582 696
583 module | encode | decode | 697 module | encode | decode |
584 -----------|------------|------------| 698 -----------|------------|------------|
585 JSON | 11488.516 | 7823.035 | 699 JSON | 7645.468 | 4208.613 |
586 JSON::DWIW | 94708.054 | 129094.260 | 700 JSON::DWIW | 40721.398 | 77101.176 |
587 JSON::PC | 63884.157 | 128528.212 | 701 JSON::PC | 65948.176 | 78251.940 |
588 JSON::Syck | 34898.677 | 42096.911 | 702 JSON::Syck | 22844.793 | 26479.192 |
589 JSON::XS | 654027.064 | 396423.669 | 703 JSON::XS | 388361.481 | 199728.762 |
590 JSON::XS/2 | 371564.190 | 371725.613 | 704 JSON::XS/2 | 218453.333 | 192399.266 |
705 JSON::XS/3 | 338250.323 | 192399.266 |
706 Storable | 15779.925 | 14169.946 |
591 -----------+------------+------------+ 707 -----------+------------+------------+
592 708
593That is, JSON::XS is more than six times faster than JSON::DWIW on 709That is, JSON::XS is about five times faster than JSON::DWIW on encoding,
594encoding, more than three times faster on decoding, and about thirty times 710about three times faster on decoding, and over fourty times faster
595faster than JSON, even with pretty-printing and key sorting. 711than JSON, even with pretty-printing and key sorting. It also compares
712favourably to Storable for small amounts of data.
596 713
597Using a longer test string (roughly 18KB, generated from Yahoo! Locals 714Using a longer test string (roughly 18KB, generated from Yahoo! Locals
598search API (http://nanoref.com/yahooapis/mgPdGg): 715search API (http://nanoref.com/yahooapis/mgPdGg):
599 716
600 module | encode | decode | 717 module | encode | decode |
601 -----------|------------|------------| 718 -----------|------------|------------|
602 JSON | 273.023 | 44.674 | 719 JSON | 254.685 | 37.665 |
603 JSON::DWIW | 1089.383 | 1145.704 | 720 JSON::DWIW | 843.343 | 1049.731 |
604 JSON::PC | 3097.419 | 2393.921 | 721 JSON::PC | 3602.116 | 2307.352 |
605 JSON::Syck | 514.060 | 843.053 | 722 JSON::Syck | 505.107 | 787.899 |
606 JSON::XS | 6479.668 | 3636.364 | 723 JSON::XS | 5747.196 | 3690.220 |
607 JSON::XS/2 | 3774.221 | 3599.124 | 724 JSON::XS/2 | 3968.121 | 3676.634 |
725 JSON::XS/3 | 6105.246 | 3662.508 |
726 Storable | 4417.337 | 5285.161 |
608 -----------+------------+------------+ 727 -----------+------------+------------+
609 728
610Again, JSON::XS leads by far. 729Again, JSON::XS leads by far (except for Storable which non-surprisingly
730decodes faster).
611 731
612On large strings containing lots of high unicode characters, some modules 732On large strings containing lots of high unicode characters, some modules
613(such as JSON::PC) seem to decode faster than JSON::XS, but the result 733(such as JSON::PC) seem to decode faster than JSON::XS, but the result
614will be broken due to missing (or wrong) unicode handling. Others refuse 734will be broken due to missing (or wrong) unicode handling. Others refuse
615to decode or encode properly, so it was impossible to prepare a fair 735to decode or encode properly, so it was impossible to prepare a fair
… …
643 763
644And last but least, something else could bomb you that I forgot to think 764And last but least, something else could bomb you that I forgot to think
645of. In that case, you get to keep the pieces. I am always open for hints, 765of. In that case, you get to keep the pieces. I am always open for hints,
646though... 766though...
647 767
768If you are using JSON::XS to return packets to consumption
769by javascript scripts in a browser you should have a look at
770L<http://jpsykes.com/47/practical-csrf-and-json-security> to see wether
771you are vulnerable to some common attack vectors (which really are browser
772design bugs, but it is still you who will have to deal with it, as major
773browser developers care only for features, not about doing security
774right).
775
648 776
649=head1 BUGS 777=head1 BUGS
650 778
651While the goal of this module is to be correct, that unfortunately does 779While the goal of this module is to be correct, that unfortunately does
652not mean its bug-free, only that I think its design is bug-free. It is 780not mean its bug-free, only that I think its design is bug-free. It is
653still relatively early in its development. If you keep reporting bugs they 781still relatively early in its development. If you keep reporting bugs they
654will be fixed swiftly, though. 782will be fixed swiftly, though.
655 783
656=cut 784=cut
657 785
786our $true = do { bless \(my $dummy = 1), "JSON::XS::Boolean" };
787our $false = do { bless \(my $dummy = 0), "JSON::XS::Boolean" };
788
658sub true() { \1 } 789sub true() { $true }
659sub false() { \0 } 790sub false() { $false }
791
792sub is_bool($) {
793 UNIVERSAL::isa $_[0], "JSON::XS::Boolean"
794# or UNIVERSAL::isa $_[0], "JSON::Literal"
795}
796
797XSLoader::load "JSON::XS", $VERSION;
798
799package JSON::XS::Boolean;
800
801use overload
802 "0+" => sub { ${$_[0]} },
803 "++" => sub { $_[0] = ${$_[0]} + 1 },
804 "--" => sub { $_[0] = ${$_[0]} - 1 },
805 fallback => 1;
660 806
6611; 8071;
662 808
663=head1 AUTHOR 809=head1 AUTHOR
664 810

Diff Legend

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