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.103 by root, Tue Apr 29 16:07:56 2008 UTC vs.
Revision 1.143 by root, Fri Oct 25 20:02:54 2013 UTC

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.2'; 106our $VERSION = 2.34;
109our @ISA = qw(Exporter); 107our @ISA = qw(Exporter);
110 108
111our @EXPORT = qw(encode_json decode_json to_json from_json); 109our @EXPORT = qw(encode_json decode_json);
112
113sub to_json($) {
114 require Carp;
115 Carp::croak ("JSON::XS::to_json has been renamed to encode_json, either downgrade to pre-2.0 versions of JSON::XS or rename the call");
116}
117
118sub from_json($) {
119 require Carp;
120 Carp::croak ("JSON::XS::from_json has been renamed to decode_json, either downgrade to pre-2.0 versions of JSON::XS or rename the call");
121}
122 110
123use Exporter; 111use Exporter;
124use XSLoader; 112use XSLoader;
125 113
126=head1 FUNCTIONAL INTERFACE 114=head1 FUNCTIONAL INTERFACE
137 125
138This function call is functionally identical to: 126This function call is functionally identical to:
139 127
140 $json_text = JSON::XS->new->utf8->encode ($perl_scalar) 128 $json_text = JSON::XS->new->utf8->encode ($perl_scalar)
141 129
142except being faster. 130Except being faster.
143 131
144=item $perl_scalar = decode_json $json_text 132=item $perl_scalar = decode_json $json_text
145 133
146The opposite of C<encode_json>: expects an UTF-8 (binary) string and tries 134The opposite of C<encode_json>: expects an UTF-8 (binary) string and tries
147to parse that as an UTF-8 encoded JSON text, returning the resulting 135to parse that as an UTF-8 encoded JSON text, returning the resulting
149 137
150This function call is functionally identical to: 138This function call is functionally identical to:
151 139
152 $perl_scalar = JSON::XS->new->utf8->decode ($json_text) 140 $perl_scalar = JSON::XS->new->utf8->decode ($json_text)
153 141
154except being faster. 142Except being faster.
155 143
156=item $is_boolean = JSON::XS::is_bool $scalar 144=item $is_boolean = JSON::XS::is_bool $scalar
157 145
158Returns true if the passed scalar represents either JSON::XS::true or 146Returns true if the passed scalar represents either JSON::XS::true or
159JSON::XS::false, two constants that act like C<1> and C<0>, respectively 147JSON::XS::false, two constants that act like C<1> and C<0>, respectively
197 185
198If you didn't know about that flag, just the better, pretend it doesn't 186If you didn't know about that flag, just the better, pretend it doesn't
199exist. 187exist.
200 188
201=item 4. A "Unicode String" is simply a string where each character can be 189=item 4. A "Unicode String" is simply a string where each character can be
202validly interpreted as a Unicode codepoint. 190validly interpreted as a Unicode code point.
203 191
204If you have UTF-8 encoded data, it is no longer a Unicode string, but a 192If you have UTF-8 encoded data, it is no longer a Unicode string, but a
205Unicode string encoded in UTF-8, giving you a binary string. 193Unicode string encoded in UTF-8, giving you a binary string.
206 194
207=item 5. A string containing "high" (> 255) character values is I<not> a UTF-8 string. 195=item 5. A string containing "high" (> 255) character values is I<not> a UTF-8 string.
434If 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
435by sorting their keys. This is adding a comparatively high overhead. 423by sorting their keys. This is adding a comparatively high overhead.
436 424
437If 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
438pairs 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
439of the same script). 427of the same script, and can change even within the same run from 5.18
428onwards).
440 429
441This 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
442the 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,
443the 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,
444as key-value pairs have no inherent ordering in Perl. 433as key-value pairs have no inherent ordering in Perl.
445 434
446This setting has no effect when decoding JSON texts. 435This setting has no effect when decoding JSON texts.
436
437This setting has currently no effect on tied hashes.
447 438
448=item $json = $json->allow_nonref ([$enable]) 439=item $json = $json->allow_nonref ([$enable])
449 440
450=item $enabled = $json->get_allow_nonref 441=item $enabled = $json->get_allow_nonref
451 442
666 657
667See SECURITY CONSIDERATIONS, below, for more info on why this is useful. 658See SECURITY CONSIDERATIONS, below, for more info on why this is useful.
668 659
669=item $json_text = $json->encode ($perl_scalar) 660=item $json_text = $json->encode ($perl_scalar)
670 661
671Converts the given Perl data structure (a simple scalar or a reference 662Converts the given Perl value or data structure to its JSON
672to a hash or array) to its JSON representation. Simple scalars will be 663representation. Croaks on error.
673converted into JSON string or number sequences, while references to arrays
674become JSON arrays and references to hashes become JSON objects. Undefined
675Perl values (e.g. C<undef>) become JSON C<null> values. Neither C<true>
676nor C<false> values will be generated.
677 664
678=item $perl_scalar = $json->decode ($json_text) 665=item $perl_scalar = $json->decode ($json_text)
679 666
680The 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,
681returning the resulting simple scalar or reference. Croaks on error. 668returning the resulting simple scalar or reference. Croaks on error.
682
683JSON numbers and strings become simple Perl scalars. JSON arrays become
684Perl arrayrefs and JSON objects become Perl hashrefs. C<true> becomes
685C<1>, C<false> becomes C<0> and C<null> becomes C<undef>.
686 669
687=item ($perl_scalar, $characters) = $json->decode_prefix ($json_text) 670=item ($perl_scalar, $characters) = $json->decode_prefix ($json_text)
688 671
689This 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
690when there is trailing garbage after the first JSON object, it will 673when there is trailing garbage after the first JSON object, it will
691silently stop parsing there and return the number of characters consumed 674silently stop parsing there and return the number of characters consumed
692so far. 675so far.
693 676
694This is useful if your JSON texts are not delimited by an outer protocol 677This is useful if your JSON texts are not delimited by an outer protocol
695(which is not the brightest thing to do in the first place) and you need
696to know where the JSON text ends. 678and you need to know where the JSON text ends.
697 679
698 JSON::XS->new->decode_prefix ("[1] the tail") 680 JSON::XS->new->decode_prefix ("[1] the tail")
699 => ([], 3) 681 => ([], 3)
700 682
701=back 683=back
702 684
703 685
704=head1 INCREMENTAL PARSING 686=head1 INCREMENTAL PARSING
705
706[This section and the API it details is still EXPERIMENTAL]
707 687
708In some cases, there is the need for incremental parsing of JSON 688In some cases, there is the need for incremental parsing of JSON
709texts. While this module always has to keep both JSON text and resulting 689texts. While this module always has to keep both JSON text and resulting
710Perl data structure in memory at one time, it does allow you to parse a 690Perl data structure in memory at one time, it does allow you to parse a
711JSON stream incrementally. It does so by accumulating text until it has 691JSON stream incrementally. It does so by accumulating text until it has
712a full JSON object, which it then can decode. This process is similar to 692a full JSON object, which it then can decode. This process is similar to
713using C<decode_prefix> to see if a full JSON object is available, but is 693using C<decode_prefix> to see if a full JSON object is available, but
714much more efficient (JSON::XS will only attempt to parse the JSON text 694is much more efficient (and can be implemented with a minimum of method
695calls).
696
697JSON::XS will only attempt to parse the JSON text once it is sure it
715once it is sure it has enough text to get a decisive result, using a very 698has enough text to get a decisive result, using a very simple but
716simple but truly incremental parser). 699truly incremental parser. This means that it sometimes won't stop as
700early as the full parser, for example, it doesn't detect mismatched
701parentheses. The only thing it guarantees is that it starts decoding as
702soon as a syntactically valid JSON text has been seen. This means you need
703to set resource limits (e.g. C<max_size>) to ensure the parser will stop
704parsing in the presence if syntax errors.
717 705
718The following two methods deal with this. 706The following methods implement this incremental parser.
719 707
720=over 4 708=over 4
721 709
722=item [void, scalar or list context] = $json->incr_parse ([$string]) 710=item [void, scalar or list context] = $json->incr_parse ([$string])
723 711
734 722
735If the method is called in scalar context, then it will try to extract 723If the method is called in scalar context, then it will try to extract
736exactly I<one> JSON object. If that is successful, it will return this 724exactly I<one> JSON object. If that is successful, it will return this
737object, otherwise it will return C<undef>. If there is a parse error, 725object, otherwise it will return C<undef>. If there is a parse error,
738this method will croak just as C<decode> would do (one can then use 726this method will croak just as C<decode> would do (one can then use
739C<incr_skip> to skip the errornous part). This is the most common way of 727C<incr_skip> to skip the erroneous part). This is the most common way of
740using the method. 728using the method.
741 729
742And finally, in list context, it will try to extract as many objects 730And finally, in list context, it will try to extract as many objects
743from the stream as it can find and return them, or the empty list 731from the stream as it can find and return them, or the empty list
744otherwise. For this to work, there must be no separators between the JSON 732otherwise. For this to work, there must be no separators between the JSON
745objects or arrays, instead they must be concatenated back-to-back. If 733objects or arrays, instead they must be concatenated back-to-back. If
746an error occurs, an exception will be raised as in the scalar context 734an error occurs, an exception will be raised as in the scalar context
747case. Note that in this case, any previously-parsed JSON texts will be 735case. Note that in this case, any previously-parsed JSON texts will be
748lost. 736lost.
749 737
738Example: Parse some JSON arrays/objects in a given string and return
739them.
740
741 my @objs = JSON::XS->new->incr_parse ("[5][7][1,2]");
742
750=item $lvalue_string = $json->incr_text 743=item $lvalue_string = $json->incr_text
751 744
752This method returns the currently stored JSON fragment as an lvalue, that 745This method returns the currently stored JSON fragment as an lvalue, that
753is, you can manipulate it. This I<only> works when a preceding call to 746is, you can manipulate it. This I<only> works when a preceding call to
754C<incr_parse> in I<scalar context> successfully returned an object. Under 747C<incr_parse> in I<scalar context> successfully returned an object. Under
761JSON object or b) parsing multiple JSON objects separated by non-JSON text 754JSON object or b) parsing multiple JSON objects separated by non-JSON text
762(such as commas). 755(such as commas).
763 756
764=item $json->incr_skip 757=item $json->incr_skip
765 758
766This will reset the state of the incremental parser and will remove the 759This will reset the state of the incremental parser and will remove
767parsed text from the input buffer. This is useful after C<incr_parse> 760the parsed text from the input buffer so far. This is useful after
768died, in which case the input buffer and incremental parser state is left 761C<incr_parse> died, in which case the input buffer and incremental parser
769unchanged, to skip the text parsed so far and to reset the parse state. 762state is left unchanged, to skip the text parsed so far and to reset the
763parse state.
764
765The difference to C<incr_reset> is that only text until the parse error
766occurred is removed.
767
768=item $json->incr_reset
769
770This completely resets the incremental parser, that is, after this call,
771it will be as if the parser had never parsed anything.
772
773This is useful if you want to repeatedly parse JSON objects and want to
774ignore any trailing data, which means you have to reset the parser after
775each successful decode.
770 776
771=back 777=back
772 778
773=head2 LIMITATIONS 779=head2 LIMITATIONS
774 780
775All options that affect decoding are supported, except 781All options that affect decoding are supported, except
776C<allow_nonref>. The reason for this is that it cannot be made to 782C<allow_nonref>. The reason for this is that it cannot be made to work
777work sensibly: JSON objects and arrays are self-delimited, i.e. you can concatenate 783sensibly: JSON objects and arrays are self-delimited, i.e. you can
778them back to back and still decode them perfectly. This does not hold true 784concatenate them back to back and still decode them perfectly. This does
779for JSON numbers, however. 785not hold true for JSON numbers, however.
780 786
781For example, is the string C<1> a single JSON number, or is it simply the 787For example, is the string C<1> a single JSON number, or is it simply the
782start of C<12>? Or is C<12> a single JSON number, or the concatenation 788start of C<12>? Or is C<12> a single JSON number, or the concatenation
783of C<1> and C<2>? In neither case you can tell, and this is why JSON::XS 789of C<1> and C<2>? In neither case you can tell, and this is why JSON::XS
784takes the conservative route and disallows this case. 790takes the conservative route and disallows this case.
963If the number consists of digits only, JSON::XS will try to represent 969If the number consists of digits only, JSON::XS will try to represent
964it as an integer value. If that fails, it will try to represent it as 970it as an integer value. If that fails, it will try to represent it as
965a numeric (floating point) value if that is possible without loss of 971a numeric (floating point) value if that is possible without loss of
966precision. Otherwise it will preserve the number as a string value (in 972precision. Otherwise it will preserve the number as a string value (in
967which case you lose roundtripping ability, as the JSON number will be 973which case you lose roundtripping ability, as the JSON number will be
968re-encoded toa JSON string). 974re-encoded to a JSON string).
969 975
970Numbers containing a fractional or exponential part will always be 976Numbers containing a fractional or exponential part will always be
971represented as numeric (floating point) values, possibly at a loss of 977represented as numeric (floating point) values, possibly at a loss of
972precision (in which case you might lose perfect roundtripping ability, but 978precision (in which case you might lose perfect roundtripping ability, but
973the JSON number will still be re-encoded as a JSON number). 979the JSON number will still be re-encoded as a JSON number).
974 980
981Note that precision is not accuracy - binary floating point values cannot
982represent most decimal fractions exactly, and when converting from and to
983floating point, JSON::XS only guarantees precision up to but not including
984the least significant bit.
985
975=item true, false 986=item true, false
976 987
977These JSON atoms become C<JSON::XS::true> and C<JSON::XS::false>, 988These JSON atoms become C<JSON::XS::true> and C<JSON::XS::false>,
978respectively. They are overloaded to act almost exactly like the numbers 989respectively. They are overloaded to act almost exactly like the numbers
979C<1> and C<0>. You can check whether a scalar is a JSON boolean by using 990C<1> and C<0>. You can check whether a scalar is a JSON boolean by using
994 1005
995=over 4 1006=over 4
996 1007
997=item hash references 1008=item hash references
998 1009
999Perl hash references become JSON objects. As there is no inherent ordering 1010Perl hash references become JSON objects. As there is no inherent
1000in hash keys (or JSON objects), they will usually be encoded in a 1011ordering in hash keys (or JSON objects), they will usually be encoded
1001pseudo-random order that can change between runs of the same program but 1012in a pseudo-random order. JSON::XS can optionally sort the hash keys
1002stays generally the same within a single run of a program. JSON::XS can 1013(determined by the I<canonical> flag), so the same datastructure will
1003optionally sort the hash keys (determined by the I<canonical> flag), so 1014serialise to the same JSON text (given same settings and version of
1004the same datastructure will serialise to the same JSON text (given same 1015JSON::XS), but this incurs a runtime overhead and is only rarely useful,
1005settings and version of JSON::XS), but this incurs a runtime overhead 1016e.g. when you want to compare some JSON text against another for equality.
1006and is only rarely useful, e.g. when you want to compare some JSON text
1007against another for equality.
1008 1017
1009=item array references 1018=item array references
1010 1019
1011Perl array references become JSON arrays. 1020Perl array references become JSON arrays.
1012 1021
1015Other unblessed references are generally not allowed and will cause an 1024Other unblessed references are generally not allowed and will cause an
1016exception to be thrown, except for references to the integers C<0> and 1025exception to be thrown, except for references to the integers C<0> and
1017C<1>, which get turned into C<false> and C<true> atoms in JSON. You can 1026C<1>, which get turned into C<false> and C<true> atoms in JSON. You can
1018also use C<JSON::XS::false> and C<JSON::XS::true> to improve readability. 1027also use C<JSON::XS::false> and C<JSON::XS::true> to improve readability.
1019 1028
1020 encode_json [\0,JSON::XS::true] # yields [false,true] 1029 encode_json [\0, JSON::XS::true] # yields [false,true]
1021 1030
1022=item JSON::XS::true, JSON::XS::false 1031=item JSON::XS::true, JSON::XS::false
1023 1032
1024These special values become JSON true and JSON false values, 1033These special values become JSON true and JSON false values,
1025respectively. You can also use C<\1> and C<\0> directly if you want. 1034respectively. You can also use C<\1> and C<\0> directly if you want.
1065 $x *= 1; # same thing, the choice is yours. 1074 $x *= 1; # same thing, the choice is yours.
1066 1075
1067You can not currently force the type in other, less obscure, ways. Tell me 1076You can not currently force the type in other, less obscure, ways. Tell me
1068if you need this capability (but don't forget to explain why it's needed 1077if you need this capability (but don't forget to explain why it's needed
1069:). 1078:).
1079
1080Note that numerical precision has the same meaning as under Perl (so
1081binary to decimal conversion follows the same rules as in Perl, which
1082can differ to other languages). Also, your perl interpreter might expose
1083extensions to the floating point numbers of your platform, such as
1084infinities or NaN's - these cannot be represented in JSON, and it is an
1085error to pass those in.
1070 1086
1071=back 1087=back
1072 1088
1073 1089
1074=head1 ENCODING/CODESET FLAG NOTES 1090=head1 ENCODING/CODESET FLAG NOTES
1101=item C<utf8> flag disabled 1117=item C<utf8> flag disabled
1102 1118
1103When C<utf8> is disabled (the default), then C<encode>/C<decode> generate 1119When C<utf8> is disabled (the default), then C<encode>/C<decode> generate
1104and expect Unicode strings, that is, characters with high ordinal Unicode 1120and expect Unicode strings, that is, characters with high ordinal Unicode
1105values (> 255) will be encoded as such characters, and likewise such 1121values (> 255) will be encoded as such characters, and likewise such
1106characters are decoded as-is, no canges to them will be done, except 1122characters are decoded as-is, no changes to them will be done, except
1107"(re-)interpreting" them as Unicode codepoints or Unicode characters, 1123"(re-)interpreting" them as Unicode codepoints or Unicode characters,
1108respectively (to Perl, these are the same thing in strings unless you do 1124respectively (to Perl, these are the same thing in strings unless you do
1109funny/weird/dumb stuff). 1125funny/weird/dumb stuff).
1110 1126
1111This is useful when you want to do the encoding yourself (e.g. when you 1127This is useful when you want to do the encoding yourself (e.g. when you
1167proper subset of most 8-bit and multibyte encodings in use in the world. 1183proper subset of most 8-bit and multibyte encodings in use in the world.
1168 1184
1169=back 1185=back
1170 1186
1171 1187
1188=head2 JSON and ECMAscript
1189
1190JSON syntax is based on how literals are represented in javascript (the
1191not-standardised predecessor of ECMAscript) which is presumably why it is
1192called "JavaScript Object Notation".
1193
1194However, JSON is not a subset (and also not a superset of course) of
1195ECMAscript (the standard) or javascript (whatever browsers actually
1196implement).
1197
1198If you want to use javascript's C<eval> function to "parse" JSON, you
1199might run into parse errors for valid JSON texts, or the resulting data
1200structure might not be queryable:
1201
1202One of the problems is that U+2028 and U+2029 are valid characters inside
1203JSON strings, but are not allowed in ECMAscript string literals, so the
1204following Perl fragment will not output something that can be guaranteed
1205to be parsable by javascript's C<eval>:
1206
1207 use JSON::XS;
1208
1209 print encode_json [chr 0x2028];
1210
1211The right fix for this is to use a proper JSON parser in your javascript
1212programs, and not rely on C<eval> (see for example Douglas Crockford's
1213F<json2.js> parser).
1214
1215If this is not an option, you can, as a stop-gap measure, simply encode to
1216ASCII-only JSON:
1217
1218 use JSON::XS;
1219
1220 print JSON::XS->new->ascii->encode ([chr 0x2028]);
1221
1222Note that this will enlarge the resulting JSON text quite a bit if you
1223have many non-ASCII characters. You might be tempted to run some regexes
1224to only escape U+2028 and U+2029, e.g.:
1225
1226 # DO NOT USE THIS!
1227 my $json = JSON::XS->new->utf8->encode ([chr 0x2028]);
1228 $json =~ s/\xe2\x80\xa8/\\u2028/g; # escape U+2028
1229 $json =~ s/\xe2\x80\xa9/\\u2029/g; # escape U+2029
1230 print $json;
1231
1232Note that I<this is a bad idea>: the above only works for U+2028 and
1233U+2029 and thus only for fully ECMAscript-compliant parsers. Many existing
1234javascript implementations, however, have issues with other characters as
1235well - using C<eval> naively simply I<will> cause problems.
1236
1237Another problem is that some javascript implementations reserve
1238some property names for their own purposes (which probably makes
1239them non-ECMAscript-compliant). For example, Iceweasel reserves the
1240C<__proto__> property name for its own purposes.
1241
1242If that is a problem, you could parse try to filter the resulting JSON
1243output for these property strings, e.g.:
1244
1245 $json =~ s/"__proto__"\s*:/"__proto__renamed":/g;
1246
1247This works because C<__proto__> is not valid outside of strings, so every
1248occurrence of C<"__proto__"\s*:> must be a string used as property name.
1249
1250If you know of other incompatibilities, please let me know.
1251
1252
1172=head2 JSON and YAML 1253=head2 JSON and YAML
1173 1254
1174You often hear that JSON is a subset of YAML. This is, however, a mass 1255You often hear that JSON is a subset of YAML. This is, however, a mass
1175hysteria(*) and very far from the truth (as of the time of this writing), 1256hysteria(*) and very far from the truth (as of the time of this writing),
1176so let me state it clearly: I<in general, there is no way to configure 1257so let me state it clearly: I<in general, there is no way to configure
1184 my $yaml = $to_yaml->encode ($ref) . "\n"; 1265 my $yaml = $to_yaml->encode ($ref) . "\n";
1185 1266
1186This will I<usually> generate JSON texts that also parse as valid 1267This will I<usually> generate JSON texts that also parse as valid
1187YAML. Please note that YAML has hardcoded limits on (simple) object key 1268YAML. Please note that YAML has hardcoded limits on (simple) object key
1188lengths that JSON doesn't have and also has different and incompatible 1269lengths that JSON doesn't have and also has different and incompatible
1189unicode handling, so you should make sure that your hash keys are 1270unicode character escape syntax, so you should make sure that your hash
1190noticeably shorter than the 1024 "stream characters" YAML allows and that 1271keys are noticeably shorter than the 1024 "stream characters" YAML allows
1191you do not have characters with codepoint values outside the Unicode BMP 1272and that you do not have characters with codepoint values outside the
1192(basic multilingual page). YAML also does not allow C<\/> sequences in 1273Unicode BMP (basic multilingual page). YAML also does not allow C<\/>
1193strings (which JSON::XS does not I<currently> generate, but other JSON 1274sequences in strings (which JSON::XS does not I<currently> generate, but
1194generators might). 1275other JSON generators might).
1195 1276
1196There might be other incompatibilities that I am not aware of (or the YAML 1277There might be other incompatibilities that I am not aware of (or the YAML
1197specification has been changed yet again - it does so quite often). In 1278specification has been changed yet again - it does so quite often). In
1198general you should not try to generate YAML with a JSON generator or vice 1279general you should not try to generate YAML with a JSON generator or vice
1199versa, or try to parse JSON with a YAML parser or vice versa: chances are 1280versa, or try to parse JSON with a YAML parser or vice versa: chances are
1218that difficult or long) and finally make YAML compatible to it, and 1299that difficult or long) and finally make YAML compatible to it, and
1219educating users about the changes, instead of spreading lies about the 1300educating users about the changes, instead of spreading lies about the
1220real compatibility for many I<years> and trying to silence people who 1301real compatibility for many I<years> and trying to silence people who
1221point out that it isn't true. 1302point out that it isn't true.
1222 1303
1304Addendum/2009: the YAML 1.2 spec is still incompatible with JSON, even
1305though the incompatibilities have been documented (and are known to Brian)
1306for many years and the spec makes explicit claims that YAML is a superset
1307of JSON. It would be so easy to fix, but apparently, bullying people and
1308corrupting userdata is so much easier.
1309
1223=back 1310=back
1224 1311
1225 1312
1226=head2 SPEED 1313=head2 SPEED
1227 1314
1234a very short single-line JSON string (also available at 1321a very short single-line JSON string (also available at
1235L<http://dist.schmorp.de/misc/json/short.json>). 1322L<http://dist.schmorp.de/misc/json/short.json>).
1236 1323
1237 {"method": "handleMessage", "params": ["user1", 1324 {"method": "handleMessage", "params": ["user1",
1238 "we were just talking"], "id": null, "array":[1,11,234,-5,1e5,1e7, 1325 "we were just talking"], "id": null, "array":[1,11,234,-5,1e5,1e7,
1239 true, false]} 1326 1, 0]}
1240 1327
1241It shows the number of encodes/decodes per second (JSON::XS uses 1328It shows the number of encodes/decodes per second (JSON::XS uses
1242the functional interface, while JSON::XS/2 uses the OO interface 1329the functional interface, while JSON::XS/2 uses the OO interface
1243with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables 1330with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables
1244shrink). Higher is better: 1331shrink. JSON::DWIW/DS uses the deserialise function, while JSON::DWIW::FJ
1332uses the from_json method). Higher is better:
1245 1333
1246 module | encode | decode | 1334 module | encode | decode |
1247 -----------|------------|------------| 1335 --------------|------------|------------|
1248 JSON 1.x | 4990.842 | 4088.813 | 1336 JSON::DWIW/DS | 86302.551 | 102300.098 |
1249 JSON::DWIW | 51653.990 | 71575.154 | 1337 JSON::DWIW/FJ | 86302.551 | 75983.768 |
1250 JSON::PC | 65948.176 | 74631.744 | 1338 JSON::PP | 15827.562 | 6638.658 |
1251 JSON::PP | 8931.652 | 3817.168 | 1339 JSON::Syck | 63358.066 | 47662.545 |
1252 JSON::Syck | 24877.248 | 27776.848 | 1340 JSON::XS | 511500.488 | 511500.488 |
1253 JSON::XS | 388361.481 | 227951.304 | 1341 JSON::XS/2 | 291271.111 | 388361.481 |
1254 JSON::XS/2 | 227951.304 | 218453.333 | 1342 JSON::XS/3 | 361577.931 | 361577.931 |
1255 JSON::XS/3 | 338250.323 | 218453.333 | 1343 Storable | 66788.280 | 265462.278 |
1256 Storable | 16500.016 | 135300.129 |
1257 -----------+------------+------------+ 1344 --------------+------------+------------+
1258 1345
1259That is, JSON::XS is about five times faster than JSON::DWIW on encoding, 1346That is, JSON::XS is almost six times faster than JSON::DWIW on encoding,
1260about three times faster on decoding, and over forty times faster 1347about five times faster on decoding, and over thirty to seventy times
1261than JSON, even with pretty-printing and key sorting. It also compares 1348faster than JSON's pure perl implementation. It also compares favourably
1262favourably to Storable for small amounts of data. 1349to Storable for small amounts of data.
1263 1350
1264Using a longer test string (roughly 18KB, generated from Yahoo! Locals 1351Using a longer test string (roughly 18KB, generated from Yahoo! Locals
1265search API (L<http://dist.schmorp.de/misc/json/long.json>). 1352search API (L<http://dist.schmorp.de/misc/json/long.json>).
1266 1353
1267 module | encode | decode | 1354 module | encode | decode |
1268 -----------|------------|------------| 1355 --------------|------------|------------|
1269 JSON 1.x | 55.260 | 34.971 | 1356 JSON::DWIW/DS | 1647.927 | 2673.916 |
1270 JSON::DWIW | 825.228 | 1082.513 | 1357 JSON::DWIW/FJ | 1630.249 | 2596.128 |
1271 JSON::PC | 3571.444 | 2394.829 |
1272 JSON::PP | 210.987 | 32.574 | 1358 JSON::PP | 400.640 | 62.311 |
1273 JSON::Syck | 552.551 | 787.544 | 1359 JSON::Syck | 1481.040 | 1524.869 |
1274 JSON::XS | 5780.463 | 4854.519 | 1360 JSON::XS | 20661.596 | 9541.183 |
1275 JSON::XS/2 | 3869.998 | 4798.975 | 1361 JSON::XS/2 | 10683.403 | 9416.938 |
1276 JSON::XS/3 | 5862.880 | 4798.975 | 1362 JSON::XS/3 | 20661.596 | 9400.054 |
1277 Storable | 4445.002 | 5235.027 | 1363 Storable | 19765.806 | 10000.725 |
1278 -----------+------------+------------+ 1364 --------------+------------+------------+
1279 1365
1280Again, JSON::XS leads by far (except for Storable which non-surprisingly 1366Again, JSON::XS leads by far (except for Storable which non-surprisingly
1281decodes faster). 1367decodes a bit faster).
1282 1368
1283On large strings containing lots of high Unicode characters, some modules 1369On large strings containing lots of high Unicode characters, some modules
1284(such as JSON::PC) seem to decode faster than JSON::XS, but the result 1370(such as JSON::PC) seem to decode faster than JSON::XS, but the result
1285will be broken due to missing (or wrong) Unicode handling. Others refuse 1371will be broken due to missing (or wrong) Unicode handling. Others refuse
1286to decode or encode properly, so it was impossible to prepare a fair 1372to decode or encode properly, so it was impossible to prepare a fair
1322information you might want to make sure that exceptions thrown by JSON::XS 1408information you might want to make sure that exceptions thrown by JSON::XS
1323will not end up in front of untrusted eyes. 1409will not end up in front of untrusted eyes.
1324 1410
1325If you are using JSON::XS to return packets to consumption 1411If you are using JSON::XS to return packets to consumption
1326by JavaScript scripts in a browser you should have a look at 1412by JavaScript scripts in a browser you should have a look at
1327L<http://jpsykes.com/47/practical-csrf-and-json-security> to see whether 1413L<http://blog.archive.jpsykes.com/47/practical-csrf-and-json-security/> to
1328you are vulnerable to some common attack vectors (which really are browser 1414see whether you are vulnerable to some common attack vectors (which really
1329design bugs, but it is still you who will have to deal with it, as major 1415are browser design bugs, but it is still you who will have to deal with
1330browser developers care only for features, not about getting security 1416it, as major browser developers care only for features, not about getting
1331right). 1417security right).
1332 1418
1333 1419
1334=head1 THREADS 1420=head1 THREADS
1335 1421
1336This module is I<not> guaranteed to be thread safe and there are no 1422This module is I<not> guaranteed to be thread safe and there are no
1337plans to change this until Perl gets thread support (as opposed to the 1423plans to change this until Perl gets thread support (as opposed to the
1338horribly slow so-called "threads" which are simply slow and bloated 1424horribly slow so-called "threads" which are simply slow and bloated
1339process simulations - use fork, it's I<much> faster, cheaper, better). 1425process simulations - use fork, it's I<much> faster, cheaper, better).
1340 1426
1341(It might actually work, but you have been warned). 1427(It might actually work, but you have been warned).
1428
1429
1430=head1 THE PERILS OF SETLOCALE
1431
1432Sometimes people avoid the Perl locale support and directly call the
1433system's setlocale function with C<LC_ALL>.
1434
1435This breaks both perl and modules such as JSON::XS, as stringification of
1436numbers no longer works correctly (e.g. C<$x = 0.1; print "$x"+1> might
1437print C<1>, and JSON::XS might output illegal JSON as JSON::XS relies on
1438perl to stringify numbers).
1439
1440The solution is simple: don't call C<setlocale>, or use it for only those
1441categories you need, such as C<LC_MESSAGES> or C<LC_CTYPE>.
1442
1443If you need C<LC_NUMERIC>, you should enable it only around the code that
1444actually needs it (avoiding stringification of numbers), and restore it
1445afterwards.
1342 1446
1343 1447
1344=head1 BUGS 1448=head1 BUGS
1345 1449
1346While the goal of this module is to be correct, that unfortunately does 1450While the goal of this module is to be correct, that unfortunately does

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines