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.76 by root, Sun Dec 2 15:34:13 2007 UTC vs.
Revision 1.141 by root, Fri Oct 25 19:53:08 2013 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 and Perl, the deserialised data structure is identical on the Perl
54(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
55like a number). 71it looks like a number). There I<are> minor exceptions to this, read the
72MAPPING section 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.
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
87use strict; 104use common::sense;
88 105
89our $VERSION = '2.0'; 106our $VERSION = 2.34;
90our @ISA = qw(Exporter); 107our @ISA = qw(Exporter);
91 108
92our @EXPORT = qw(to_json from_json); 109our @EXPORT = qw(encode_json decode_json);
93 110
94use Exporter; 111use Exporter;
95use XSLoader; 112use XSLoader;
96 113
97=head1 FUNCTIONAL INTERFACE 114=head1 FUNCTIONAL INTERFACE
99The following convenience methods are provided by this module. They are 116The following convenience methods are provided by this module. They are
100exported by default: 117exported by default:
101 118
102=over 4 119=over 4
103 120
104=item $json_text = to_json $perl_scalar 121=item $json_text = encode_json $perl_scalar
105 122
106Converts the given Perl data structure to a UTF-8 encoded, binary string 123Converts the given Perl data structure to a UTF-8 encoded, binary string
107(that is, the string contains octets only). Croaks on error. 124(that is, the string contains octets only). Croaks on error.
108 125
109This function call is functionally identical to: 126This function call is functionally identical to:
110 127
111 $json_text = JSON::XS->new->utf8->encode ($perl_scalar) 128 $json_text = JSON::XS->new->utf8->encode ($perl_scalar)
112 129
113except being faster. 130Except being faster.
114 131
115=item $perl_scalar = from_json $json_text 132=item $perl_scalar = decode_json $json_text
116 133
117The opposite of C<to_json>: expects an UTF-8 (binary) string and tries 134The 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 135to parse that as an UTF-8 encoded JSON text, returning the resulting
119reference. Croaks on error. 136reference. Croaks on error.
120 137
121This function call is functionally identical to: 138This function call is functionally identical to:
122 139
123 $perl_scalar = JSON::XS->new->utf8->decode ($json_text) 140 $perl_scalar = JSON::XS->new->utf8->decode ($json_text)
124 141
125except being faster. 142Except being faster.
126 143
127=item $is_boolean = JSON::XS::is_bool $scalar 144=item $is_boolean = JSON::XS::is_bool $scalar
128 145
129Returns true if the passed scalar represents either JSON::XS::true or 146Returns 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 147JSON::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 165This enables you to store Unicode characters as single characters in a
149Perl string - very natural. 166Perl string - very natural.
150 167
151=item 2. Perl does I<not> associate an encoding with your strings. 168=item 2. Perl does I<not> associate an encoding with your strings.
152 169
153Unless you force it to, e.g. when matching it against a regex, or printing 170... 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 171printing the scalar to a file, in which case Perl either interprets your
155locale-encoded text, octets/binary, or as Unicode, depending on various 172string as locale-encoded text, octets/binary, or as Unicode, depending
156settings. In no case is an encoding stored together with your data, it is 173on various settings. In no case is an encoding stored together with your
157I<use> that decides encoding, not any magical metadata. 174data, it is I<use> that decides encoding, not any magical meta data.
158 175
159=item 3. The internal utf-8 flag has no meaning with regards to the 176=item 3. The internal utf-8 flag has no meaning with regards to the
160encoding of your string. 177encoding of your string.
161 178
162Just ignore that flag unless you debug a Perl bug, a module written in 179Just ignore that flag unless you debug a Perl bug, a module written in
168 185
169If 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
170exist. 187exist.
171 188
172=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
173validly interpreted as a Unicode codepoint. 190validly interpreted as a Unicode code point.
174 191
175If 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
176Unicode string encoded in UTF-8, giving you a binary string. 193Unicode string encoded in UTF-8, giving you a binary string.
177 194
178=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.
216 233
217If 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
218characters unless required by the JSON syntax or other flags. This results 235characters unless required by the JSON syntax or other flags. This results
219in a faster and more compact format. 236in a faster and more compact format.
220 237
238See also the section I<ENCODING/CODESET FLAG NOTES> later in this
239document.
240
221The 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
222transmitted 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
223contain any 8 bit characters. 243contain any 8 bit characters.
224 244
225 JSON::XS->new->ascii (1)->encode ([chr 0x10401]) 245 JSON::XS->new->ascii (1)->encode ([chr 0x10401])
236will 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
237expects Unicode, which is a strict superset of latin1. 257expects Unicode, which is a strict superset of latin1.
238 258
239If 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
240characters 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.
241 264
242The 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
243text, 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
244size. The disadvantage is that the resulting JSON text is encoded 267size. The disadvantage is that the resulting JSON text is encoded
245in latin1 (and must correctly be treated as such when storing and 268in latin1 (and must correctly be treated as such when storing and
264 287
265If 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
266string 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
267Unicode 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
268to 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.
269 295
270Example, output UTF-16BE-encoded JSON: 296Example, output UTF-16BE-encoded JSON:
271 297
272 use Encode; 298 use Encode;
273 $jsontext = encode "UTF-16BE", JSON::XS->new->encode ($object); 299 $jsontext = encode "UTF-16BE", JSON::XS->new->encode ($object);
396If 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
397by sorting their keys. This is adding a comparatively high overhead. 423by sorting their keys. This is adding a comparatively high overhead.
398 424
399If 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
400pairs 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
401of the same script). 427of the same script, and can change even within the same run from 5.18
428onwards).
402 429
403This 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
404the 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,
405the 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,
406as key-value pairs have no inherent ordering in Perl. 433as key-value pairs have no inherent ordering in Perl.
407 434
408This setting has no effect when decoding JSON texts. 435This setting has no effect when decoding JSON texts.
409 436
437This setting has currently no effect on tied hashes.
438
410=item $json = $json->allow_nonref ([$enable]) 439=item $json = $json->allow_nonref ([$enable])
411 440
412=item $enabled = $json->get_allow_nonref 441=item $enabled = $json->get_allow_nonref
413 442
414If 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
424Example, 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>,
425resulting in an invalid JSON text: 454resulting in an invalid JSON text:
426 455
427 JSON::XS->new->allow_nonref->encode ("Hello, World!") 456 JSON::XS->new->allow_nonref->encode ("Hello, World!")
428 => "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.
429 474
430=item $json = $json->allow_blessed ([$enable]) 475=item $json = $json->allow_blessed ([$enable])
431 476
432=item $enabled = $json->get_allow_blessed 477=item $enabled = $json->get_allow_blessed
433 478
455The C<TO_JSON> method may safely call die if it wants. If C<TO_JSON> 500The 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 501returns other blessed objects, those will be handled in the same
457way. C<TO_JSON> must take care of not causing an endless recursion cycle 502way. 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 503(== 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 504methods 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> 505usually in upper case letters and to avoid collisions with any C<to_json>
461function. 506function or method.
462 507
463This setting does not yet influence C<decode> in any way, but in the 508This 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 509future, global hooks might get installed that influence C<decode> and are
465enabled by this setting. 510enabled by this setting.
466 511
574=item $json = $json->max_depth ([$maximum_nesting_depth]) 619=item $json = $json->max_depth ([$maximum_nesting_depth])
575 620
576=item $max_depth = $json->get_max_depth 621=item $max_depth = $json->get_max_depth
577 622
578Sets the maximum nesting level (default C<512>) accepted while encoding 623Sets the maximum nesting level (default C<512>) accepted while encoding
579or 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
580higher nesting level then this limit, then the encoder and decoder will 625data structure, then the encoder and decoder will stop and croak at that
581stop and croak at that point. 626point.
582 627
583Nesting 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
584needs 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<[>
585characters without their matching closing parenthesis crossed to reach a 630characters without their matching closing parenthesis crossed to reach a
586given character in a string. 631given character in a string.
587 632
588Setting the maximum depth to one disallows any nesting, so that ensures 633Setting the maximum depth to one disallows any nesting, so that ensures
589that the object is only a single hash/object or array. 634that the object is only a single hash/object or array.
590 635
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 636If no argument is given, the highest possible setting will be used, which
593used, 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.
594 642
595See SECURITY CONSIDERATIONS, below, for more info on why this is useful. 643See SECURITY CONSIDERATIONS, below, for more info on why this is useful.
596 644
597=item $json = $json->max_size ([$maximum_string_size]) 645=item $json = $json->max_size ([$maximum_string_size])
598 646
599=item $max_size = $json->get_max_size 647=item $max_size = $json->get_max_size
600 648
601Set 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
602being 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>
603is 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
604attempt 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
605effect on C<encode> (yet). 653effect on C<encode> (yet).
606 654
607The 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
608power of two (so may be more than requested). If no argument is given, the 656C<0> is specified).
609limit check will be deactivated (same as when C<0> is specified).
610 657
611See SECURITY CONSIDERATIONS, below, for more info on why this is useful. 658See SECURITY CONSIDERATIONS, below, for more info on why this is useful.
612 659
613=item $json_text = $json->encode ($perl_scalar) 660=item $json_text = $json->encode ($perl_scalar)
614 661
615Converts the given Perl data structure (a simple scalar or a reference 662Converts the given Perl value or data structure to its JSON
616to a hash or array) to its JSON representation. Simple scalars will be 663representation. Croaks on error.
617converted into JSON string or number sequences, while references to arrays
618become JSON arrays and references to hashes become JSON objects. Undefined
619Perl values (e.g. C<undef>) become JSON C<null> values. Neither C<true>
620nor C<false> values will be generated.
621 664
622=item $perl_scalar = $json->decode ($json_text) 665=item $perl_scalar = $json->decode ($json_text)
623 666
624The 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,
625returning the resulting simple scalar or reference. Croaks on error. 668returning the resulting simple scalar or reference. Croaks on error.
626
627JSON numbers and strings become simple Perl scalars. JSON arrays become
628Perl arrayrefs and JSON objects become Perl hashrefs. C<true> becomes
629C<1>, C<false> becomes C<0> and C<null> becomes C<undef>.
630 669
631=item ($perl_scalar, $characters) = $json->decode_prefix ($json_text) 670=item ($perl_scalar, $characters) = $json->decode_prefix ($json_text)
632 671
633This 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
634when there is trailing garbage after the first JSON object, it will 673when there is trailing garbage after the first JSON object, it will
643 => ([], 3) 682 => ([], 3)
644 683
645=back 684=back
646 685
647 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
929
930
648=head1 MAPPING 931=head1 MAPPING
649 932
650This 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
651vice versa. These mappings are designed to "do the right thing" in most 934vice versa. These mappings are designed to "do the right thing" in most
652circumstances automatically, preserving round-tripping characteristics 935circumstances automatically, preserving round-tripping characteristics
680 963
681A JSON number becomes either an integer, numeric (floating point) or 964A JSON number becomes either an integer, numeric (floating point) or
682string scalar in perl, depending on its range and any fractional parts. On 965string 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 966the Perl level, there is no difference between those as Perl handles all
684the conversion details, but an integer may take slightly less memory and 967the conversion details, but an integer may take slightly less memory and
685might represent more values exactly than (floating point) numbers. 968might represent more values exactly than floating point numbers.
686 969
687If 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
688it 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
689a numeric (floating point) value if that is possible without loss of 972a numeric (floating point) value if that is possible without loss of
690precision. Otherwise it will preserve the number as a string value. 973precision. Otherwise it will preserve the number as a string value (in
974which case you lose roundtripping ability, as the JSON number will be
975re-encoded to a JSON string).
691 976
692Numbers containing a fractional or exponential part will always be 977Numbers containing a fractional or exponential part will always be
693represented as numeric (floating point) values, possibly at a loss of 978represented as numeric (floating point) values, possibly at a loss of
694precision. 979precision (in which case you might lose perfect roundtripping ability, but
980the JSON number will still be re-encoded as a JSON number).
695 981
696This might create round-tripping problems as numbers might become strings, 982Note that precision is not accuracy - binary floating point values cannot
697but as Perl is typeless there is no other way to do it. 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.
698 986
699=item true, false 987=item true, false
700 988
701These 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>,
702respectively. They are overloaded to act almost exactly like the numbers 990respectively. They are overloaded to act almost exactly like the numbers
739Other unblessed references are generally not allowed and will cause an 1027Other unblessed references are generally not allowed and will cause an
740exception to be thrown, except for references to the integers C<0> and 1028exception 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 1029C<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. 1030also use C<JSON::XS::false> and C<JSON::XS::true> to improve readability.
743 1031
744 to_json [\0,JSON::XS::true] # yields [false,true] 1032 encode_json [\0, JSON::XS::true] # yields [false,true]
745 1033
746=item JSON::XS::true, JSON::XS::false 1034=item JSON::XS::true, JSON::XS::false
747 1035
748These special values become JSON true and JSON false values, 1036These special values become JSON true and JSON false values,
749respectively. You can also use C<\1> and C<\0> directly if you want. 1037respectively. You can also use C<\1> and C<\0> directly if you want.
750 1038
751=item blessed objects 1039=item blessed objects
752 1040
753Blessed objects are not allowed. JSON::XS currently tries to encode their 1041Blessed objects are not directly representable in JSON. See the
754underlying representation (hash- or arrayref), but this behaviour might 1042C<allow_blessed> and C<convert_blessed> methods on various options on
755change in future versions. 1043how to deal with this: basically, you can choose between throwing an
1044exception, encoding the reference as if it weren't blessed, or provide
1045your own serialiser method.
756 1046
757=item simple scalars 1047=item simple scalars
758 1048
759Simple Perl scalars (any scalar that is not a reference) are the most 1049Simple Perl scalars (any scalar that is not a reference) are the most
760difficult objects to encode: JSON::XS will encode undefined scalars as 1050difficult objects to encode: JSON::XS will encode undefined scalars as
761JSON null value, scalars that have last been used in a string context 1051JSON C<null> values, scalars that have last been used in a string context
762before encoding as JSON strings and anything else as number value: 1052before encoding as JSON strings, and anything else as number value:
763 1053
764 # dump as number 1054 # dump as number
765 to_json [2] # yields [2] 1055 encode_json [2] # yields [2]
766 to_json [-3.0e17] # yields [-3e+17] 1056 encode_json [-3.0e17] # yields [-3e+17]
767 my $value = 5; to_json [$value] # yields [5] 1057 my $value = 5; encode_json [$value] # yields [5]
768 1058
769 # used as string, so dump as string 1059 # used as string, so dump as string
770 print $value; 1060 print $value;
771 to_json [$value] # yields ["5"] 1061 encode_json [$value] # yields ["5"]
772 1062
773 # undef becomes null 1063 # undef becomes null
774 to_json [undef] # yields [null] 1064 encode_json [undef] # yields [null]
775 1065
776You can force the type to be a JSON string by stringifying it: 1066You can force the type to be a JSON string by stringifying it:
777 1067
778 my $x = 3.1; # some variable containing a number 1068 my $x = 3.1; # some variable containing a number
779 "$x"; # stringified 1069 "$x"; # stringified
785 my $x = "3"; # some variable containing a string 1075 my $x = "3"; # some variable containing a string
786 $x += 0; # numify it, ensuring it will be dumped as a number 1076 $x += 0; # numify it, ensuring it will be dumped as a number
787 $x *= 1; # same thing, the choice is yours. 1077 $x *= 1; # same thing, the choice is yours.
788 1078
789You can not currently force the type in other, less obscure, ways. Tell me 1079You can not currently force the type in other, less obscure, ways. Tell me
790if you need this capability. 1080if you need this capability (but don't forget to explain why it's needed
1081:).
1082
1083Note that numerical precision has the same meaning as under Perl (so
1084binary to decimal conversion follows the same rules as in Perl, which
1085can differ to other languages). Also, your perl interpreter might expose
1086extensions to the floating point numbers of your platform, such as
1087infinities or NaN's - these cannot be represented in JSON, and it is an
1088error to pass those in.
791 1089
792=back 1090=back
793 1091
794 1092
795=head1 COMPARISON 1093=head1 ENCODING/CODESET FLAG NOTES
796 1094
797As already mentioned, this module was created because none of the existing 1095The interested reader might have seen a number of flags that signify
798JSON modules could be made to work correctly. First I will describe the 1096encodings or codesets - C<utf8>, C<latin1> and C<ascii>. There seems to be
799problems (or pleasures) I encountered with various existing JSON modules, 1097some confusion on what these do, so here is a short comparison:
800followed by some benchmark values. JSON::XS was designed not to suffer 1098
801from any of these problems or limitations. 1099C<utf8> controls whether the JSON text created by C<encode> (and expected
1100by C<decode>) is UTF-8 encoded or not, while C<latin1> and C<ascii> only
1101control whether C<encode> escapes character values outside their respective
1102codeset range. Neither of these flags conflict with each other, although
1103some combinations make less sense than others.
1104
1105Care has been taken to make all flags symmetrical with respect to
1106C<encode> and C<decode>, that is, texts encoded with any combination of
1107these flag values will be correctly decoded when the same flags are used
1108- in general, if you use different flag settings while encoding vs. when
1109decoding you likely have a bug somewhere.
1110
1111Below comes a verbose discussion of these flags. Note that a "codeset" is
1112simply an abstract set of character-codepoint pairs, while an encoding
1113takes those codepoint numbers and I<encodes> them, in our case into
1114octets. Unicode is (among other things) a codeset, UTF-8 is an encoding,
1115and ISO-8859-1 (= latin 1) and ASCII are both codesets I<and> encodings at
1116the same time, which can be confusing.
802 1117
803=over 4 1118=over 4
804 1119
805=item JSON 1.07 1120=item C<utf8> flag disabled
806 1121
807Slow (but very portable, as it is written in pure Perl). 1122When C<utf8> is disabled (the default), then C<encode>/C<decode> generate
1123and expect Unicode strings, that is, characters with high ordinal Unicode
1124values (> 255) will be encoded as such characters, and likewise such
1125characters are decoded as-is, no changes to them will be done, except
1126"(re-)interpreting" them as Unicode codepoints or Unicode characters,
1127respectively (to Perl, these are the same thing in strings unless you do
1128funny/weird/dumb stuff).
808 1129
809Undocumented/buggy Unicode handling (how JSON handles Unicode values is 1130This 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 1131want to have UTF-16 encoded JSON texts) or when some other layer does
811en-/decoding oneself, but Unicode escapes are not working properly). 1132the encoding for you (for example, when printing to a terminal using a
1133filehandle that transparently encodes to UTF-8 you certainly do NOT want
1134to UTF-8 encode your data first and have Perl encode it another time).
812 1135
813No round-tripping (strings get clobbered if they look like numbers, e.g. 1136=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 1137
817=item JSON::PC 0.01 1138If the C<utf8>-flag is enabled, C<encode>/C<decode> will encode all
1139characters using the corresponding UTF-8 multi-byte sequence, and will
1140expect your input strings to be encoded as UTF-8, that is, no "character"
1141of the input string must have any value > 255, as UTF-8 does not allow
1142that.
818 1143
819Very fast. 1144The C<utf8> flag therefore switches between two modes: disabled means you
1145will get a Unicode string in Perl, enabled means you get an UTF-8 encoded
1146octet/binary string in Perl.
820 1147
821Undocumented/buggy Unicode handling. 1148=item C<latin1> or C<ascii> flags enabled
822 1149
823No round-tripping. 1150With C<latin1> (or C<ascii>) enabled, C<encode> will escape characters
1151with ordinal values > 255 (> 127 with C<ascii>) and encode the remaining
1152characters as specified by the C<utf8> flag.
824 1153
825Has problems handling many Perl values (e.g. regex results and other magic 1154If C<utf8> is disabled, then the result is also correctly encoded in those
826values will make it croak). 1155character sets (as both are proper subsets of Unicode, meaning that a
1156Unicode string with all character values < 256 is the same thing as a
1157ISO-8859-1 string, and a Unicode string with all character values < 128 is
1158the same thing as an ASCII string in Perl).
827 1159
828Does not even generate valid JSON (C<{1,2}> gets converted to C<{1:2}> 1160If C<utf8> is enabled, you still get a correct UTF-8-encoded string,
829which is not a valid JSON text. 1161regardless of these flags, just some more characters will be escaped using
1162C<\uXXXX> then before.
830 1163
831Unmaintained (maintainer unresponsive for many months, bugs are not 1164Note that ISO-8859-1-I<encoded> strings are not compatible with UTF-8
832getting fixed). 1165encoding, while ASCII-encoded strings are. That is because the ISO-8859-1
1166encoding is NOT a subset of UTF-8 (despite the ISO-8859-1 I<codeset> being
1167a subset of Unicode), while ASCII is.
833 1168
834=item JSON::Syck 0.21 1169Surprisingly, C<decode> will ignore these flags and so treat all input
1170values as governed by the C<utf8> flag. If it is disabled, this allows you
1171to decode ISO-8859-1- and ASCII-encoded strings, as both strict subsets of
1172Unicode. If it is enabled, you can correctly decode UTF-8 encoded strings.
835 1173
836Very buggy (often crashes). 1174So neither C<latin1> nor C<ascii> are incompatible with the C<utf8> flag -
1175they only govern when the JSON output engine escapes a character or not.
837 1176
838Very inflexible (no human-readable format supported, format pretty much 1177The 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 1178as 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 1179
843Completely broken (and confusingly documented) Unicode handling (Unicode 1180The 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 1181with values > 127, which means you can interpret the resulting string
845I<different> values on en- and decoding to get symmetric behaviour). 1182as UTF-8, ISO-8859-1, ASCII, KOI8-R or most about any character set and
846 11838-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 1184when your channel for JSON transfer is not 8-bit clean or the encoding
848value was used in a numeric context or not). 1185might be mangled in between (e.g. in mail), and works because ASCII is a
849 1186proper 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 1187
879=back 1188=back
880 1189
881 1190
1191=head2 JSON and ECMAscript
1192
1193JSON syntax is based on how literals are represented in javascript (the
1194not-standardised predecessor of ECMAscript) which is presumably why it is
1195called "JavaScript Object Notation".
1196
1197However, JSON is not a subset (and also not a superset of course) of
1198ECMAscript (the standard) or javascript (whatever browsers actually
1199implement).
1200
1201If you want to use javascript's C<eval> function to "parse" JSON, you
1202might run into parse errors for valid JSON texts, or the resulting data
1203structure might not be queryable:
1204
1205One of the problems is that U+2028 and U+2029 are valid characters inside
1206JSON strings, but are not allowed in ECMAscript string literals, so the
1207following Perl fragment will not output something that can be guaranteed
1208to be parsable by javascript's C<eval>:
1209
1210 use JSON::XS;
1211
1212 print encode_json [chr 0x2028];
1213
1214The right fix for this is to use a proper JSON parser in your javascript
1215programs, and not rely on C<eval> (see for example Douglas Crockford's
1216F<json2.js> parser).
1217
1218If this is not an option, you can, as a stop-gap measure, simply encode to
1219ASCII-only JSON:
1220
1221 use JSON::XS;
1222
1223 print JSON::XS->new->ascii->encode ([chr 0x2028]);
1224
1225Note that this will enlarge the resulting JSON text quite a bit if you
1226have many non-ASCII characters. You might be tempted to run some regexes
1227to only escape U+2028 and U+2029, e.g.:
1228
1229 # DO NOT USE THIS!
1230 my $json = JSON::XS->new->utf8->encode ([chr 0x2028]);
1231 $json =~ s/\xe2\x80\xa8/\\u2028/g; # escape U+2028
1232 $json =~ s/\xe2\x80\xa9/\\u2029/g; # escape U+2029
1233 print $json;
1234
1235Note that I<this is a bad idea>: the above only works for U+2028 and
1236U+2029 and thus only for fully ECMAscript-compliant parsers. Many existing
1237javascript implementations, however, have issues with other characters as
1238well - using C<eval> naively simply I<will> cause problems.
1239
1240Another problem is that some javascript implementations reserve
1241some property names for their own purposes (which probably makes
1242them non-ECMAscript-compliant). For example, Iceweasel reserves the
1243C<__proto__> property name for its own purposes.
1244
1245If that is a problem, you could parse try to filter the resulting JSON
1246output for these property strings, e.g.:
1247
1248 $json =~ s/"__proto__"\s*:/"__proto__renamed":/g;
1249
1250This works because C<__proto__> is not valid outside of strings, so every
1251occurrence of C<"__proto__"\s*:> must be a string used as property name.
1252
1253If you know of other incompatibilities, please let me know.
1254
1255
882=head2 JSON and YAML 1256=head2 JSON and YAML
883 1257
884You often hear that JSON is a subset (or a close subset) of YAML. This is, 1258You 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 1259hysteria(*) 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. 1260so let me state it clearly: I<in general, there is no way to configure
1261JSON::XS to output a data structure as valid YAML> that works in all
1262cases.
887 1263
888If you really must use JSON::XS to generate YAML, you should use this 1264If you really must use JSON::XS to generate YAML, you should use this
889algorithm (subject to change in future versions): 1265algorithm (subject to change in future versions):
890 1266
891 my $to_yaml = JSON::XS->new->utf8->space_after (1); 1267 my $to_yaml = JSON::XS->new->utf8->space_after (1);
892 my $yaml = $to_yaml->encode ($ref) . "\n"; 1268 my $yaml = $to_yaml->encode ($ref) . "\n";
893 1269
894This will usually generate JSON texts that also parse as valid 1270This will I<usually> generate JSON texts that also parse as valid
895YAML. Please note that YAML has hardcoded limits on (simple) object key 1271YAML. 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 1272lengths that JSON doesn't have and also has different and incompatible
1273unicode character escape syntax, so you should make sure that your hash
897keys are noticeably shorter than the 1024 characters YAML allows. 1274keys are noticeably shorter than the 1024 "stream characters" YAML allows
1275and that you do not have characters with codepoint values outside the
1276Unicode BMP (basic multilingual page). YAML also does not allow C<\/>
1277sequences in strings (which JSON::XS does not I<currently> generate, but
1278other JSON generators might).
898 1279
899There might be other incompatibilities that I am not aware of. In general 1280There might be other incompatibilities that I am not aware of (or the YAML
1281specification 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, 1282general 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 1283versa, or try to parse JSON with a YAML parser or vice versa: chances are
902that you will run into severe interoperability problems. 1284high that you will run into severe interoperability problems when you
1285least expect it.
1286
1287=over 4
1288
1289=item (*)
1290
1291I have been pressured multiple times by Brian Ingerson (one of the
1292authors of the YAML specification) to remove this paragraph, despite him
1293acknowledging that the actual incompatibilities exist. As I was personally
1294bitten by this "JSON is YAML" lie, I refused and said I will continue to
1295educate people about these issues, so others do not run into the same
1296problem again and again. After this, Brian called me a (quote)I<complete
1297and worthless idiot>(unquote).
1298
1299In my opinion, instead of pressuring and insulting people who actually
1300clarify issues with YAML and the wrong statements of some of its
1301proponents, I would kindly suggest reading the JSON spec (which is not
1302that difficult or long) and finally make YAML compatible to it, and
1303educating users about the changes, instead of spreading lies about the
1304real compatibility for many I<years> and trying to silence people who
1305point out that it isn't true.
1306
1307Addendum/2009: the YAML 1.2 spec is still incompatible with JSON, even
1308though the incompatibilities have been documented (and are known to Brian)
1309for many years and the spec makes explicit claims that YAML is a superset
1310of JSON. It would be so easy to fix, but apparently, bullying people and
1311corrupting userdata is so much easier.
1312
1313=back
903 1314
904 1315
905=head2 SPEED 1316=head2 SPEED
906 1317
907It seems that JSON::XS is surprisingly fast, as shown in the following 1318It 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 1319tables. 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 1320in the JSON::XS distribution, to make it easy to compare on your own
910system. 1321system.
911 1322
912First comes a comparison between various modules using a very short 1323First comes a comparison between various modules using
913single-line JSON string: 1324a very short single-line JSON string (also available at
1325L<http://dist.schmorp.de/misc/json/short.json>).
914 1326
915 {"method": "handleMessage", "params": ["user1", "we were just talking"], \ 1327 {"method": "handleMessage", "params": ["user1",
916 "id": null, "array":[1,11,234,-5,1e5,1e7, true, false]} 1328 "we were just talking"], "id": null, "array":[1,11,234,-5,1e5,1e7,
1329 1, 0]}
917 1330
918It shows the number of encodes/decodes per second (JSON::XS uses 1331It shows the number of encodes/decodes per second (JSON::XS uses
919the functional interface, while JSON::XS/2 uses the OO interface 1332the functional interface, while JSON::XS/2 uses the OO interface
920with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables 1333with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables
921shrink). Higher is better: 1334shrink. JSON::DWIW/DS uses the deserialise function, while JSON::DWIW::FJ
1335uses the from_json method). Higher is better:
922 1336
923 module | encode | decode | 1337 module | encode | decode |
924 -----------|------------|------------| 1338 --------------|------------|------------|
925 JSON 1.x | 4990.842 | 4088.813 | 1339 JSON::DWIW/DS | 86302.551 | 102300.098 |
926 JSON::DWIW | 51653.990 | 71575.154 | 1340 JSON::DWIW/FJ | 86302.551 | 75983.768 |
927 JSON::PC | 65948.176 | 74631.744 | 1341 JSON::PP | 15827.562 | 6638.658 |
928 JSON::PP | 8931.652 | 3817.168 | 1342 JSON::Syck | 63358.066 | 47662.545 |
929 JSON::Syck | 24877.248 | 27776.848 | 1343 JSON::XS | 511500.488 | 511500.488 |
930 JSON::XS | 388361.481 | 227951.304 | 1344 JSON::XS/2 | 291271.111 | 388361.481 |
931 JSON::XS/2 | 227951.304 | 218453.333 | 1345 JSON::XS/3 | 361577.931 | 361577.931 |
932 JSON::XS/3 | 338250.323 | 218453.333 | 1346 Storable | 66788.280 | 265462.278 |
933 Storable | 16500.016 | 135300.129 |
934 -----------+------------+------------+ 1347 --------------+------------+------------+
935 1348
936That is, JSON::XS is about five times faster than JSON::DWIW on encoding, 1349That is, JSON::XS is almost six times faster than JSON::DWIW on encoding,
937about three times faster on decoding, and over forty times faster 1350about five times faster on decoding, and over thirty to seventy times
938than JSON, even with pretty-printing and key sorting. It also compares 1351faster than JSON's pure perl implementation. It also compares favourably
939favourably to Storable for small amounts of data. 1352to Storable for small amounts of data.
940 1353
941Using a longer test string (roughly 18KB, generated from Yahoo! Locals 1354Using a longer test string (roughly 18KB, generated from Yahoo! Locals
942search API (http://nanoref.com/yahooapis/mgPdGg): 1355search API (L<http://dist.schmorp.de/misc/json/long.json>).
943 1356
944 module | encode | decode | 1357 module | encode | decode |
945 -----------|------------|------------| 1358 --------------|------------|------------|
946 JSON 1.x | 55.260 | 34.971 | 1359 JSON::DWIW/DS | 1647.927 | 2673.916 |
947 JSON::DWIW | 825.228 | 1082.513 | 1360 JSON::DWIW/FJ | 1630.249 | 2596.128 |
948 JSON::PC | 3571.444 | 2394.829 |
949 JSON::PP | 210.987 | 32.574 | 1361 JSON::PP | 400.640 | 62.311 |
950 JSON::Syck | 552.551 | 787.544 | 1362 JSON::Syck | 1481.040 | 1524.869 |
951 JSON::XS | 5780.463 | 4854.519 | 1363 JSON::XS | 20661.596 | 9541.183 |
952 JSON::XS/2 | 3869.998 | 4798.975 | 1364 JSON::XS/2 | 10683.403 | 9416.938 |
953 JSON::XS/3 | 5862.880 | 4798.975 | 1365 JSON::XS/3 | 20661.596 | 9400.054 |
954 Storable | 4445.002 | 5235.027 | 1366 Storable | 19765.806 | 10000.725 |
955 -----------+------------+------------+ 1367 --------------+------------+------------+
956 1368
957Again, JSON::XS leads by far (except for Storable which non-surprisingly 1369Again, JSON::XS leads by far (except for Storable which non-surprisingly
958decodes faster). 1370decodes a bit faster).
959 1371
960On large strings containing lots of high Unicode characters, some modules 1372On large strings containing lots of high Unicode characters, some modules
961(such as JSON::PC) seem to decode faster than JSON::XS, but the result 1373(such as JSON::PC) seem to decode faster than JSON::XS, but the result
962will be broken due to missing (or wrong) Unicode handling. Others refuse 1374will be broken due to missing (or wrong) Unicode handling. Others refuse
963to decode or encode properly, so it was impossible to prepare a fair 1375to decode or encode properly, so it was impossible to prepare a fair
984 1396
985Third, JSON::XS recurses using the C stack when decoding objects and 1397Third, JSON::XS recurses using the C stack when decoding objects and
986arrays. The C stack is a limited resource: for instance, on my amd64 1398arrays. 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 1399machine 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 1400only 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 1401to free the temporary). If that is exceeded, the program crashes. To be
990conservative, the default nesting limit is set to 512. If your process 1402conservative, the default nesting limit is set to 512. If your process
991has a smaller stack, you should adjust this setting accordingly with the 1403has a smaller stack, you should adjust this setting accordingly with the
992C<max_depth> method. 1404C<max_depth> method.
993 1405
994And last but least, something else could bomb you that I forgot to think 1406Something 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, 1407case, you get to keep the pieces. I am always open for hints, though...
996though... 1408
1409Also keep in mind that JSON::XS might leak contents of your Perl data
1410structures in its error messages, so when you serialise sensitive
1411information you might want to make sure that exceptions thrown by JSON::XS
1412will not end up in front of untrusted eyes.
997 1413
998If you are using JSON::XS to return packets to consumption 1414If you are using JSON::XS to return packets to consumption
999by JavaScript scripts in a browser you should have a look at 1415by JavaScript scripts in a browser you should have a look at
1000L<http://jpsykes.com/47/practical-csrf-and-json-security> to see whether 1416L<http://blog.archive.jpsykes.com/47/practical-csrf-and-json-security/> to
1001you are vulnerable to some common attack vectors (which really are browser 1417see whether you are vulnerable to some common attack vectors (which really
1002design bugs, but it is still you who will have to deal with it, as major 1418are browser design bugs, but it is still you who will have to deal with
1003browser developers care only for features, not about doing security 1419it, as major browser developers care only for features, not about getting
1004right). 1420security right).
1005 1421
1006 1422
1007=head1 THREADS 1423=head1 THREADS
1008 1424
1009This module is I<not> guaranteed to be thread safe and there are no 1425This 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 1426plans to change this until Perl gets thread support (as opposed to the
1011horribly slow so-called "threads" which are simply slow and bloated 1427horribly slow so-called "threads" which are simply slow and bloated
1012process simulations - use fork, its I<much> faster, cheaper, better). 1428process simulations - use fork, it's I<much> faster, cheaper, better).
1013 1429
1014(It might actually work, but you have been warned). 1430(It might actually work, but you have been warned).
1015 1431
1016 1432
1433=head1 THE PERILS OF SETLOCALE
1434
1435Sometimes people avoid the Perl locale support and directly call the
1436system's setlocale function with C<LC_ALL>.
1437
1438This breaks both perl and modules such as JSON::XS, as stringification of
1439numbers no longer works correctly (e.g. C<$x = 0.1; print "$x"+1> might
1440print C<1>, and JSON::XS might output illegal JSON as JSON::XS relies on
1441perl to stringify numbers).
1442
1443The solution is simple: don't call C<setlocale>, or use it for only those
1444categories you need, such as C<LC_MESSAGES> or C<LC_CTYPE>.
1445
1446If you need C<LC_NUMERIC>, you should enable it only around the code that
1447actually needs it (avoiding stringification of numbers), and restore it
1448afterwards.
1449
1450
1017=head1 BUGS 1451=head1 BUGS
1018 1452
1019While the goal of this module is to be correct, that unfortunately does 1453While 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 1454not 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 1455keep reporting bugs they will be fixed swiftly, though.
1022will be fixed swiftly, though.
1023 1456
1024Please refrain from using rt.cpan.org or any other bug reporting 1457Please refrain from using rt.cpan.org or any other bug reporting
1025service. I put the contact address into my modules for a reason. 1458service. I put the contact address into my modules for a reason.
1026 1459
1027=cut 1460=cut
1047 "--" => sub { $_[0] = ${$_[0]} - 1 }, 1480 "--" => sub { $_[0] = ${$_[0]} - 1 },
1048 fallback => 1; 1481 fallback => 1;
1049 1482
10501; 14831;
1051 1484
1485=head1 SEE ALSO
1486
1487The F<json_xs> command line utility for quick experiments.
1488
1052=head1 AUTHOR 1489=head1 AUTHOR
1053 1490
1054 Marc Lehmann <schmorp@schmorp.de> 1491 Marc Lehmann <schmorp@schmorp.de>
1055 http://home.schmorp.de/ 1492 http://home.schmorp.de/
1056 1493

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines