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.88 by root, Wed Mar 19 13:44:41 2008 UTC vs.
Revision 1.145 by root, Tue Oct 29 00:06:40 2013 UTC

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

Diff Legend

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