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.86 by root, Wed Mar 19 03:17:38 2008 UTC vs.
Revision 1.142 by root, Fri Oct 25 19:57:42 2013 UTC

1=head1 NAME
2
3JSON::XS - JSON serialising/deserialising, done correctly and fast
4
1=encoding utf-8 5=encoding utf-8
2
3=head1 NAME
4
5JSON::XS - JSON serialising/deserialising, done correctly and fast
6 6
7JSON::XS - 正しくて高速な JSON シリアライザ/デシリアライザ 7JSON::XS - 正しくて高速な JSON シリアライザ/デシリアライザ
8 (http://fleur.hio.jp/perldoc/mix/lib/JSON/XS.html) 8 (http://fleur.hio.jp/perldoc/mix/lib/JSON/XS.html)
9 9
10=head1 SYNOPSIS 10=head1 SYNOPSIS
… …
37primary goal is to be I<correct> and its secondary goal is to be 37primary goal is to be I<correct> and its secondary goal is to be
38I<fast>. To reach the latter goal it was written in C. 38I<fast>. To reach the latter goal it was written in C.
39 39
40Beginning with version 2.0 of the JSON module, when both JSON and 40Beginning with version 2.0 of the JSON module, when both JSON and
41JSON::XS are installed, then JSON will fall back on JSON::XS (this can be 41JSON::XS are installed, then JSON will fall back on JSON::XS (this can be
42overriden) with no overhead due to emulation (by inheritign constructor 42overridden) with no overhead due to emulation (by inheriting constructor
43and methods). If JSON::XS is not available, it will fall back to the 43and methods). If JSON::XS is not available, it will fall back to the
44compatible JSON::PP module as backend, so using JSON instead of JSON::XS 44compatible JSON::PP module as backend, so using JSON instead of JSON::XS
45gives you a portable JSON API that can be fast when you need and doesn't 45gives you a portable JSON API that can be fast when you need and doesn't
46require a C compiler when that is a problem. 46require a C compiler when that is a problem.
47 47
… …
49to write yet another JSON module? While it seems there are many JSON 49to write yet another JSON module? While it seems there are many JSON
50modules, none of them correctly handle all corner cases, and in most cases 50modules, none of them correctly handle all corner cases, and in most cases
51their maintainers are unresponsive, gone missing, or not listening to bug 51their maintainers are unresponsive, gone missing, or not listening to bug
52reports for other reasons. 52reports for other reasons.
53 53
54See COMPARISON, below, for a comparison to some other JSON modules.
55
56See MAPPING, below, on how JSON::XS maps perl values to JSON values and 54See MAPPING, below, on how JSON::XS maps perl values to JSON values and
57vice versa. 55vice versa.
58 56
59=head2 FEATURES 57=head2 FEATURES
60 58
… …
65This module knows how to handle Unicode, documents how and when it does 63This module knows how to handle Unicode, documents how and when it does
66so, and even documents what "correct" means. 64so, and even documents what "correct" means.
67 65
68=item * round-trip integrity 66=item * round-trip integrity
69 67
70When you serialise a perl data structure using only datatypes supported 68When you serialise a perl data structure using only data types supported
71by JSON, the deserialised data structure is identical on the Perl level. 69by JSON and Perl, the deserialised data structure is identical on the Perl
72(e.g. the string "2.0" doesn't suddenly become "2" just because it looks 70level. (e.g. the string "2.0" doesn't suddenly become "2" just because
73like a number). There minor I<are> exceptions to this, read the MAPPING 71it looks like a number). There I<are> minor exceptions to this, read the
74section below to learn about those. 72MAPPING section below to learn about those.
75 73
76=item * strict checking of JSON correctness 74=item * strict checking of JSON correctness
77 75
78There is no guessing, no generating of illegal JSON texts by default, 76There is no guessing, no generating of illegal JSON texts by default,
79and only JSON is accepted as input by default (the latter is a security 77and only JSON is accepted as input by default (the latter is a security
… …
84Compared to other JSON modules and other serialisers such as Storable, 82Compared to other JSON modules and other serialisers such as Storable,
85this module usually compares favourably in terms of speed, too. 83this module usually compares favourably in terms of speed, too.
86 84
87=item * simple to use 85=item * simple to use
88 86
89This module has both a simple functional interface as well as an objetc 87This module has both a simple functional interface as well as an object
90oriented interface interface. 88oriented interface.
91 89
92=item * reasonably versatile output formats 90=item * reasonably versatile output formats
93 91
94You can choose between the most compact guaranteed-single-line format 92You can choose between the most compact guaranteed-single-line format
95possible (nice for simple line-based protocols), a pure-ascii format 93possible (nice for simple line-based protocols), a pure-ASCII format
96(for when your transport is not 8-bit clean, still supports the whole 94(for when your transport is not 8-bit clean, still supports the whole
97Unicode range), or a pretty-printed format (for when you want to read that 95Unicode range), or a pretty-printed format (for when you want to read that
98stuff). Or you can combine those features in whatever way you like. 96stuff). Or you can combine those features in whatever way you like.
99 97
100=back 98=back
101 99
102=cut 100=cut
103 101
104package JSON::XS; 102package JSON::XS;
105 103
106use strict; 104use common::sense;
107 105
108our $VERSION = '2.01'; 106our $VERSION = 2.34;
109our @ISA = qw(Exporter); 107our @ISA = qw(Exporter);
110 108
111our @EXPORT = qw(encode_json decode_json to_json from_json); 109our @EXPORT = qw(encode_json decode_json);
112
113sub to_json($) {
114 require Carp;
115 Carp::croak ("JSON::XS::to_json has been renamed to encode_json, either downgrade to pre-2.0 versions of JSON::XS or rename the call");
116}
117
118sub from_json($) {
119 require Carp;
120 Carp::croak ("JSON::XS::from_json has been renamed to decode_json, either downgrade to pre-2.0 versions of JSON::XS or rename the call");
121}
122 110
123use Exporter; 111use Exporter;
124use XSLoader; 112use XSLoader;
125 113
126=head1 FUNCTIONAL INTERFACE 114=head1 FUNCTIONAL INTERFACE
… …
137 125
138This function call is functionally identical to: 126This function call is functionally identical to:
139 127
140 $json_text = JSON::XS->new->utf8->encode ($perl_scalar) 128 $json_text = JSON::XS->new->utf8->encode ($perl_scalar)
141 129
142except being faster. 130Except being faster.
143 131
144=item $perl_scalar = decode_json $json_text 132=item $perl_scalar = decode_json $json_text
145 133
146The opposite of C<encode_json>: expects an UTF-8 (binary) string and tries 134The opposite of C<encode_json>: expects an UTF-8 (binary) string and tries
147to parse that as an UTF-8 encoded JSON text, returning the resulting 135to parse that as an UTF-8 encoded JSON text, returning the resulting
… …
149 137
150This function call is functionally identical to: 138This function call is functionally identical to:
151 139
152 $perl_scalar = JSON::XS->new->utf8->decode ($json_text) 140 $perl_scalar = JSON::XS->new->utf8->decode ($json_text)
153 141
154except being faster. 142Except being faster.
155 143
156=item $is_boolean = JSON::XS::is_bool $scalar 144=item $is_boolean = JSON::XS::is_bool $scalar
157 145
158Returns true if the passed scalar represents either JSON::XS::true or 146Returns true if the passed scalar represents either JSON::XS::true or
159JSON::XS::false, two constants that act like C<1> and C<0>, respectively 147JSON::XS::false, two constants that act like C<1> and C<0>, respectively
… …
197 185
198If you didn't know about that flag, just the better, pretend it doesn't 186If you didn't know about that flag, just the better, pretend it doesn't
199exist. 187exist.
200 188
201=item 4. A "Unicode String" is simply a string where each character can be 189=item 4. A "Unicode String" is simply a string where each character can be
202validly interpreted as a Unicode codepoint. 190validly interpreted as a Unicode code point.
203 191
204If you have UTF-8 encoded data, it is no longer a Unicode string, but a 192If you have UTF-8 encoded data, it is no longer a Unicode string, but a
205Unicode string encoded in UTF-8, giving you a binary string. 193Unicode string encoded in UTF-8, giving you a binary string.
206 194
207=item 5. A string containing "high" (> 255) character values is I<not> a UTF-8 string. 195=item 5. A string containing "high" (> 255) character values is I<not> a UTF-8 string.
… …
245 233
246If C<$enable> is false, then the C<encode> method will not escape Unicode 234If C<$enable> is false, then the C<encode> method will not escape Unicode
247characters unless required by the JSON syntax or other flags. This results 235characters unless required by the JSON syntax or other flags. This results
248in a faster and more compact format. 236in a faster and more compact format.
249 237
238See also the section I<ENCODING/CODESET FLAG NOTES> later in this
239document.
240
250The main use for this flag is to produce JSON texts that can be 241The main use for this flag is to produce JSON texts that can be
251transmitted over a 7-bit channel, as the encoded JSON texts will not 242transmitted over a 7-bit channel, as the encoded JSON texts will not
252contain any 8 bit characters. 243contain any 8 bit characters.
253 244
254 JSON::XS->new->ascii (1)->encode ([chr 0x10401]) 245 JSON::XS->new->ascii (1)->encode ([chr 0x10401])
… …
265will not be affected in any way by this flag, as C<decode> by default 256will not be affected in any way by this flag, as C<decode> by default
266expects Unicode, which is a strict superset of latin1. 257expects Unicode, which is a strict superset of latin1.
267 258
268If C<$enable> is false, then the C<encode> method will not escape Unicode 259If C<$enable> is false, then the C<encode> method will not escape Unicode
269characters unless required by the JSON syntax or other flags. 260characters unless required by the JSON syntax or other flags.
261
262See also the section I<ENCODING/CODESET FLAG NOTES> later in this
263document.
270 264
271The main use for this flag is efficiently encoding binary data as JSON 265The main use for this flag is efficiently encoding binary data as JSON
272text, as most octets will not be escaped, resulting in a smaller encoded 266text, as most octets will not be escaped, resulting in a smaller encoded
273size. The disadvantage is that the resulting JSON text is encoded 267size. The disadvantage is that the resulting JSON text is encoded
274in latin1 (and must correctly be treated as such when storing and 268in latin1 (and must correctly be treated as such when storing and
… …
293 287
294If C<$enable> is false, then the C<encode> method will return the JSON 288If C<$enable> is false, then the C<encode> method will return the JSON
295string as a (non-encoded) Unicode string, while C<decode> expects thus a 289string as a (non-encoded) Unicode string, while C<decode> expects thus a
296Unicode string. Any decoding or encoding (e.g. to UTF-8 or UTF-16) needs 290Unicode string. Any decoding or encoding (e.g. to UTF-8 or UTF-16) needs
297to be done yourself, e.g. using the Encode module. 291to be done yourself, e.g. using the Encode module.
292
293See also the section I<ENCODING/CODESET FLAG NOTES> later in this
294document.
298 295
299Example, output UTF-16BE-encoded JSON: 296Example, output UTF-16BE-encoded JSON:
300 297
301 use Encode; 298 use Encode;
302 $jsontext = encode "UTF-16BE", JSON::XS->new->encode ($object); 299 $jsontext = encode "UTF-16BE", JSON::XS->new->encode ($object);
… …
425If C<$enable> is true (or missing), then the C<encode> method will output JSON objects 422If C<$enable> is true (or missing), then the C<encode> method will output JSON objects
426by sorting their keys. This is adding a comparatively high overhead. 423by sorting their keys. This is adding a comparatively high overhead.
427 424
428If C<$enable> is false, then the C<encode> method will output key-value 425If C<$enable> is false, then the C<encode> method will output key-value
429pairs in the order Perl stores them (which will likely change between runs 426pairs in the order Perl stores them (which will likely change between runs
430of the same script). 427of the same script, and can change even within the same run from 5.18
428onwards).
431 429
432This option is useful if you want the same data structure to be encoded as 430This option is useful if you want the same data structure to be encoded as
433the same JSON text (given the same overall settings). If it is disabled, 431the same JSON text (given the same overall settings). If it is disabled,
434the same hash might be encoded differently even if contains the same data, 432the same hash might be encoded differently even if contains the same data,
435as key-value pairs have no inherent ordering in Perl. 433as key-value pairs have no inherent ordering in Perl.
436 434
437This setting has no effect when decoding JSON texts. 435This setting has no effect when decoding JSON texts.
438 436
437This setting has currently no effect on tied hashes.
438
439=item $json = $json->allow_nonref ([$enable]) 439=item $json = $json->allow_nonref ([$enable])
440 440
441=item $enabled = $json->get_allow_nonref 441=item $enabled = $json->get_allow_nonref
442 442
443If C<$enable> is true (or missing), then the C<encode> method can convert a 443If C<$enable> is true (or missing), then the C<encode> method can convert a
… …
453Example, encode a Perl scalar as JSON value with enabled C<allow_nonref>, 453Example, encode a Perl scalar as JSON value with enabled C<allow_nonref>,
454resulting in an invalid JSON text: 454resulting in an invalid JSON text:
455 455
456 JSON::XS->new->allow_nonref->encode ("Hello, World!") 456 JSON::XS->new->allow_nonref->encode ("Hello, World!")
457 => "Hello, World!" 457 => "Hello, World!"
458
459=item $json = $json->allow_unknown ([$enable])
460
461=item $enabled = $json->get_allow_unknown
462
463If C<$enable> is true (or missing), then C<encode> will I<not> throw an
464exception when it encounters values it cannot represent in JSON (for
465example, filehandles) but instead will encode a JSON C<null> value. Note
466that blessed objects are not included here and are handled separately by
467c<allow_nonref>.
468
469If C<$enable> is false (the default), then C<encode> will throw an
470exception when it encounters anything it cannot encode as JSON.
471
472This option does not affect C<decode> in any way, and it is recommended to
473leave it off unless you know your communications partner.
458 474
459=item $json = $json->allow_blessed ([$enable]) 475=item $json = $json->allow_blessed ([$enable])
460 476
461=item $enabled = $json->get_allow_blessed 477=item $enabled = $json->get_allow_blessed
462 478
… …
603=item $json = $json->max_depth ([$maximum_nesting_depth]) 619=item $json = $json->max_depth ([$maximum_nesting_depth])
604 620
605=item $max_depth = $json->get_max_depth 621=item $max_depth = $json->get_max_depth
606 622
607Sets the maximum nesting level (default C<512>) accepted while encoding 623Sets the maximum nesting level (default C<512>) accepted while encoding
608or decoding. If the JSON text or Perl data structure has an equal or 624or decoding. If a higher nesting level is detected in JSON text or a Perl
609higher nesting level then this limit, then the encoder and decoder will 625data structure, then the encoder and decoder will stop and croak at that
610stop and croak at that point. 626point.
611 627
612Nesting level is defined by number of hash- or arrayrefs that the encoder 628Nesting level is defined by number of hash- or arrayrefs that the encoder
613needs to traverse to reach a given point or the number of C<{> or C<[> 629needs to traverse to reach a given point or the number of C<{> or C<[>
614characters without their matching closing parenthesis crossed to reach a 630characters without their matching closing parenthesis crossed to reach a
615given character in a string. 631given character in a string.
616 632
617Setting the maximum depth to one disallows any nesting, so that ensures 633Setting the maximum depth to one disallows any nesting, so that ensures
618that the object is only a single hash/object or array. 634that the object is only a single hash/object or array.
619 635
620The argument to C<max_depth> will be rounded up to the next highest power
621of two. If no argument is given, the highest possible setting will be 636If no argument is given, the highest possible setting will be used, which
622used, which is rarely useful. 637is rarely useful.
638
639Note that nesting is implemented by recursion in C. The default value has
640been chosen to be as large as typical operating systems allow without
641crashing.
623 642
624See SECURITY CONSIDERATIONS, below, for more info on why this is useful. 643See SECURITY CONSIDERATIONS, below, for more info on why this is useful.
625 644
626=item $json = $json->max_size ([$maximum_string_size]) 645=item $json = $json->max_size ([$maximum_string_size])
627 646
628=item $max_size = $json->get_max_size 647=item $max_size = $json->get_max_size
629 648
630Set the maximum length a JSON text may have (in bytes) where decoding is 649Set the maximum length a JSON text may have (in bytes) where decoding is
631being attempted. The default is C<0>, meaning no limit. When C<decode> 650being attempted. The default is C<0>, meaning no limit. When C<decode>
632is called on a string longer then this number of characters it will not 651is called on a string that is longer then this many bytes, it will not
633attempt to decode the string but throw an exception. This setting has no 652attempt to decode the string but throw an exception. This setting has no
634effect on C<encode> (yet). 653effect on C<encode> (yet).
635 654
636The argument to C<max_size> will be rounded up to the next B<highest> 655If no argument is given, the limit check will be deactivated (same as when
637power of two (so may be more than requested). If no argument is given, the 656C<0> is specified).
638limit check will be deactivated (same as when C<0> is specified).
639 657
640See SECURITY CONSIDERATIONS, below, for more info on why this is useful. 658See SECURITY CONSIDERATIONS, below, for more info on why this is useful.
641 659
642=item $json_text = $json->encode ($perl_scalar) 660=item $json_text = $json->encode ($perl_scalar)
643 661
644Converts the given Perl data structure (a simple scalar or a reference 662Converts the given Perl value or data structure to its JSON
645to a hash or array) to its JSON representation. Simple scalars will be 663representation. Croaks on error.
646converted into JSON string or number sequences, while references to arrays
647become JSON arrays and references to hashes become JSON objects. Undefined
648Perl values (e.g. C<undef>) become JSON C<null> values. Neither C<true>
649nor C<false> values will be generated.
650 664
651=item $perl_scalar = $json->decode ($json_text) 665=item $perl_scalar = $json->decode ($json_text)
652 666
653The opposite of C<encode>: expects a JSON text and tries to parse it, 667The opposite of C<encode>: expects a JSON text and tries to parse it,
654returning the resulting simple scalar or reference. Croaks on error. 668returning the resulting simple scalar or reference. Croaks on error.
655
656JSON numbers and strings become simple Perl scalars. JSON arrays become
657Perl arrayrefs and JSON objects become Perl hashrefs. C<true> becomes
658C<1>, C<false> becomes C<0> and C<null> becomes C<undef>.
659 669
660=item ($perl_scalar, $characters) = $json->decode_prefix ($json_text) 670=item ($perl_scalar, $characters) = $json->decode_prefix ($json_text)
661 671
662This works like the C<decode> method, but instead of raising an exception 672This works like the C<decode> method, but instead of raising an exception
663when there is trailing garbage after the first JSON object, it will 673when there is trailing garbage after the first JSON object, it will
… …
670 680
671 JSON::XS->new->decode_prefix ("[1] the tail") 681 JSON::XS->new->decode_prefix ("[1] the tail")
672 => ([], 3) 682 => ([], 3)
673 683
674=back 684=back
685
686
687=head1 INCREMENTAL PARSING
688
689In some cases, there is the need for incremental parsing of JSON
690texts. While this module always has to keep both JSON text and resulting
691Perl data structure in memory at one time, it does allow you to parse a
692JSON stream incrementally. It does so by accumulating text until it has
693a full JSON object, which it then can decode. This process is similar to
694using C<decode_prefix> to see if a full JSON object is available, but
695is much more efficient (and can be implemented with a minimum of method
696calls).
697
698JSON::XS will only attempt to parse the JSON text once it is sure it
699has enough text to get a decisive result, using a very simple but
700truly incremental parser. This means that it sometimes won't stop as
701early as the full parser, for example, it doesn't detect mismatched
702parentheses. The only thing it guarantees is that it starts decoding as
703soon as a syntactically valid JSON text has been seen. This means you need
704to set resource limits (e.g. C<max_size>) to ensure the parser will stop
705parsing in the presence if syntax errors.
706
707The following methods implement this incremental parser.
708
709=over 4
710
711=item [void, scalar or list context] = $json->incr_parse ([$string])
712
713This is the central parsing function. It can both append new text and
714extract objects from the stream accumulated so far (both of these
715functions are optional).
716
717If C<$string> is given, then this string is appended to the already
718existing JSON fragment stored in the C<$json> object.
719
720After that, if the function is called in void context, it will simply
721return without doing anything further. This can be used to add more text
722in as many chunks as you want.
723
724If the method is called in scalar context, then it will try to extract
725exactly I<one> JSON object. If that is successful, it will return this
726object, otherwise it will return C<undef>. If there is a parse error,
727this method will croak just as C<decode> would do (one can then use
728C<incr_skip> to skip the erroneous part). This is the most common way of
729using the method.
730
731And finally, in list context, it will try to extract as many objects
732from the stream as it can find and return them, or the empty list
733otherwise. For this to work, there must be no separators between the JSON
734objects or arrays, instead they must be concatenated back-to-back. If
735an error occurs, an exception will be raised as in the scalar context
736case. Note that in this case, any previously-parsed JSON texts will be
737lost.
738
739Example: Parse some JSON arrays/objects in a given string and return
740them.
741
742 my @objs = JSON::XS->new->incr_parse ("[5][7][1,2]");
743
744=item $lvalue_string = $json->incr_text
745
746This method returns the currently stored JSON fragment as an lvalue, that
747is, you can manipulate it. This I<only> works when a preceding call to
748C<incr_parse> in I<scalar context> successfully returned an object. Under
749all other circumstances you must not call this function (I mean it.
750although in simple tests it might actually work, it I<will> fail under
751real world conditions). As a special exception, you can also call this
752method before having parsed anything.
753
754This function is useful in two cases: a) finding the trailing text after a
755JSON object or b) parsing multiple JSON objects separated by non-JSON text
756(such as commas).
757
758=item $json->incr_skip
759
760This will reset the state of the incremental parser and will remove
761the parsed text from the input buffer so far. This is useful after
762C<incr_parse> died, in which case the input buffer and incremental parser
763state is left unchanged, to skip the text parsed so far and to reset the
764parse state.
765
766The difference to C<incr_reset> is that only text until the parse error
767occurred is removed.
768
769=item $json->incr_reset
770
771This completely resets the incremental parser, that is, after this call,
772it will be as if the parser had never parsed anything.
773
774This is useful if you want to repeatedly parse JSON objects and want to
775ignore any trailing data, which means you have to reset the parser after
776each successful decode.
777
778=back
779
780=head2 LIMITATIONS
781
782All options that affect decoding are supported, except
783C<allow_nonref>. The reason for this is that it cannot be made to
784work sensibly: JSON objects and arrays are self-delimited, i.e. you can concatenate
785them back to back and still decode them perfectly. This does not hold true
786for JSON numbers, however.
787
788For example, is the string C<1> a single JSON number, or is it simply the
789start of C<12>? Or is C<12> a single JSON number, or the concatenation
790of C<1> and C<2>? In neither case you can tell, and this is why JSON::XS
791takes the conservative route and disallows this case.
792
793=head2 EXAMPLES
794
795Some examples will make all this clearer. First, a simple example that
796works similarly to C<decode_prefix>: We want to decode the JSON object at
797the start of a string and identify the portion after the JSON object:
798
799 my $text = "[1,2,3] hello";
800
801 my $json = new JSON::XS;
802
803 my $obj = $json->incr_parse ($text)
804 or die "expected JSON object or array at beginning of string";
805
806 my $tail = $json->incr_text;
807 # $tail now contains " hello"
808
809Easy, isn't it?
810
811Now for a more complicated example: Imagine a hypothetical protocol where
812you read some requests from a TCP stream, and each request is a JSON
813array, without any separation between them (in fact, it is often useful to
814use newlines as "separators", as these get interpreted as whitespace at
815the start of the JSON text, which makes it possible to test said protocol
816with C<telnet>...).
817
818Here is how you'd do it (it is trivial to write this in an event-based
819manner):
820
821 my $json = new JSON::XS;
822
823 # read some data from the socket
824 while (sysread $socket, my $buf, 4096) {
825
826 # split and decode as many requests as possible
827 for my $request ($json->incr_parse ($buf)) {
828 # act on the $request
829 }
830 }
831
832Another complicated example: Assume you have a string with JSON objects
833or arrays, all separated by (optional) comma characters (e.g. C<[1],[2],
834[3]>). To parse them, we have to skip the commas between the JSON texts,
835and here is where the lvalue-ness of C<incr_text> comes in useful:
836
837 my $text = "[1],[2], [3]";
838 my $json = new JSON::XS;
839
840 # void context, so no parsing done
841 $json->incr_parse ($text);
842
843 # now extract as many objects as possible. note the
844 # use of scalar context so incr_text can be called.
845 while (my $obj = $json->incr_parse) {
846 # do something with $obj
847
848 # now skip the optional comma
849 $json->incr_text =~ s/^ \s* , //x;
850 }
851
852Now lets go for a very complex example: Assume that you have a gigantic
853JSON array-of-objects, many gigabytes in size, and you want to parse it,
854but you cannot load it into memory fully (this has actually happened in
855the real world :).
856
857Well, you lost, you have to implement your own JSON parser. But JSON::XS
858can still help you: You implement a (very simple) array parser and let
859JSON decode the array elements, which are all full JSON objects on their
860own (this wouldn't work if the array elements could be JSON numbers, for
861example):
862
863 my $json = new JSON::XS;
864
865 # open the monster
866 open my $fh, "<bigfile.json"
867 or die "bigfile: $!";
868
869 # first parse the initial "["
870 for (;;) {
871 sysread $fh, my $buf, 65536
872 or die "read error: $!";
873 $json->incr_parse ($buf); # void context, so no parsing
874
875 # Exit the loop once we found and removed(!) the initial "[".
876 # In essence, we are (ab-)using the $json object as a simple scalar
877 # we append data to.
878 last if $json->incr_text =~ s/^ \s* \[ //x;
879 }
880
881 # now we have the skipped the initial "[", so continue
882 # parsing all the elements.
883 for (;;) {
884 # in this loop we read data until we got a single JSON object
885 for (;;) {
886 if (my $obj = $json->incr_parse) {
887 # do something with $obj
888 last;
889 }
890
891 # add more data
892 sysread $fh, my $buf, 65536
893 or die "read error: $!";
894 $json->incr_parse ($buf); # void context, so no parsing
895 }
896
897 # in this loop we read data until we either found and parsed the
898 # separating "," between elements, or the final "]"
899 for (;;) {
900 # first skip whitespace
901 $json->incr_text =~ s/^\s*//;
902
903 # if we find "]", we are done
904 if ($json->incr_text =~ s/^\]//) {
905 print "finished.\n";
906 exit;
907 }
908
909 # if we find ",", we can continue with the next element
910 if ($json->incr_text =~ s/^,//) {
911 last;
912 }
913
914 # if we find anything else, we have a parse error!
915 if (length $json->incr_text) {
916 die "parse error near ", $json->incr_text;
917 }
918
919 # else add more data
920 sysread $fh, my $buf, 65536
921 or die "read error: $!";
922 $json->incr_parse ($buf); # void context, so no parsing
923 }
924
925This is a complex example, but most of the complexity comes from the fact
926that we are trying to be correct (bear with me if I am wrong, I never ran
927the above example :).
928
675 929
676 930
677=head1 MAPPING 931=head1 MAPPING
678 932
679This section describes how JSON::XS maps Perl values to JSON values and 933This section describes how JSON::XS maps Perl values to JSON values and
… …
716If the number consists of digits only, JSON::XS will try to represent 970If the number consists of digits only, JSON::XS will try to represent
717it as an integer value. If that fails, it will try to represent it as 971it as an integer value. If that fails, it will try to represent it as
718a numeric (floating point) value if that is possible without loss of 972a numeric (floating point) value if that is possible without loss of
719precision. Otherwise it will preserve the number as a string value (in 973precision. Otherwise it will preserve the number as a string value (in
720which case you lose roundtripping ability, as the JSON number will be 974which case you lose roundtripping ability, as the JSON number will be
721re-encoded toa JSON string). 975re-encoded to a JSON string).
722 976
723Numbers containing a fractional or exponential part will always be 977Numbers containing a fractional or exponential part will always be
724represented as numeric (floating point) values, possibly at a loss of 978represented as numeric (floating point) values, possibly at a loss of
725precision (in which case you might lose perfect roundtripping ability, but 979precision (in which case you might lose perfect roundtripping ability, but
726the JSON number will still be re-encoded as a JSON number). 980the JSON number will still be re-encoded as a JSON number).
727 981
982Note that precision is not accuracy - binary floating point values cannot
983represent most decimal fractions exactly, and when converting from and to
984floating point, JSON::XS only guarantees precision up to but not including
985the least significant bit.
986
728=item true, false 987=item true, false
729 988
730These JSON atoms become C<JSON::XS::true> and C<JSON::XS::false>, 989These JSON atoms become C<JSON::XS::true> and C<JSON::XS::false>,
731respectively. They are overloaded to act almost exactly like the numbers 990respectively. They are overloaded to act almost exactly like the numbers
732C<1> and C<0>. You can check whether a scalar is a JSON boolean by using 991C<1> and C<0>. You can check whether a scalar is a JSON boolean by using
… …
747 1006
748=over 4 1007=over 4
749 1008
750=item hash references 1009=item hash references
751 1010
752Perl hash references become JSON objects. As there is no inherent ordering 1011Perl hash references become JSON objects. As there is no inherent
753in hash keys (or JSON objects), they will usually be encoded in a 1012ordering in hash keys (or JSON objects), they will usually be encoded
754pseudo-random order that can change between runs of the same program but 1013in a pseudo-random order. JSON::XS can optionally sort the hash keys
755stays generally the same within a single run of a program. JSON::XS can 1014(determined by the I<canonical> flag), so the same datastructure will
756optionally sort the hash keys (determined by the I<canonical> flag), so 1015serialise to the same JSON text (given same settings and version of
757the same datastructure will serialise to the same JSON text (given same 1016JSON::XS), but this incurs a runtime overhead and is only rarely useful,
758settings and version of JSON::XS), but this incurs a runtime overhead 1017e.g. when you want to compare some JSON text against another for equality.
759and is only rarely useful, e.g. when you want to compare some JSON text
760against another for equality.
761 1018
762=item array references 1019=item array references
763 1020
764Perl array references become JSON arrays. 1021Perl array references become JSON arrays.
765 1022
… …
768Other unblessed references are generally not allowed and will cause an 1025Other unblessed references are generally not allowed and will cause an
769exception to be thrown, except for references to the integers C<0> and 1026exception to be thrown, except for references to the integers C<0> and
770C<1>, which get turned into C<false> and C<true> atoms in JSON. You can 1027C<1>, which get turned into C<false> and C<true> atoms in JSON. You can
771also use C<JSON::XS::false> and C<JSON::XS::true> to improve readability. 1028also use C<JSON::XS::false> and C<JSON::XS::true> to improve readability.
772 1029
773 encode_json [\0,JSON::XS::true] # yields [false,true] 1030 encode_json [\0, JSON::XS::true] # yields [false,true]
774 1031
775=item JSON::XS::true, JSON::XS::false 1032=item JSON::XS::true, JSON::XS::false
776 1033
777These special values become JSON true and JSON false values, 1034These special values become JSON true and JSON false values,
778respectively. You can also use C<\1> and C<\0> directly if you want. 1035respectively. You can also use C<\1> and C<\0> directly if you want.
… …
816 my $x = "3"; # some variable containing a string 1073 my $x = "3"; # some variable containing a string
817 $x += 0; # numify it, ensuring it will be dumped as a number 1074 $x += 0; # numify it, ensuring it will be dumped as a number
818 $x *= 1; # same thing, the choice is yours. 1075 $x *= 1; # same thing, the choice is yours.
819 1076
820You can not currently force the type in other, less obscure, ways. Tell me 1077You can not currently force the type in other, less obscure, ways. Tell me
821if you need this capability (but don't forget to explain why its needed 1078if you need this capability (but don't forget to explain why it's needed
822:). 1079:).
1080
1081Note that numerical precision has the same meaning as under Perl (so
1082binary to decimal conversion follows the same rules as in Perl, which
1083can differ to other languages). Also, your perl interpreter might expose
1084extensions to the floating point numbers of your platform, such as
1085infinities or NaN's - these cannot be represented in JSON, and it is an
1086error to pass those in.
823 1087
824=back 1088=back
825 1089
826 1090
827=head1 ENCODING/CODESET FLAG NOTES 1091=head1 ENCODING/CODESET FLAG NOTES
828 1092
829The interested reader might have seen a number of flags that signify 1093The interested reader might have seen a number of flags that signify
830encodings or codesets - C<utf8>, C<latin1> and C<ascii>. There seems to be 1094encodings or codesets - C<utf8>, C<latin1> and C<ascii>. There seems to be
831some confusion on what these do, so here is a short comparison: 1095some confusion on what these do, so here is a short comparison:
832 1096
833C<utf8> controls wether the JSON text created by C<encode> (and expected 1097C<utf8> controls whether the JSON text created by C<encode> (and expected
834by C<decode>) is UTF-8 encoded or not, while C<latin1> and C<ascii> only 1098by C<decode>) is UTF-8 encoded or not, while C<latin1> and C<ascii> only
835control wether C<encode> escapes character values outside their respective 1099control whether C<encode> escapes character values outside their respective
836codeset range. Neither of these flags conflict with each other, although 1100codeset range. Neither of these flags conflict with each other, although
837some combinations make less sense than others. 1101some combinations make less sense than others.
838 1102
839Care has been taken to make all flags symmetrical with respect to 1103Care has been taken to make all flags symmetrical with respect to
840C<encode> and C<decode>, that is, texts encoded with any combination of 1104C<encode> and C<decode>, that is, texts encoded with any combination of
… …
854=item C<utf8> flag disabled 1118=item C<utf8> flag disabled
855 1119
856When C<utf8> is disabled (the default), then C<encode>/C<decode> generate 1120When C<utf8> is disabled (the default), then C<encode>/C<decode> generate
857and expect Unicode strings, that is, characters with high ordinal Unicode 1121and expect Unicode strings, that is, characters with high ordinal Unicode
858values (> 255) will be encoded as such characters, and likewise such 1122values (> 255) will be encoded as such characters, and likewise such
859characters are decoded as-is, no canges to them will be done, except 1123characters are decoded as-is, no changes to them will be done, except
860"(re-)interpreting" them as Unicode codepoints or Unicode characters, 1124"(re-)interpreting" them as Unicode codepoints or Unicode characters,
861respectively (to Perl, these are the same thing in strings unless you do 1125respectively (to Perl, these are the same thing in strings unless you do
862funny/weird/dumb stuff). 1126funny/weird/dumb stuff).
863 1127
864This is useful when you want to do the encoding yourself (e.g. when you 1128This is useful when you want to do the encoding yourself (e.g. when you
… …
920proper subset of most 8-bit and multibyte encodings in use in the world. 1184proper subset of most 8-bit and multibyte encodings in use in the world.
921 1185
922=back 1186=back
923 1187
924 1188
925=head1 COMPARISON 1189=head2 JSON and ECMAscript
926 1190
927As already mentioned, this module was created because none of the existing 1191JSON syntax is based on how literals are represented in javascript (the
928JSON modules could be made to work correctly. First I will describe the 1192not-standardised predecessor of ECMAscript) which is presumably why it is
929problems (or pleasures) I encountered with various existing JSON modules, 1193called "JavaScript Object Notation".
930followed by some benchmark values. JSON::XS was designed not to suffer
931from any of these problems or limitations.
932 1194
933=over 4 1195However, JSON is not a subset (and also not a superset of course) of
1196ECMAscript (the standard) or javascript (whatever browsers actually
1197implement).
934 1198
935=item JSON 2.xx 1199If you want to use javascript's C<eval> function to "parse" JSON, you
1200might run into parse errors for valid JSON texts, or the resulting data
1201structure might not be queryable:
936 1202
937A marvellous piece of engineering, this module either uses JSON::XS 1203One of the problems is that U+2028 and U+2029 are valid characters inside
938directly when available (so will be 100% compatible with it, including 1204JSON strings, but are not allowed in ECMAscript string literals, so the
939speed), or it uses JSON::PP, which is basically JSON::XS translated to 1205following Perl fragment will not output something that can be guaranteed
940Pure Perl, which should be 100% compatible with JSON::XS, just a bit 1206to be parsable by javascript's C<eval>:
941slower.
942 1207
943You cannot really lose by using this module, especially as it tries very 1208 use JSON::XS;
944hard to work even with ancient Perl versions, while JSON::XS does not.
945 1209
946=item JSON 1.07 1210 print encode_json [chr 0x2028];
947 1211
948Slow (but very portable, as it is written in pure Perl). 1212The right fix for this is to use a proper JSON parser in your javascript
1213programs, and not rely on C<eval> (see for example Douglas Crockford's
1214F<json2.js> parser).
949 1215
950Undocumented/buggy Unicode handling (how JSON handles Unicode values is 1216If this is not an option, you can, as a stop-gap measure, simply encode to
951undocumented. One can get far by feeding it Unicode strings and doing 1217ASCII-only JSON:
952en-/decoding oneself, but Unicode escapes are not working properly).
953 1218
954No round-tripping (strings get clobbered if they look like numbers, e.g. 1219 use JSON::XS;
955the string C<2.0> will encode to C<2.0> instead of C<"2.0">, and that will
956decode into the number 2.
957 1220
958=item JSON::PC 0.01 1221 print JSON::XS->new->ascii->encode ([chr 0x2028]);
959 1222
960Very fast. 1223Note that this will enlarge the resulting JSON text quite a bit if you
1224have many non-ASCII characters. You might be tempted to run some regexes
1225to only escape U+2028 and U+2029, e.g.:
961 1226
962Undocumented/buggy Unicode handling. 1227 # DO NOT USE THIS!
1228 my $json = JSON::XS->new->utf8->encode ([chr 0x2028]);
1229 $json =~ s/\xe2\x80\xa8/\\u2028/g; # escape U+2028
1230 $json =~ s/\xe2\x80\xa9/\\u2029/g; # escape U+2029
1231 print $json;
963 1232
964No round-tripping. 1233Note that I<this is a bad idea>: the above only works for U+2028 and
1234U+2029 and thus only for fully ECMAscript-compliant parsers. Many existing
1235javascript implementations, however, have issues with other characters as
1236well - using C<eval> naively simply I<will> cause problems.
965 1237
966Has problems handling many Perl values (e.g. regex results and other magic 1238Another problem is that some javascript implementations reserve
967values will make it croak). 1239some property names for their own purposes (which probably makes
1240them non-ECMAscript-compliant). For example, Iceweasel reserves the
1241C<__proto__> property name for its own purposes.
968 1242
969Does not even generate valid JSON (C<{1,2}> gets converted to C<{1:2}> 1243If that is a problem, you could parse try to filter the resulting JSON
970which is not a valid JSON text. 1244output for these property strings, e.g.:
971 1245
972Unmaintained (maintainer unresponsive for many months, bugs are not 1246 $json =~ s/"__proto__"\s*:/"__proto__renamed":/g;
973getting fixed).
974 1247
975=item JSON::Syck 0.21 1248This works because C<__proto__> is not valid outside of strings, so every
1249occurrence of C<"__proto__"\s*:> must be a string used as property name.
976 1250
977Very buggy (often crashes). 1251If you know of other incompatibilities, please let me know.
978
979Very inflexible (no human-readable format supported, format pretty much
980undocumented. I need at least a format for easy reading by humans and a
981single-line compact format for use in a protocol, and preferably a way to
982generate ASCII-only JSON texts).
983
984Completely broken (and confusingly documented) Unicode handling (Unicode
985escapes are not working properly, you need to set ImplicitUnicode to
986I<different> values on en- and decoding to get symmetric behaviour).
987
988No round-tripping (simple cases work, but this depends on whether the scalar
989value was used in a numeric context or not).
990
991Dumping hashes may skip hash values depending on iterator state.
992
993Unmaintained (maintainer unresponsive for many months, bugs are not
994getting fixed).
995
996Does not check input for validity (i.e. will accept non-JSON input and
997return "something" instead of raising an exception. This is a security
998issue: imagine two banks transferring money between each other using
999JSON. One bank might parse a given non-JSON request and deduct money,
1000while the other might reject the transaction with a syntax error. While a
1001good protocol will at least recover, that is extra unnecessary work and
1002the transaction will still not succeed).
1003
1004=item JSON::DWIW 0.04
1005
1006Very fast. Very natural. Very nice.
1007
1008Undocumented Unicode handling (but the best of the pack. Unicode escapes
1009still don't get parsed properly).
1010
1011Very inflexible.
1012
1013No round-tripping.
1014
1015Does not generate valid JSON texts (key strings are often unquoted, empty keys
1016result in nothing being output)
1017
1018Does not check input for validity.
1019
1020=back
1021 1252
1022 1253
1023=head2 JSON and YAML 1254=head2 JSON and YAML
1024 1255
1025You often hear that JSON is a subset of YAML. This is, however, a mass 1256You often hear that JSON is a subset of YAML. This is, however, a mass
1026hysteria(*) and very far from the truth. In general, there is no way to 1257hysteria(*) and very far from the truth (as of the time of this writing),
1258so let me state it clearly: I<in general, there is no way to configure
1027configure JSON::XS to output a data structure as valid YAML that works for 1259JSON::XS to output a data structure as valid YAML> that works in all
1028all cases. 1260cases.
1029 1261
1030If you really must use JSON::XS to generate YAML, you should use this 1262If you really must use JSON::XS to generate YAML, you should use this
1031algorithm (subject to change in future versions): 1263algorithm (subject to change in future versions):
1032 1264
1033 my $to_yaml = JSON::XS->new->utf8->space_after (1); 1265 my $to_yaml = JSON::XS->new->utf8->space_after (1);
1034 my $yaml = $to_yaml->encode ($ref) . "\n"; 1266 my $yaml = $to_yaml->encode ($ref) . "\n";
1035 1267
1036This will I<usually> generate JSON texts that also parse as valid 1268This will I<usually> generate JSON texts that also parse as valid
1037YAML. Please note that YAML has hardcoded limits on (simple) object key 1269YAML. Please note that YAML has hardcoded limits on (simple) object key
1038lengths that JSON doesn't have and also has different and incompatible 1270lengths that JSON doesn't have and also has different and incompatible
1039unicode handling, so you should make sure that your hash keys are 1271unicode character escape syntax, so you should make sure that your hash
1040noticeably shorter than the 1024 "stream characters" YAML allows and that 1272keys are noticeably shorter than the 1024 "stream characters" YAML allows
1041you do not have codepoints with values outside the Unicode BMP (basic 1273and that you do not have characters with codepoint values outside the
1042multilingual page). YAML also does not allow C<\/> sequences in strings 1274Unicode BMP (basic multilingual page). YAML also does not allow C<\/>
1043(which JSON::XS does not I<currently> generate). 1275sequences in strings (which JSON::XS does not I<currently> generate, but
1276other JSON generators might).
1044 1277
1045There might be other incompatibilities that I am not aware of (or the YAML 1278There might be other incompatibilities that I am not aware of (or the YAML
1046specification has been changed yet again - it does so quite often). In 1279specification has been changed yet again - it does so quite often). In
1047general you should not try to generate YAML with a JSON generator or vice 1280general you should not try to generate YAML with a JSON generator or vice
1048versa, or try to parse JSON with a YAML parser or vice versa: chances are 1281versa, or try to parse JSON with a YAML parser or vice versa: chances are
… …
1051 1284
1052=over 4 1285=over 4
1053 1286
1054=item (*) 1287=item (*)
1055 1288
1056This is spread actively by the YAML team, however. For many years now they 1289I have been pressured multiple times by Brian Ingerson (one of the
1057claim YAML were a superset of JSON, even when proven otherwise. 1290authors of the YAML specification) to remove this paragraph, despite him
1291acknowledging that the actual incompatibilities exist. As I was personally
1292bitten by this "JSON is YAML" lie, I refused and said I will continue to
1293educate people about these issues, so others do not run into the same
1294problem again and again. After this, Brian called me a (quote)I<complete
1295and worthless idiot>(unquote).
1058 1296
1059Even the author of this manpage was at some point accused of providing 1297In my opinion, instead of pressuring and insulting people who actually
1060"incorrect" information, despite the evidence presented (claims ranged 1298clarify issues with YAML and the wrong statements of some of its
1061from "your documentation contains inaccurate and negative statements about 1299proponents, I would kindly suggest reading the JSON spec (which is not
1062YAML" (the only negative comment is this footnote, and it didn't exist 1300that difficult or long) and finally make YAML compatible to it, and
1063back then; the question on which claims were inaccurate was never answered 1301educating users about the changes, instead of spreading lies about the
1064etc.) to "the YAML spec is not up-to-date" (the *real* and supposedly 1302real compatibility for many I<years> and trying to silence people who
1065JSON-compatible spec is apparently not currently publicly available) 1303point out that it isn't true.
1066to actual requests to replace this section by *incorrect* information,
1067suppressing information about the real problem).
1068 1304
1069So whenever you are told that YAML was a superset of JSON, first check 1305Addendum/2009: the YAML 1.2 spec is still incompatible with JSON, even
1070wether it is really true (it might be when you check it, but it certainly 1306though the incompatibilities have been documented (and are known to Brian)
1071was not true when this was written). I would much prefer if the YAML team 1307for many years and the spec makes explicit claims that YAML is a superset
1072would spent their time on actually making JSON compatibility a truth 1308of JSON. It would be so easy to fix, but apparently, bullying people and
1073(JSON, after all, has a very small and simple specification) instead of 1309corrupting userdata is so much easier.
1074trying to lobby/force people into reporting untruths.
1075 1310
1076=back 1311=back
1077 1312
1078 1313
1079=head2 SPEED 1314=head2 SPEED
… …
1081It seems that JSON::XS is surprisingly fast, as shown in the following 1316It seems that JSON::XS is surprisingly fast, as shown in the following
1082tables. They have been generated with the help of the C<eg/bench> program 1317tables. They have been generated with the help of the C<eg/bench> program
1083in the JSON::XS distribution, to make it easy to compare on your own 1318in the JSON::XS distribution, to make it easy to compare on your own
1084system. 1319system.
1085 1320
1086First comes a comparison between various modules using a very short 1321First comes a comparison between various modules using
1087single-line JSON string: 1322a very short single-line JSON string (also available at
1323L<http://dist.schmorp.de/misc/json/short.json>).
1088 1324
1089 {"method": "handleMessage", "params": ["user1", "we were just talking"], \ 1325 {"method": "handleMessage", "params": ["user1",
1090 "id": null, "array":[1,11,234,-5,1e5,1e7, true, false]} 1326 "we were just talking"], "id": null, "array":[1,11,234,-5,1e5,1e7,
1327 1, 0]}
1091 1328
1092It shows the number of encodes/decodes per second (JSON::XS uses 1329It shows the number of encodes/decodes per second (JSON::XS uses
1093the functional interface, while JSON::XS/2 uses the OO interface 1330the functional interface, while JSON::XS/2 uses the OO interface
1094with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables 1331with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables
1095shrink). Higher is better: 1332shrink. JSON::DWIW/DS uses the deserialise function, while JSON::DWIW::FJ
1333uses the from_json method). Higher is better:
1096 1334
1097 module | encode | decode | 1335 module | encode | decode |
1098 -----------|------------|------------| 1336 --------------|------------|------------|
1099 JSON 1.x | 4990.842 | 4088.813 | 1337 JSON::DWIW/DS | 86302.551 | 102300.098 |
1100 JSON::DWIW | 51653.990 | 71575.154 | 1338 JSON::DWIW/FJ | 86302.551 | 75983.768 |
1101 JSON::PC | 65948.176 | 74631.744 | 1339 JSON::PP | 15827.562 | 6638.658 |
1102 JSON::PP | 8931.652 | 3817.168 | 1340 JSON::Syck | 63358.066 | 47662.545 |
1103 JSON::Syck | 24877.248 | 27776.848 | 1341 JSON::XS | 511500.488 | 511500.488 |
1104 JSON::XS | 388361.481 | 227951.304 | 1342 JSON::XS/2 | 291271.111 | 388361.481 |
1105 JSON::XS/2 | 227951.304 | 218453.333 | 1343 JSON::XS/3 | 361577.931 | 361577.931 |
1106 JSON::XS/3 | 338250.323 | 218453.333 | 1344 Storable | 66788.280 | 265462.278 |
1107 Storable | 16500.016 | 135300.129 |
1108 -----------+------------+------------+ 1345 --------------+------------+------------+
1109 1346
1110That is, JSON::XS is about five times faster than JSON::DWIW on encoding, 1347That is, JSON::XS is almost six times faster than JSON::DWIW on encoding,
1111about three times faster on decoding, and over forty times faster 1348about five times faster on decoding, and over thirty to seventy times
1112than JSON, even with pretty-printing and key sorting. It also compares 1349faster than JSON's pure perl implementation. It also compares favourably
1113favourably to Storable for small amounts of data. 1350to Storable for small amounts of data.
1114 1351
1115Using a longer test string (roughly 18KB, generated from Yahoo! Locals 1352Using a longer test string (roughly 18KB, generated from Yahoo! Locals
1116search API (http://nanoref.com/yahooapis/mgPdGg): 1353search API (L<http://dist.schmorp.de/misc/json/long.json>).
1117 1354
1118 module | encode | decode | 1355 module | encode | decode |
1119 -----------|------------|------------| 1356 --------------|------------|------------|
1120 JSON 1.x | 55.260 | 34.971 | 1357 JSON::DWIW/DS | 1647.927 | 2673.916 |
1121 JSON::DWIW | 825.228 | 1082.513 | 1358 JSON::DWIW/FJ | 1630.249 | 2596.128 |
1122 JSON::PC | 3571.444 | 2394.829 |
1123 JSON::PP | 210.987 | 32.574 | 1359 JSON::PP | 400.640 | 62.311 |
1124 JSON::Syck | 552.551 | 787.544 | 1360 JSON::Syck | 1481.040 | 1524.869 |
1125 JSON::XS | 5780.463 | 4854.519 | 1361 JSON::XS | 20661.596 | 9541.183 |
1126 JSON::XS/2 | 3869.998 | 4798.975 | 1362 JSON::XS/2 | 10683.403 | 9416.938 |
1127 JSON::XS/3 | 5862.880 | 4798.975 | 1363 JSON::XS/3 | 20661.596 | 9400.054 |
1128 Storable | 4445.002 | 5235.027 | 1364 Storable | 19765.806 | 10000.725 |
1129 -----------+------------+------------+ 1365 --------------+------------+------------+
1130 1366
1131Again, JSON::XS leads by far (except for Storable which non-surprisingly 1367Again, JSON::XS leads by far (except for Storable which non-surprisingly
1132decodes faster). 1368decodes a bit faster).
1133 1369
1134On large strings containing lots of high Unicode characters, some modules 1370On large strings containing lots of high Unicode characters, some modules
1135(such as JSON::PC) seem to decode faster than JSON::XS, but the result 1371(such as JSON::PC) seem to decode faster than JSON::XS, but the result
1136will be broken due to missing (or wrong) Unicode handling. Others refuse 1372will be broken due to missing (or wrong) Unicode handling. Others refuse
1137to decode or encode properly, so it was impossible to prepare a fair 1373to decode or encode properly, so it was impossible to prepare a fair
… …
1173information you might want to make sure that exceptions thrown by JSON::XS 1409information you might want to make sure that exceptions thrown by JSON::XS
1174will not end up in front of untrusted eyes. 1410will not end up in front of untrusted eyes.
1175 1411
1176If you are using JSON::XS to return packets to consumption 1412If you are using JSON::XS to return packets to consumption
1177by JavaScript scripts in a browser you should have a look at 1413by JavaScript scripts in a browser you should have a look at
1178L<http://jpsykes.com/47/practical-csrf-and-json-security> to see whether 1414L<http://blog.archive.jpsykes.com/47/practical-csrf-and-json-security/> to
1179you are vulnerable to some common attack vectors (which really are browser 1415see whether you are vulnerable to some common attack vectors (which really
1180design bugs, but it is still you who will have to deal with it, as major 1416are browser design bugs, but it is still you who will have to deal with
1181browser developers care only for features, not about getting security 1417it, as major browser developers care only for features, not about getting
1182right). 1418security right).
1183 1419
1184 1420
1185=head1 THREADS 1421=head1 THREADS
1186 1422
1187This module is I<not> guaranteed to be thread safe and there are no 1423This module is I<not> guaranteed to be thread safe and there are no
1188plans to change this until Perl gets thread support (as opposed to the 1424plans to change this until Perl gets thread support (as opposed to the
1189horribly slow so-called "threads" which are simply slow and bloated 1425horribly slow so-called "threads" which are simply slow and bloated
1190process simulations - use fork, its I<much> faster, cheaper, better). 1426process simulations - use fork, it's I<much> faster, cheaper, better).
1191 1427
1192(It might actually work, but you have been warned). 1428(It might actually work, but you have been warned).
1193 1429
1194 1430
1431=head1 THE PERILS OF SETLOCALE
1432
1433Sometimes people avoid the Perl locale support and directly call the
1434system's setlocale function with C<LC_ALL>.
1435
1436This breaks both perl and modules such as JSON::XS, as stringification of
1437numbers no longer works correctly (e.g. C<$x = 0.1; print "$x"+1> might
1438print C<1>, and JSON::XS might output illegal JSON as JSON::XS relies on
1439perl to stringify numbers).
1440
1441The solution is simple: don't call C<setlocale>, or use it for only those
1442categories you need, such as C<LC_MESSAGES> or C<LC_CTYPE>.
1443
1444If you need C<LC_NUMERIC>, you should enable it only around the code that
1445actually needs it (avoiding stringification of numbers), and restore it
1446afterwards.
1447
1448
1195=head1 BUGS 1449=head1 BUGS
1196 1450
1197While the goal of this module is to be correct, that unfortunately does 1451While the goal of this module is to be correct, that unfortunately does
1198not mean its bug-free, only that I think its design is bug-free. It is 1452not mean it's bug-free, only that I think its design is bug-free. If you
1199still relatively early in its development. If you keep reporting bugs they 1453keep reporting bugs they will be fixed swiftly, though.
1200will be fixed swiftly, though.
1201 1454
1202Please refrain from using rt.cpan.org or any other bug reporting 1455Please refrain from using rt.cpan.org or any other bug reporting
1203service. I put the contact address into my modules for a reason. 1456service. I put the contact address into my modules for a reason.
1204 1457
1205=cut 1458=cut
… …
1225 "--" => sub { $_[0] = ${$_[0]} - 1 }, 1478 "--" => sub { $_[0] = ${$_[0]} - 1 },
1226 fallback => 1; 1479 fallback => 1;
1227 1480
12281; 14811;
1229 1482
1483=head1 SEE ALSO
1484
1485The F<json_xs> command line utility for quick experiments.
1486
1230=head1 AUTHOR 1487=head1 AUTHOR
1231 1488
1232 Marc Lehmann <schmorp@schmorp.de> 1489 Marc Lehmann <schmorp@schmorp.de>
1233 http://home.schmorp.de/ 1490 http://home.schmorp.de/
1234 1491

Diff Legend

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