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.74 by root, Wed Nov 28 13:57:15 2007 UTC vs.
Revision 1.116 by root, Tue Feb 17 23:41:20 2009 UTC

1=head1 NAME 1=head1 NAME
2 2
3JSON::XS - JSON serialising/deserialising, done correctly and fast 3JSON::XS - JSON serialising/deserialising, done correctly and fast
4
5=encoding utf-8
4 6
5JSON::XS - 正しくて高速な JSON シリアライザ/デシリアライザ 7JSON::XS - 正しくて高速な JSON シリアライザ/デシリアライザ
6 (http://fleur.hio.jp/perldoc/mix/lib/JSON/XS.html) 8 (http://fleur.hio.jp/perldoc/mix/lib/JSON/XS.html)
7 9
8=head1 SYNOPSIS 10=head1 SYNOPSIS
10 use JSON::XS; 12 use JSON::XS;
11 13
12 # exported functions, they croak on error 14 # exported functions, they croak on error
13 # and expect/generate UTF-8 15 # and expect/generate UTF-8
14 16
15 $utf8_encoded_json_text = to_json $perl_hash_or_arrayref; 17 $utf8_encoded_json_text = encode_json $perl_hash_or_arrayref;
16 $perl_hash_or_arrayref = from_json $utf8_encoded_json_text; 18 $perl_hash_or_arrayref = decode_json $utf8_encoded_json_text;
17 19
18 # OO-interface 20 # OO-interface
19 21
20 $coder = JSON::XS->new->ascii->pretty->allow_nonref; 22 $coder = JSON::XS->new->ascii->pretty->allow_nonref;
21 $pretty_printed_unencoded = $coder->encode ($perl_scalar); 23 $pretty_printed_unencoded = $coder->encode ($perl_scalar);
22 $perl_scalar = $coder->decode ($unicode_json_text); 24 $perl_scalar = $coder->decode ($unicode_json_text);
23 25
26 # Note that JSON version 2.0 and above will automatically use JSON::XS
27 # if available, at virtually no speed overhead either, so you should
28 # be able to just:
29
30 use JSON;
31
32 # and do the same things, except that you have a pure-perl fallback now.
33
24=head1 DESCRIPTION 34=head1 DESCRIPTION
25 35
26This module converts Perl data structures to JSON and vice versa. Its 36This module converts Perl data structures to JSON and vice versa. Its
27primary 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
28I<fast>. To reach the latter goal it was written in C. 38I<fast>. To reach the latter goal it was written in C.
39
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
42overridden) with no overhead due to emulation (by inheriting constructor
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
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.
29 47
30As this is the n-th-something JSON module on CPAN, what was the reason 48As this is the n-th-something JSON module on CPAN, what was the reason
31to 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
32modules, 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
33their maintainers are unresponsive, gone missing, or not listening to bug 51their maintainers are unresponsive, gone missing, or not listening to bug
34reports for other reasons. 52reports for other reasons.
35 53
36See COMPARISON, below, for a comparison to some other JSON modules.
37
38See 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
39vice versa. 55vice versa.
40 56
41=head2 FEATURES 57=head2 FEATURES
42 58
43=over 4 59=over 4
44 60
45=item * correct Unicode handling 61=item * correct Unicode handling
46 62
47This module knows how to handle Unicode, and even documents how and when 63This module knows how to handle Unicode, documents how and when it does
48it does so. 64so, and even documents what "correct" means.
49 65
50=item * round-trip integrity 66=item * round-trip integrity
51 67
52When you serialise a perl data structure using only datatypes supported 68When you serialise a perl data structure using only data types supported
53by JSON, the deserialised data structure is identical on the Perl level. 69by JSON, the deserialised data structure is identical on the Perl level.
54(e.g. the string "2.0" doesn't suddenly become "2" just because it looks 70(e.g. the string "2.0" doesn't suddenly become "2" just because it looks
55like a number). 71like a number). There minor I<are> exceptions to this, read the MAPPING
72section below to learn about those.
56 73
57=item * strict checking of JSON correctness 74=item * strict checking of JSON correctness
58 75
59There is no guessing, no generating of illegal JSON texts by default, 76There is no guessing, no generating of illegal JSON texts by default,
60and 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
61feature). 78feature).
62 79
63=item * fast 80=item * fast
64 81
65Compared to other JSON modules, this module compares favourably in terms 82Compared to other JSON modules and other serialisers such as Storable,
66of speed, too. 83this module usually compares favourably in terms of speed, too.
67 84
68=item * simple to use 85=item * simple to use
69 86
70This module has both a simple functional interface as well as an OO 87This module has both a simple functional interface as well as an object
71interface. 88oriented interface interface.
72 89
73=item * reasonably versatile output formats 90=item * reasonably versatile output formats
74 91
75You can choose between the most compact guaranteed single-line format 92You can choose between the most compact guaranteed-single-line format
76possible (nice for simple line-based protocols), a pure-ascii format 93possible (nice for simple line-based protocols), a pure-ASCII format
77(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
78Unicode 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
79stuff). Or you can combine those features in whatever way you like. 96stuff). Or you can combine those features in whatever way you like.
80 97
81=back 98=back
82 99
83=cut 100=cut
84 101
85package JSON::XS; 102package JSON::XS;
86 103
104no warnings;
87use strict; 105use strict;
88 106
89our $VERSION = '2.0'; 107our $VERSION = '2.232';
90our @ISA = qw(Exporter); 108our @ISA = qw(Exporter);
91 109
92our @EXPORT = qw(to_json from_json); 110our @EXPORT = qw(encode_json decode_json to_json from_json);
111
112sub to_json($) {
113 require Carp;
114 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");
115}
116
117sub from_json($) {
118 require Carp;
119 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");
120}
93 121
94use Exporter; 122use Exporter;
95use XSLoader; 123use XSLoader;
96 124
97=head1 FUNCTIONAL INTERFACE 125=head1 FUNCTIONAL INTERFACE
99The following convenience methods are provided by this module. They are 127The following convenience methods are provided by this module. They are
100exported by default: 128exported by default:
101 129
102=over 4 130=over 4
103 131
104=item $json_text = to_json $perl_scalar 132=item $json_text = encode_json $perl_scalar
105 133
106Converts the given Perl data structure to a UTF-8 encoded, binary string 134Converts the given Perl data structure to a UTF-8 encoded, binary string
107(that is, the string contains octets only). Croaks on error. 135(that is, the string contains octets only). Croaks on error.
108 136
109This function call is functionally identical to: 137This function call is functionally identical to:
110 138
111 $json_text = JSON::XS->new->utf8->encode ($perl_scalar) 139 $json_text = JSON::XS->new->utf8->encode ($perl_scalar)
112 140
113except being faster. 141Except being faster.
114 142
115=item $perl_scalar = from_json $json_text 143=item $perl_scalar = decode_json $json_text
116 144
117The opposite of C<to_json>: expects an UTF-8 (binary) string and tries 145The opposite of C<encode_json>: expects an UTF-8 (binary) string and tries
118to parse that as an UTF-8 encoded JSON text, returning the resulting 146to parse that as an UTF-8 encoded JSON text, returning the resulting
119reference. Croaks on error. 147reference. Croaks on error.
120 148
121This function call is functionally identical to: 149This function call is functionally identical to:
122 150
123 $perl_scalar = JSON::XS->new->utf8->decode ($json_text) 151 $perl_scalar = JSON::XS->new->utf8->decode ($json_text)
124 152
125except being faster. 153Except being faster.
126 154
127=item $is_boolean = JSON::XS::is_bool $scalar 155=item $is_boolean = JSON::XS::is_bool $scalar
128 156
129Returns true if the passed scalar represents either JSON::XS::true or 157Returns true if the passed scalar represents either JSON::XS::true or
130JSON::XS::false, two constants that act like C<1> and C<0>, respectively 158JSON::XS::false, two constants that act like C<1> and C<0>, respectively
148This enables you to store Unicode characters as single characters in a 176This enables you to store Unicode characters as single characters in a
149Perl string - very natural. 177Perl string - very natural.
150 178
151=item 2. Perl does I<not> associate an encoding with your strings. 179=item 2. Perl does I<not> associate an encoding with your strings.
152 180
153Unless you force it to, e.g. when matching it against a regex, or printing 181... until you force it to, e.g. when matching it against a regex, or
154the scalar to a file, in which case Perl either interprets your string as 182printing the scalar to a file, in which case Perl either interprets your
155locale-encoded text, octets/binary, or as Unicode, depending on various 183string as locale-encoded text, octets/binary, or as Unicode, depending
156settings. In no case is an encoding stored together with your data, it is 184on various settings. In no case is an encoding stored together with your
157I<use> that decides encoding, not any magical metadata. 185data, it is I<use> that decides encoding, not any magical meta data.
158 186
159=item 3. The internal utf-8 flag has no meaning with regards to the 187=item 3. The internal utf-8 flag has no meaning with regards to the
160encoding of your string. 188encoding of your string.
161 189
162Just ignore that flag unless you debug a Perl bug, a module written in 190Just ignore that flag unless you debug a Perl bug, a module written in
168 196
169If you didn't know about that flag, just the better, pretend it doesn't 197If you didn't know about that flag, just the better, pretend it doesn't
170exist. 198exist.
171 199
172=item 4. A "Unicode String" is simply a string where each character can be 200=item 4. A "Unicode String" is simply a string where each character can be
173validly interpreted as a Unicode codepoint. 201validly interpreted as a Unicode code point.
174 202
175If you have UTF-8 encoded data, it is no longer a Unicode string, but a 203If you have UTF-8 encoded data, it is no longer a Unicode string, but a
176Unicode string encoded in UTF-8, giving you a binary string. 204Unicode string encoded in UTF-8, giving you a binary string.
177 205
178=item 5. A string containing "high" (> 255) character values is I<not> a UTF-8 string. 206=item 5. A string containing "high" (> 255) character values is I<not> a UTF-8 string.
216 244
217If C<$enable> is false, then the C<encode> method will not escape Unicode 245If C<$enable> is false, then the C<encode> method will not escape Unicode
218characters unless required by the JSON syntax or other flags. This results 246characters unless required by the JSON syntax or other flags. This results
219in a faster and more compact format. 247in a faster and more compact format.
220 248
249See also the section I<ENCODING/CODESET FLAG NOTES> later in this
250document.
251
221The main use for this flag is to produce JSON texts that can be 252The main use for this flag is to produce JSON texts that can be
222transmitted over a 7-bit channel, as the encoded JSON texts will not 253transmitted over a 7-bit channel, as the encoded JSON texts will not
223contain any 8 bit characters. 254contain any 8 bit characters.
224 255
225 JSON::XS->new->ascii (1)->encode ([chr 0x10401]) 256 JSON::XS->new->ascii (1)->encode ([chr 0x10401])
236will not be affected in any way by this flag, as C<decode> by default 267will not be affected in any way by this flag, as C<decode> by default
237expects Unicode, which is a strict superset of latin1. 268expects Unicode, which is a strict superset of latin1.
238 269
239If C<$enable> is false, then the C<encode> method will not escape Unicode 270If C<$enable> is false, then the C<encode> method will not escape Unicode
240characters unless required by the JSON syntax or other flags. 271characters unless required by the JSON syntax or other flags.
272
273See also the section I<ENCODING/CODESET FLAG NOTES> later in this
274document.
241 275
242The main use for this flag is efficiently encoding binary data as JSON 276The main use for this flag is efficiently encoding binary data as JSON
243text, as most octets will not be escaped, resulting in a smaller encoded 277text, as most octets will not be escaped, resulting in a smaller encoded
244size. The disadvantage is that the resulting JSON text is encoded 278size. The disadvantage is that the resulting JSON text is encoded
245in latin1 (and must correctly be treated as such when storing and 279in latin1 (and must correctly be treated as such when storing and
264 298
265If C<$enable> is false, then the C<encode> method will return the JSON 299If C<$enable> is false, then the C<encode> method will return the JSON
266string as a (non-encoded) Unicode string, while C<decode> expects thus a 300string as a (non-encoded) Unicode string, while C<decode> expects thus a
267Unicode string. Any decoding or encoding (e.g. to UTF-8 or UTF-16) needs 301Unicode string. Any decoding or encoding (e.g. to UTF-8 or UTF-16) needs
268to be done yourself, e.g. using the Encode module. 302to be done yourself, e.g. using the Encode module.
303
304See also the section I<ENCODING/CODESET FLAG NOTES> later in this
305document.
269 306
270Example, output UTF-16BE-encoded JSON: 307Example, output UTF-16BE-encoded JSON:
271 308
272 use Encode; 309 use Encode;
273 $jsontext = encode "UTF-16BE", JSON::XS->new->encode ($object); 310 $jsontext = encode "UTF-16BE", JSON::XS->new->encode ($object);
425resulting in an invalid JSON text: 462resulting in an invalid JSON text:
426 463
427 JSON::XS->new->allow_nonref->encode ("Hello, World!") 464 JSON::XS->new->allow_nonref->encode ("Hello, World!")
428 => "Hello, World!" 465 => "Hello, World!"
429 466
467=item $json = $json->allow_unknown ([$enable])
468
469=item $enabled = $json->get_allow_unknown
470
471If C<$enable> is true (or missing), then C<encode> will I<not> throw an
472exception when it encounters values it cannot represent in JSON (for
473example, filehandles) but instead will encode a JSON C<null> value. Note
474that blessed objects are not included here and are handled separately by
475c<allow_nonref>.
476
477If C<$enable> is false (the default), then C<encode> will throw an
478exception when it encounters anything it cannot encode as JSON.
479
480This option does not affect C<decode> in any way, and it is recommended to
481leave it off unless you know your communications partner.
482
430=item $json = $json->allow_blessed ([$enable]) 483=item $json = $json->allow_blessed ([$enable])
431 484
432=item $enabled = $json->get_allow_bless 485=item $enabled = $json->get_allow_blessed
433 486
434If C<$enable> is true (or missing), then the C<encode> method will not 487If C<$enable> is true (or missing), then the C<encode> method will not
435barf when it encounters a blessed reference. Instead, the value of the 488barf when it encounters a blessed reference. Instead, the value of the
436B<convert_blessed> option will decide whether C<null> (C<convert_blessed> 489B<convert_blessed> option will decide whether C<null> (C<convert_blessed>
437disabled or no C<to_json> method found) or a representation of the 490disabled or no C<TO_JSON> method found) or a representation of the
438object (C<convert_blessed> enabled and C<to_json> method found) is being 491object (C<convert_blessed> enabled and C<TO_JSON> method found) is being
439encoded. Has no effect on C<decode>. 492encoded. Has no effect on C<decode>.
440 493
441If C<$enable> is false (the default), then C<encode> will throw an 494If C<$enable> is false (the default), then C<encode> will throw an
442exception when it encounters a blessed object. 495exception when it encounters a blessed object.
443 496
455The C<TO_JSON> method may safely call die if it wants. If C<TO_JSON> 508The C<TO_JSON> method may safely call die if it wants. If C<TO_JSON>
456returns other blessed objects, those will be handled in the same 509returns other blessed objects, those will be handled in the same
457way. C<TO_JSON> must take care of not causing an endless recursion cycle 510way. C<TO_JSON> must take care of not causing an endless recursion cycle
458(== crash) in this case. The name of C<TO_JSON> was chosen because other 511(== crash) in this case. The name of C<TO_JSON> was chosen because other
459methods called by the Perl core (== not by the user of the object) are 512methods called by the Perl core (== not by the user of the object) are
460usually in upper case letters and to avoid collisions with the C<to_json> 513usually in upper case letters and to avoid collisions with any C<to_json>
461function. 514function or method.
462 515
463This setting does not yet influence C<decode> in any way, but in the 516This setting does not yet influence C<decode> in any way, but in the
464future, global hooks might get installed that influence C<decode> and are 517future, global hooks might get installed that influence C<decode> and are
465enabled by this setting. 518enabled by this setting.
466 519
574=item $json = $json->max_depth ([$maximum_nesting_depth]) 627=item $json = $json->max_depth ([$maximum_nesting_depth])
575 628
576=item $max_depth = $json->get_max_depth 629=item $max_depth = $json->get_max_depth
577 630
578Sets the maximum nesting level (default C<512>) accepted while encoding 631Sets the maximum nesting level (default C<512>) accepted while encoding
579or decoding. If the JSON text or Perl data structure has an equal or 632or decoding. If a higher nesting level is detected in JSON text or a Perl
580higher nesting level then this limit, then the encoder and decoder will 633data structure, then the encoder and decoder will stop and croak at that
581stop and croak at that point. 634point.
582 635
583Nesting level is defined by number of hash- or arrayrefs that the encoder 636Nesting level is defined by number of hash- or arrayrefs that the encoder
584needs to traverse to reach a given point or the number of C<{> or C<[> 637needs to traverse to reach a given point or the number of C<{> or C<[>
585characters without their matching closing parenthesis crossed to reach a 638characters without their matching closing parenthesis crossed to reach a
586given character in a string. 639given character in a string.
587 640
588Setting the maximum depth to one disallows any nesting, so that ensures 641Setting the maximum depth to one disallows any nesting, so that ensures
589that the object is only a single hash/object or array. 642that the object is only a single hash/object or array.
590 643
591The argument to C<max_depth> will be rounded up to the next highest power
592of two. If no argument is given, the highest possible setting will be 644If no argument is given, the highest possible setting will be used, which
593used, which is rarely useful. 645is rarely useful.
646
647Note that nesting is implemented by recursion in C. The default value has
648been chosen to be as large as typical operating systems allow without
649crashing.
594 650
595See SECURITY CONSIDERATIONS, below, for more info on why this is useful. 651See SECURITY CONSIDERATIONS, below, for more info on why this is useful.
596 652
597=item $json = $json->max_size ([$maximum_string_size]) 653=item $json = $json->max_size ([$maximum_string_size])
598 654
599=item $max_size = $json->get_max_size 655=item $max_size = $json->get_max_size
600 656
601Set the maximum length a JSON text may have (in bytes) where decoding is 657Set the maximum length a JSON text may have (in bytes) where decoding is
602being attempted. The default is C<0>, meaning no limit. When C<decode> 658being attempted. The default is C<0>, meaning no limit. When C<decode>
603is called on a string longer then this number of characters it will not 659is called on a string that is longer then this many bytes, it will not
604attempt to decode the string but throw an exception. This setting has no 660attempt to decode the string but throw an exception. This setting has no
605effect on C<encode> (yet). 661effect on C<encode> (yet).
606 662
607The argument to C<max_size> will be rounded up to the next B<highest> 663If no argument is given, the limit check will be deactivated (same as when
608power of two (so may be more than requested). If no argument is given, the 664C<0> is specified).
609limit check will be deactivated (same as when C<0> is specified).
610 665
611See SECURITY CONSIDERATIONS, below, for more info on why this is useful. 666See SECURITY CONSIDERATIONS, below, for more info on why this is useful.
612 667
613=item $json_text = $json->encode ($perl_scalar) 668=item $json_text = $json->encode ($perl_scalar)
614 669
643 => ([], 3) 698 => ([], 3)
644 699
645=back 700=back
646 701
647 702
703=head1 INCREMENTAL PARSING
704
705In some cases, there is the need for incremental parsing of JSON
706texts. While this module always has to keep both JSON text and resulting
707Perl data structure in memory at one time, it does allow you to parse a
708JSON stream incrementally. It does so by accumulating text until it has
709a full JSON object, which it then can decode. This process is similar to
710using C<decode_prefix> to see if a full JSON object is available, but
711is much more efficient (and can be implemented with a minimum of method
712calls).
713
714JSON::XS will only attempt to parse the JSON text once it is sure it
715has enough text to get a decisive result, using a very simple but
716truly incremental parser. This means that it sometimes won't stop as
717early as the full parser, for example, it doesn't detect parenthese
718mismatches. The only thing it guarantees is that it starts decoding as
719soon as a syntactically valid JSON text has been seen. This means you need
720to set resource limits (e.g. C<max_size>) to ensure the parser will stop
721parsing in the presence if syntax errors.
722
723The following methods implement this incremental parser.
724
725=over 4
726
727=item [void, scalar or list context] = $json->incr_parse ([$string])
728
729This is the central parsing function. It can both append new text and
730extract objects from the stream accumulated so far (both of these
731functions are optional).
732
733If C<$string> is given, then this string is appended to the already
734existing JSON fragment stored in the C<$json> object.
735
736After that, if the function is called in void context, it will simply
737return without doing anything further. This can be used to add more text
738in as many chunks as you want.
739
740If the method is called in scalar context, then it will try to extract
741exactly I<one> JSON object. If that is successful, it will return this
742object, otherwise it will return C<undef>. If there is a parse error,
743this method will croak just as C<decode> would do (one can then use
744C<incr_skip> to skip the errornous part). This is the most common way of
745using the method.
746
747And finally, in list context, it will try to extract as many objects
748from the stream as it can find and return them, or the empty list
749otherwise. For this to work, there must be no separators between the JSON
750objects or arrays, instead they must be concatenated back-to-back. If
751an error occurs, an exception will be raised as in the scalar context
752case. Note that in this case, any previously-parsed JSON texts will be
753lost.
754
755=item $lvalue_string = $json->incr_text
756
757This method returns the currently stored JSON fragment as an lvalue, that
758is, you can manipulate it. This I<only> works when a preceding call to
759C<incr_parse> in I<scalar context> successfully returned an object. Under
760all other circumstances you must not call this function (I mean it.
761although in simple tests it might actually work, it I<will> fail under
762real world conditions). As a special exception, you can also call this
763method before having parsed anything.
764
765This function is useful in two cases: a) finding the trailing text after a
766JSON object or b) parsing multiple JSON objects separated by non-JSON text
767(such as commas).
768
769=item $json->incr_skip
770
771This will reset the state of the incremental parser and will remove
772the parsed text from the input buffer so far. This is useful after
773C<incr_parse> died, in which case the input buffer and incremental parser
774state is left unchanged, to skip the text parsed so far and to reset the
775parse state.
776
777The difference to C<incr_reset> is that only text until the parse error
778occured is removed.
779
780=item $json->incr_reset
781
782This completely resets the incremental parser, that is, after this call,
783it will be as if the parser had never parsed anything.
784
785This is useful if you want to repeatedly parse JSON objects and want to
786ignore any trailing data, which means you have to reset the parser after
787each successful decode.
788
789=back
790
791=head2 LIMITATIONS
792
793All options that affect decoding are supported, except
794C<allow_nonref>. The reason for this is that it cannot be made to
795work sensibly: JSON objects and arrays are self-delimited, i.e. you can concatenate
796them back to back and still decode them perfectly. This does not hold true
797for JSON numbers, however.
798
799For example, is the string C<1> a single JSON number, or is it simply the
800start of C<12>? Or is C<12> a single JSON number, or the concatenation
801of C<1> and C<2>? In neither case you can tell, and this is why JSON::XS
802takes the conservative route and disallows this case.
803
804=head2 EXAMPLES
805
806Some examples will make all this clearer. First, a simple example that
807works similarly to C<decode_prefix>: We want to decode the JSON object at
808the start of a string and identify the portion after the JSON object:
809
810 my $text = "[1,2,3] hello";
811
812 my $json = new JSON::XS;
813
814 my $obj = $json->incr_parse ($text)
815 or die "expected JSON object or array at beginning of string";
816
817 my $tail = $json->incr_text;
818 # $tail now contains " hello"
819
820Easy, isn't it?
821
822Now for a more complicated example: Imagine a hypothetical protocol where
823you read some requests from a TCP stream, and each request is a JSON
824array, without any separation between them (in fact, it is often useful to
825use newlines as "separators", as these get interpreted as whitespace at
826the start of the JSON text, which makes it possible to test said protocol
827with C<telnet>...).
828
829Here is how you'd do it (it is trivial to write this in an event-based
830manner):
831
832 my $json = new JSON::XS;
833
834 # read some data from the socket
835 while (sysread $socket, my $buf, 4096) {
836
837 # split and decode as many requests as possible
838 for my $request ($json->incr_parse ($buf)) {
839 # act on the $request
840 }
841 }
842
843Another complicated example: Assume you have a string with JSON objects
844or arrays, all separated by (optional) comma characters (e.g. C<[1],[2],
845[3]>). To parse them, we have to skip the commas between the JSON texts,
846and here is where the lvalue-ness of C<incr_text> comes in useful:
847
848 my $text = "[1],[2], [3]";
849 my $json = new JSON::XS;
850
851 # void context, so no parsing done
852 $json->incr_parse ($text);
853
854 # now extract as many objects as possible. note the
855 # use of scalar context so incr_text can be called.
856 while (my $obj = $json->incr_parse) {
857 # do something with $obj
858
859 # now skip the optional comma
860 $json->incr_text =~ s/^ \s* , //x;
861 }
862
863Now lets go for a very complex example: Assume that you have a gigantic
864JSON array-of-objects, many gigabytes in size, and you want to parse it,
865but you cannot load it into memory fully (this has actually happened in
866the real world :).
867
868Well, you lost, you have to implement your own JSON parser. But JSON::XS
869can still help you: You implement a (very simple) array parser and let
870JSON decode the array elements, which are all full JSON objects on their
871own (this wouldn't work if the array elements could be JSON numbers, for
872example):
873
874 my $json = new JSON::XS;
875
876 # open the monster
877 open my $fh, "<bigfile.json"
878 or die "bigfile: $!";
879
880 # first parse the initial "["
881 for (;;) {
882 sysread $fh, my $buf, 65536
883 or die "read error: $!";
884 $json->incr_parse ($buf); # void context, so no parsing
885
886 # Exit the loop once we found and removed(!) the initial "[".
887 # In essence, we are (ab-)using the $json object as a simple scalar
888 # we append data to.
889 last if $json->incr_text =~ s/^ \s* \[ //x;
890 }
891
892 # now we have the skipped the initial "[", so continue
893 # parsing all the elements.
894 for (;;) {
895 # in this loop we read data until we got a single JSON object
896 for (;;) {
897 if (my $obj = $json->incr_parse) {
898 # do something with $obj
899 last;
900 }
901
902 # add more data
903 sysread $fh, my $buf, 65536
904 or die "read error: $!";
905 $json->incr_parse ($buf); # void context, so no parsing
906 }
907
908 # in this loop we read data until we either found and parsed the
909 # separating "," between elements, or the final "]"
910 for (;;) {
911 # first skip whitespace
912 $json->incr_text =~ s/^\s*//;
913
914 # if we find "]", we are done
915 if ($json->incr_text =~ s/^\]//) {
916 print "finished.\n";
917 exit;
918 }
919
920 # if we find ",", we can continue with the next element
921 if ($json->incr_text =~ s/^,//) {
922 last;
923 }
924
925 # if we find anything else, we have a parse error!
926 if (length $json->incr_text) {
927 die "parse error near ", $json->incr_text;
928 }
929
930 # else add more data
931 sysread $fh, my $buf, 65536
932 or die "read error: $!";
933 $json->incr_parse ($buf); # void context, so no parsing
934 }
935
936This is a complex example, but most of the complexity comes from the fact
937that we are trying to be correct (bear with me if I am wrong, I never ran
938the above example :).
939
940
941
648=head1 MAPPING 942=head1 MAPPING
649 943
650This section describes how JSON::XS maps Perl values to JSON values and 944This section describes how JSON::XS maps Perl values to JSON values and
651vice versa. These mappings are designed to "do the right thing" in most 945vice versa. These mappings are designed to "do the right thing" in most
652circumstances automatically, preserving round-tripping characteristics 946circumstances automatically, preserving round-tripping characteristics
680 974
681A JSON number becomes either an integer, numeric (floating point) or 975A JSON number becomes either an integer, numeric (floating point) or
682string scalar in perl, depending on its range and any fractional parts. On 976string scalar in perl, depending on its range and any fractional parts. On
683the Perl level, there is no difference between those as Perl handles all 977the Perl level, there is no difference between those as Perl handles all
684the conversion details, but an integer may take slightly less memory and 978the conversion details, but an integer may take slightly less memory and
685might represent more values exactly than (floating point) numbers. 979might represent more values exactly than floating point numbers.
686 980
687If the number consists of digits only, JSON::XS will try to represent 981If the number consists of digits only, JSON::XS will try to represent
688it as an integer value. If that fails, it will try to represent it as 982it as an integer value. If that fails, it will try to represent it as
689a numeric (floating point) value if that is possible without loss of 983a numeric (floating point) value if that is possible without loss of
690precision. Otherwise it will preserve the number as a string value. 984precision. Otherwise it will preserve the number as a string value (in
985which case you lose roundtripping ability, as the JSON number will be
986re-encoded toa JSON string).
691 987
692Numbers containing a fractional or exponential part will always be 988Numbers containing a fractional or exponential part will always be
693represented as numeric (floating point) values, possibly at a loss of 989represented as numeric (floating point) values, possibly at a loss of
694precision. 990precision (in which case you might lose perfect roundtripping ability, but
695 991the JSON number will still be re-encoded as a JSON number).
696This might create round-tripping problems as numbers might become strings,
697but as Perl is typeless there is no other way to do it.
698 992
699=item true, false 993=item true, false
700 994
701These JSON atoms become C<JSON::XS::true> and C<JSON::XS::false>, 995These JSON atoms become C<JSON::XS::true> and C<JSON::XS::false>,
702respectively. They are overloaded to act almost exactly like the numbers 996respectively. They are overloaded to act almost exactly like the numbers
739Other unblessed references are generally not allowed and will cause an 1033Other unblessed references are generally not allowed and will cause an
740exception to be thrown, except for references to the integers C<0> and 1034exception to be thrown, except for references to the integers C<0> and
741C<1>, which get turned into C<false> and C<true> atoms in JSON. You can 1035C<1>, which get turned into C<false> and C<true> atoms in JSON. You can
742also use C<JSON::XS::false> and C<JSON::XS::true> to improve readability. 1036also use C<JSON::XS::false> and C<JSON::XS::true> to improve readability.
743 1037
744 to_json [\0,JSON::XS::true] # yields [false,true] 1038 encode_json [\0, JSON::XS::true] # yields [false,true]
745 1039
746=item JSON::XS::true, JSON::XS::false 1040=item JSON::XS::true, JSON::XS::false
747 1041
748These special values become JSON true and JSON false values, 1042These special values become JSON true and JSON false values,
749respectively. You can also use C<\1> and C<\0> directly if you want. 1043respectively. You can also use C<\1> and C<\0> directly if you want.
750 1044
751=item blessed objects 1045=item blessed objects
752 1046
753Blessed objects are not allowed. JSON::XS currently tries to encode their 1047Blessed objects are not directly representable in JSON. See the
754underlying representation (hash- or arrayref), but this behaviour might 1048C<allow_blessed> and C<convert_blessed> methods on various options on
755change in future versions. 1049how to deal with this: basically, you can choose between throwing an
1050exception, encoding the reference as if it weren't blessed, or provide
1051your own serialiser method.
756 1052
757=item simple scalars 1053=item simple scalars
758 1054
759Simple Perl scalars (any scalar that is not a reference) are the most 1055Simple Perl scalars (any scalar that is not a reference) are the most
760difficult objects to encode: JSON::XS will encode undefined scalars as 1056difficult objects to encode: JSON::XS will encode undefined scalars as
761JSON null value, scalars that have last been used in a string context 1057JSON C<null> values, scalars that have last been used in a string context
762before encoding as JSON strings and anything else as number value: 1058before encoding as JSON strings, and anything else as number value:
763 1059
764 # dump as number 1060 # dump as number
765 to_json [2] # yields [2] 1061 encode_json [2] # yields [2]
766 to_json [-3.0e17] # yields [-3e+17] 1062 encode_json [-3.0e17] # yields [-3e+17]
767 my $value = 5; to_json [$value] # yields [5] 1063 my $value = 5; encode_json [$value] # yields [5]
768 1064
769 # used as string, so dump as string 1065 # used as string, so dump as string
770 print $value; 1066 print $value;
771 to_json [$value] # yields ["5"] 1067 encode_json [$value] # yields ["5"]
772 1068
773 # undef becomes null 1069 # undef becomes null
774 to_json [undef] # yields [null] 1070 encode_json [undef] # yields [null]
775 1071
776You can force the type to be a JSON string by stringifying it: 1072You can force the type to be a JSON string by stringifying it:
777 1073
778 my $x = 3.1; # some variable containing a number 1074 my $x = 3.1; # some variable containing a number
779 "$x"; # stringified 1075 "$x"; # stringified
785 my $x = "3"; # some variable containing a string 1081 my $x = "3"; # some variable containing a string
786 $x += 0; # numify it, ensuring it will be dumped as a number 1082 $x += 0; # numify it, ensuring it will be dumped as a number
787 $x *= 1; # same thing, the choice is yours. 1083 $x *= 1; # same thing, the choice is yours.
788 1084
789You can not currently force the type in other, less obscure, ways. Tell me 1085You can not currently force the type in other, less obscure, ways. Tell me
790if you need this capability. 1086if you need this capability (but don't forget to explain why it's needed
1087:).
791 1088
792=back 1089=back
793 1090
794 1091
795=head1 COMPARISON 1092=head1 ENCODING/CODESET FLAG NOTES
796 1093
797As already mentioned, this module was created because none of the existing 1094The interested reader might have seen a number of flags that signify
798JSON modules could be made to work correctly. First I will describe the 1095encodings or codesets - C<utf8>, C<latin1> and C<ascii>. There seems to be
799problems (or pleasures) I encountered with various existing JSON modules, 1096some confusion on what these do, so here is a short comparison:
800followed by some benchmark values. JSON::XS was designed not to suffer 1097
801from any of these problems or limitations. 1098C<utf8> controls whether the JSON text created by C<encode> (and expected
1099by C<decode>) is UTF-8 encoded or not, while C<latin1> and C<ascii> only
1100control whether C<encode> escapes character values outside their respective
1101codeset range. Neither of these flags conflict with each other, although
1102some combinations make less sense than others.
1103
1104Care has been taken to make all flags symmetrical with respect to
1105C<encode> and C<decode>, that is, texts encoded with any combination of
1106these flag values will be correctly decoded when the same flags are used
1107- in general, if you use different flag settings while encoding vs. when
1108decoding you likely have a bug somewhere.
1109
1110Below comes a verbose discussion of these flags. Note that a "codeset" is
1111simply an abstract set of character-codepoint pairs, while an encoding
1112takes those codepoint numbers and I<encodes> them, in our case into
1113octets. Unicode is (among other things) a codeset, UTF-8 is an encoding,
1114and ISO-8859-1 (= latin 1) and ASCII are both codesets I<and> encodings at
1115the same time, which can be confusing.
802 1116
803=over 4 1117=over 4
804 1118
805=item JSON 1.07 1119=item C<utf8> flag disabled
806 1120
807Slow (but very portable, as it is written in pure Perl). 1121When C<utf8> is disabled (the default), then C<encode>/C<decode> generate
1122and expect Unicode strings, that is, characters with high ordinal Unicode
1123values (> 255) will be encoded as such characters, and likewise such
1124characters are decoded as-is, no canges to them will be done, except
1125"(re-)interpreting" them as Unicode codepoints or Unicode characters,
1126respectively (to Perl, these are the same thing in strings unless you do
1127funny/weird/dumb stuff).
808 1128
809Undocumented/buggy Unicode handling (how JSON handles Unicode values is 1129This is useful when you want to do the encoding yourself (e.g. when you
810undocumented. One can get far by feeding it Unicode strings and doing 1130want to have UTF-16 encoded JSON texts) or when some other layer does
811en-/decoding oneself, but Unicode escapes are not working properly). 1131the encoding for you (for example, when printing to a terminal using a
1132filehandle that transparently encodes to UTF-8 you certainly do NOT want
1133to UTF-8 encode your data first and have Perl encode it another time).
812 1134
813No round-tripping (strings get clobbered if they look like numbers, e.g. 1135=item C<utf8> flag enabled
814the string C<2.0> will encode to C<2.0> instead of C<"2.0">, and that will
815decode into the number 2.
816 1136
817=item JSON::PC 0.01 1137If the C<utf8>-flag is enabled, C<encode>/C<decode> will encode all
1138characters using the corresponding UTF-8 multi-byte sequence, and will
1139expect your input strings to be encoded as UTF-8, that is, no "character"
1140of the input string must have any value > 255, as UTF-8 does not allow
1141that.
818 1142
819Very fast. 1143The C<utf8> flag therefore switches between two modes: disabled means you
1144will get a Unicode string in Perl, enabled means you get an UTF-8 encoded
1145octet/binary string in Perl.
820 1146
821Undocumented/buggy Unicode handling. 1147=item C<latin1> or C<ascii> flags enabled
822 1148
823No round-tripping. 1149With C<latin1> (or C<ascii>) enabled, C<encode> will escape characters
1150with ordinal values > 255 (> 127 with C<ascii>) and encode the remaining
1151characters as specified by the C<utf8> flag.
824 1152
825Has problems handling many Perl values (e.g. regex results and other magic 1153If C<utf8> is disabled, then the result is also correctly encoded in those
826values will make it croak). 1154character sets (as both are proper subsets of Unicode, meaning that a
1155Unicode string with all character values < 256 is the same thing as a
1156ISO-8859-1 string, and a Unicode string with all character values < 128 is
1157the same thing as an ASCII string in Perl).
827 1158
828Does not even generate valid JSON (C<{1,2}> gets converted to C<{1:2}> 1159If C<utf8> is enabled, you still get a correct UTF-8-encoded string,
829which is not a valid JSON text. 1160regardless of these flags, just some more characters will be escaped using
1161C<\uXXXX> then before.
830 1162
831Unmaintained (maintainer unresponsive for many months, bugs are not 1163Note that ISO-8859-1-I<encoded> strings are not compatible with UTF-8
832getting fixed). 1164encoding, while ASCII-encoded strings are. That is because the ISO-8859-1
1165encoding is NOT a subset of UTF-8 (despite the ISO-8859-1 I<codeset> being
1166a subset of Unicode), while ASCII is.
833 1167
834=item JSON::Syck 0.21 1168Surprisingly, C<decode> will ignore these flags and so treat all input
1169values as governed by the C<utf8> flag. If it is disabled, this allows you
1170to decode ISO-8859-1- and ASCII-encoded strings, as both strict subsets of
1171Unicode. If it is enabled, you can correctly decode UTF-8 encoded strings.
835 1172
836Very buggy (often crashes). 1173So neither C<latin1> nor C<ascii> are incompatible with the C<utf8> flag -
1174they only govern when the JSON output engine escapes a character or not.
837 1175
838Very inflexible (no human-readable format supported, format pretty much 1176The main use for C<latin1> is to relatively efficiently store binary data
839undocumented. I need at least a format for easy reading by humans and a 1177as JSON, at the expense of breaking compatibility with most JSON decoders.
840single-line compact format for use in a protocol, and preferably a way to
841generate ASCII-only JSON texts).
842 1178
843Completely broken (and confusingly documented) Unicode handling (Unicode 1179The main use for C<ascii> is to force the output to not contain characters
844escapes are not working properly, you need to set ImplicitUnicode to 1180with values > 127, which means you can interpret the resulting string
845I<different> values on en- and decoding to get symmetric behaviour). 1181as UTF-8, ISO-8859-1, ASCII, KOI8-R or most about any character set and
846 11828-bit-encoding, and still get the same data structure back. This is useful
847No round-tripping (simple cases work, but this depends on whether the scalar 1183when your channel for JSON transfer is not 8-bit clean or the encoding
848value was used in a numeric context or not). 1184might be mangled in between (e.g. in mail), and works because ASCII is a
849 1185proper subset of most 8-bit and multibyte encodings in use in the world.
850Dumping hashes may skip hash values depending on iterator state.
851
852Unmaintained (maintainer unresponsive for many months, bugs are not
853getting fixed).
854
855Does not check input for validity (i.e. will accept non-JSON input and
856return "something" instead of raising an exception. This is a security
857issue: imagine two banks transferring money between each other using
858JSON. One bank might parse a given non-JSON request and deduct money,
859while the other might reject the transaction with a syntax error. While a
860good protocol will at least recover, that is extra unnecessary work and
861the transaction will still not succeed).
862
863=item JSON::DWIW 0.04
864
865Very fast. Very natural. Very nice.
866
867Undocumented Unicode handling (but the best of the pack. Unicode escapes
868still don't get parsed properly).
869
870Very inflexible.
871
872No round-tripping.
873
874Does not generate valid JSON texts (key strings are often unquoted, empty keys
875result in nothing being output)
876
877Does not check input for validity.
878 1186
879=back 1187=back
880 1188
881 1189
1190=head2 JSON and ECMAscript
1191
1192JSON syntax is based on how literals are represented in javascript (the
1193not-standardised predecessor of ECMAscript) which is presumably why it is
1194called "JavaScript Object Notation".
1195
1196However, JSON is not a subset (and also not a superset of course) of
1197ECMAscript (the standard) or javascript (whatever browsers actually
1198implement).
1199
1200If you want to use javascript's C<eval> function to "parse" JSON, you
1201might run into parse errors for valid JSON texts, or the resulting data
1202structure might not be queryable:
1203
1204One of the problems is that U+2028 and U+2029 are valid characters inside
1205JSON strings, but are not allowed in ECMAscript string literals, so the
1206following Perl fragment will not output something that can be guaranteed
1207to be parsable by javascript's C<eval>:
1208
1209 use JSON::XS;
1210
1211 print encode_json [chr 0x2028];
1212
1213The right fix for this is to use a proper JSON parser in your javascript
1214programs, and not rely on C<eval>.
1215
1216If this is not an option, you can, as a stop-gap measure, simply encode to
1217ASCII-only JSON:
1218
1219 use JSON::XS;
1220
1221 print JSON::XS->new->ascii->encode ([chr 0x2028]);
1222
1223And if you are concerned about the size of the resulting JSON text, you
1224can run some regexes to only escape U+2028 and U+2029:
1225
1226 use JSON::XS;
1227
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;
1232
1233This works because U+2028/U+2029 are not allowed outside of strings and
1234are not used for syntax, so replacing them unconditionally just works.
1235
1236Note, however, that fixing the broken JSON parser is better than working
1237around it in every other generator. The above regexes should work well in
1238other languages, as long as they operate on UTF-8. It is equally valid to
1239replace all occurences of U+2028/2029 directly by their \\u-escaped forms
1240in unicode texts, so they can simply be used to fix any parsers relying on
1241C<eval> by first applying the regexes on the encoded texts.
1242
1243Note also that the above only works for U+2028 and U+2029 and thus
1244only for fully ECMAscript-compliant parsers. Many existing javascript
1245implementations misparse other characters as well. Best rely on a good
1246JSON parser, such as Douglas Crockfords F<json2.js>, which escapes the
1247above and many more problematic characters properly before passing them
1248into C<eval>.
1249
1250Another problem is that some javascript implementations reserve
1251some property names for their own purposes (which probably makes
1252them non-ECMAscript-compliant). For example, Iceweasel reserves the
1253C<__proto__> property name for it's own purposes.
1254
1255If that is a problem, you could parse try to filter the resulting JSON
1256output for these property strings, e.g.:
1257
1258 $json =~ s/"__proto__"\s*:/"__proto__renamed":/g;
1259
1260This works because C<__proto__> is not valid outside of strings, so every
1261occurence of C<"__proto__"\s*:> must be a string used as property name.
1262
1263If you know of other incompatibilities, please let me know.
1264
1265
882=head2 JSON and YAML 1266=head2 JSON and YAML
883 1267
884You often hear that JSON is a subset (or a close subset) of YAML. This is, 1268You often hear that JSON is a subset of YAML. This is, however, a mass
885however, a mass hysteria and very far from the truth. In general, there is 1269hysteria(*) and very far from the truth (as of the time of this writing),
886no way to configure JSON::XS to output a data structure as valid YAML. 1270so let me state it clearly: I<in general, there is no way to configure
1271JSON::XS to output a data structure as valid YAML> that works in all
1272cases.
887 1273
888If you really must use JSON::XS to generate YAML, you should use this 1274If you really must use JSON::XS to generate YAML, you should use this
889algorithm (subject to change in future versions): 1275algorithm (subject to change in future versions):
890 1276
891 my $to_yaml = JSON::XS->new->utf8->space_after (1); 1277 my $to_yaml = JSON::XS->new->utf8->space_after (1);
892 my $yaml = $to_yaml->encode ($ref) . "\n"; 1278 my $yaml = $to_yaml->encode ($ref) . "\n";
893 1279
894This will usually generate JSON texts that also parse as valid 1280This will I<usually> generate JSON texts that also parse as valid
895YAML. Please note that YAML has hardcoded limits on (simple) object key 1281YAML. Please note that YAML has hardcoded limits on (simple) object key
896lengths that JSON doesn't have, so you should make sure that your hash 1282lengths that JSON doesn't have and also has different and incompatible
1283unicode handling, so you should make sure that your hash keys are
897keys are noticeably shorter than the 1024 characters YAML allows. 1284noticeably shorter than the 1024 "stream characters" YAML allows and that
1285you do not have characters with codepoint values outside the Unicode BMP
1286(basic multilingual page). YAML also does not allow C<\/> sequences in
1287strings (which JSON::XS does not I<currently> generate, but other JSON
1288generators might).
898 1289
899There might be other incompatibilities that I am not aware of. In general 1290There might be other incompatibilities that I am not aware of (or the YAML
1291specification has been changed yet again - it does so quite often). In
900you should not try to generate YAML with a JSON generator or vice versa, 1292general you should not try to generate YAML with a JSON generator or vice
901or try to parse JSON with a YAML parser or vice versa: chances are high 1293versa, or try to parse JSON with a YAML parser or vice versa: chances are
902that you will run into severe interoperability problems. 1294high that you will run into severe interoperability problems when you
1295least expect it.
1296
1297=over 4
1298
1299=item (*)
1300
1301I have been pressured multiple times by Brian Ingerson (one of the
1302authors of the YAML specification) to remove this paragraph, despite him
1303acknowledging that the actual incompatibilities exist. As I was personally
1304bitten by this "JSON is YAML" lie, I refused and said I will continue to
1305educate people about these issues, so others do not run into the same
1306problem again and again. After this, Brian called me a (quote)I<complete
1307and worthless idiot>(unquote).
1308
1309In my opinion, instead of pressuring and insulting people who actually
1310clarify issues with YAML and the wrong statements of some of its
1311proponents, I would kindly suggest reading the JSON spec (which is not
1312that difficult or long) and finally make YAML compatible to it, and
1313educating users about the changes, instead of spreading lies about the
1314real compatibility for many I<years> and trying to silence people who
1315point out that it isn't true.
1316
1317=back
903 1318
904 1319
905=head2 SPEED 1320=head2 SPEED
906 1321
907It seems that JSON::XS is surprisingly fast, as shown in the following 1322It seems that JSON::XS is surprisingly fast, as shown in the following
908tables. They have been generated with the help of the C<eg/bench> program 1323tables. They have been generated with the help of the C<eg/bench> program
909in the JSON::XS distribution, to make it easy to compare on your own 1324in the JSON::XS distribution, to make it easy to compare on your own
910system. 1325system.
911 1326
912First comes a comparison between various modules using a very short 1327First comes a comparison between various modules using
913single-line JSON string: 1328a very short single-line JSON string (also available at
1329L<http://dist.schmorp.de/misc/json/short.json>).
914 1330
915 {"method": "handleMessage", "params": ["user1", "we were just talking"], \ 1331 {"method": "handleMessage", "params": ["user1",
916 "id": null, "array":[1,11,234,-5,1e5,1e7, true, false]} 1332 "we were just talking"], "id": null, "array":[1,11,234,-5,1e5,1e7,
1333 true, false]}
917 1334
918It shows the number of encodes/decodes per second (JSON::XS uses 1335It shows the number of encodes/decodes per second (JSON::XS uses
919the functional interface, while JSON::XS/2 uses the OO interface 1336the functional interface, while JSON::XS/2 uses the OO interface
920with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables 1337with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables
921shrink). Higher is better: 1338shrink). Higher is better:
937about three times faster on decoding, and over forty times faster 1354about three times faster on decoding, and over forty times faster
938than JSON, even with pretty-printing and key sorting. It also compares 1355than JSON, even with pretty-printing and key sorting. It also compares
939favourably to Storable for small amounts of data. 1356favourably to Storable for small amounts of data.
940 1357
941Using a longer test string (roughly 18KB, generated from Yahoo! Locals 1358Using a longer test string (roughly 18KB, generated from Yahoo! Locals
942search API (http://nanoref.com/yahooapis/mgPdGg): 1359search API (L<http://dist.schmorp.de/misc/json/long.json>).
943 1360
944 module | encode | decode | 1361 module | encode | decode |
945 -----------|------------|------------| 1362 -----------|------------|------------|
946 JSON 1.x | 55.260 | 34.971 | 1363 JSON 1.x | 55.260 | 34.971 |
947 JSON::DWIW | 825.228 | 1082.513 | 1364 JSON::DWIW | 825.228 | 1082.513 |
984 1401
985Third, JSON::XS recurses using the C stack when decoding objects and 1402Third, JSON::XS recurses using the C stack when decoding objects and
986arrays. The C stack is a limited resource: for instance, on my amd64 1403arrays. The C stack is a limited resource: for instance, on my amd64
987machine with 8MB of stack size I can decode around 180k nested arrays but 1404machine with 8MB of stack size I can decode around 180k nested arrays but
988only 14k nested JSON objects (due to perl itself recursing deeply on croak 1405only 14k nested JSON objects (due to perl itself recursing deeply on croak
989to free the temporary). If that is exceeded, the program crashes. to be 1406to free the temporary). If that is exceeded, the program crashes. To be
990conservative, the default nesting limit is set to 512. If your process 1407conservative, the default nesting limit is set to 512. If your process
991has a smaller stack, you should adjust this setting accordingly with the 1408has a smaller stack, you should adjust this setting accordingly with the
992C<max_depth> method. 1409C<max_depth> method.
993 1410
994And last but least, something else could bomb you that I forgot to think 1411Something else could bomb you, too, that I forgot to think of. In that
995of. In that case, you get to keep the pieces. I am always open for hints, 1412case, you get to keep the pieces. I am always open for hints, though...
996though... 1413
1414Also keep in mind that JSON::XS might leak contents of your Perl data
1415structures in its error messages, so when you serialise sensitive
1416information you might want to make sure that exceptions thrown by JSON::XS
1417will not end up in front of untrusted eyes.
997 1418
998If you are using JSON::XS to return packets to consumption 1419If you are using JSON::XS to return packets to consumption
999by JavaScript scripts in a browser you should have a look at 1420by JavaScript scripts in a browser you should have a look at
1000L<http://jpsykes.com/47/practical-csrf-and-json-security> to see whether 1421L<http://jpsykes.com/47/practical-csrf-and-json-security> to see whether
1001you are vulnerable to some common attack vectors (which really are browser 1422you are vulnerable to some common attack vectors (which really are browser
1002design bugs, but it is still you who will have to deal with it, as major 1423design bugs, but it is still you who will have to deal with it, as major
1003browser developers care only for features, not about doing security 1424browser developers care only for features, not about getting security
1004right). 1425right).
1005 1426
1006 1427
1007=head1 THREADS 1428=head1 THREADS
1008 1429
1009This module is I<not> guaranteed to be thread safe and there are no 1430This module is I<not> guaranteed to be thread safe and there are no
1010plans to change this until Perl gets thread support (as opposed to the 1431plans to change this until Perl gets thread support (as opposed to the
1011horribly slow so-called "threads" which are simply slow and bloated 1432horribly slow so-called "threads" which are simply slow and bloated
1012process simulations - use fork, its I<much> faster, cheaper, better). 1433process simulations - use fork, it's I<much> faster, cheaper, better).
1013 1434
1014(It might actually work, but you have been warned). 1435(It might actually work, but you have been warned).
1015 1436
1016 1437
1017=head1 BUGS 1438=head1 BUGS
1018 1439
1019While the goal of this module is to be correct, that unfortunately does 1440While the goal of this module is to be correct, that unfortunately does
1020not mean its bug-free, only that I think its design is bug-free. It is 1441not mean it's bug-free, only that I think its design is bug-free. If you
1021still relatively early in its development. If you keep reporting bugs they 1442keep reporting bugs they will be fixed swiftly, though.
1022will be fixed swiftly, though.
1023 1443
1024Please refrain from using rt.cpan.org or any other bug reporting 1444Please refrain from using rt.cpan.org or any other bug reporting
1025service. I put the contact address into my modules for a reason. 1445service. I put the contact address into my modules for a reason.
1026 1446
1027=cut 1447=cut
1047 "--" => sub { $_[0] = ${$_[0]} - 1 }, 1467 "--" => sub { $_[0] = ${$_[0]} - 1 },
1048 fallback => 1; 1468 fallback => 1;
1049 1469
10501; 14701;
1051 1471
1472=head1 SEE ALSO
1473
1474The F<json_xs> command line utility for quick experiments.
1475
1052=head1 AUTHOR 1476=head1 AUTHOR
1053 1477
1054 Marc Lehmann <schmorp@schmorp.de> 1478 Marc Lehmann <schmorp@schmorp.de>
1055 http://home.schmorp.de/ 1479 http://home.schmorp.de/
1056 1480

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines