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.98 by root, Wed Mar 26 02:36:18 2008 UTC vs.
Revision 1.140 by root, Thu Jun 27 11:45:17 2013 UTC

1=head1 NAME 1=head1 NAME
2 2
3JSON::XS - JSON serialising/deserialising, done correctly and fast
4
3=encoding utf-8 5=encoding utf-8
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.1'; 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 to_json from_json);
112 110
113sub to_json($) { 111sub to_json($) {
137 135
138This function call is functionally identical to: 136This function call is functionally identical to:
139 137
140 $json_text = JSON::XS->new->utf8->encode ($perl_scalar) 138 $json_text = JSON::XS->new->utf8->encode ($perl_scalar)
141 139
142except being faster. 140Except being faster.
143 141
144=item $perl_scalar = decode_json $json_text 142=item $perl_scalar = decode_json $json_text
145 143
146The opposite of C<encode_json>: expects an UTF-8 (binary) string and tries 144The 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 145to parse that as an UTF-8 encoded JSON text, returning the resulting
149 147
150This function call is functionally identical to: 148This function call is functionally identical to:
151 149
152 $perl_scalar = JSON::XS->new->utf8->decode ($json_text) 150 $perl_scalar = JSON::XS->new->utf8->decode ($json_text)
153 151
154except being faster. 152Except being faster.
155 153
156=item $is_boolean = JSON::XS::is_bool $scalar 154=item $is_boolean = JSON::XS::is_bool $scalar
157 155
158Returns true if the passed scalar represents either JSON::XS::true or 156Returns 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 157JSON::XS::false, two constants that act like C<1> and C<0>, respectively
197 195
198If you didn't know about that flag, just the better, pretend it doesn't 196If you didn't know about that flag, just the better, pretend it doesn't
199exist. 197exist.
200 198
201=item 4. A "Unicode String" is simply a string where each character can be 199=item 4. A "Unicode String" is simply a string where each character can be
202validly interpreted as a Unicode codepoint. 200validly interpreted as a Unicode code point.
203 201
204If you have UTF-8 encoded data, it is no longer a Unicode string, but a 202If 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. 203Unicode string encoded in UTF-8, giving you a binary string.
206 204
207=item 5. A string containing "high" (> 255) character values is I<not> a UTF-8 string. 205=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 432If 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. 433by sorting their keys. This is adding a comparatively high overhead.
436 434
437If C<$enable> is false, then the C<encode> method will output key-value 435If 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 436pairs in the order Perl stores them (which will likely change between runs
439of the same script). 437of the same script, and can change even within the same run from 5.18
438onwards).
440 439
441This option is useful if you want the same data structure to be encoded as 440This 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, 441the 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, 442the same hash might be encoded differently even if contains the same data,
444as key-value pairs have no inherent ordering in Perl. 443as key-value pairs have no inherent ordering in Perl.
445 444
446This setting has no effect when decoding JSON texts. 445This setting has no effect when decoding JSON texts.
447 446
447This setting has currently no effect on tied hashes.
448
448=item $json = $json->allow_nonref ([$enable]) 449=item $json = $json->allow_nonref ([$enable])
449 450
450=item $enabled = $json->get_allow_nonref 451=item $enabled = $json->get_allow_nonref
451 452
452If C<$enable> is true (or missing), then the C<encode> method can convert a 453If C<$enable> is true (or missing), then the C<encode> method can convert a
462Example, encode a Perl scalar as JSON value with enabled C<allow_nonref>, 463Example, encode a Perl scalar as JSON value with enabled C<allow_nonref>,
463resulting in an invalid JSON text: 464resulting in an invalid JSON text:
464 465
465 JSON::XS->new->allow_nonref->encode ("Hello, World!") 466 JSON::XS->new->allow_nonref->encode ("Hello, World!")
466 => "Hello, World!" 467 => "Hello, World!"
468
469=item $json = $json->allow_unknown ([$enable])
470
471=item $enabled = $json->get_allow_unknown
472
473If C<$enable> is true (or missing), then C<encode> will I<not> throw an
474exception when it encounters values it cannot represent in JSON (for
475example, filehandles) but instead will encode a JSON C<null> value. Note
476that blessed objects are not included here and are handled separately by
477c<allow_nonref>.
478
479If C<$enable> is false (the default), then C<encode> will throw an
480exception when it encounters anything it cannot encode as JSON.
481
482This option does not affect C<decode> in any way, and it is recommended to
483leave it off unless you know your communications partner.
467 484
468=item $json = $json->allow_blessed ([$enable]) 485=item $json = $json->allow_blessed ([$enable])
469 486
470=item $enabled = $json->get_allow_blessed 487=item $enabled = $json->get_allow_blessed
471 488
612=item $json = $json->max_depth ([$maximum_nesting_depth]) 629=item $json = $json->max_depth ([$maximum_nesting_depth])
613 630
614=item $max_depth = $json->get_max_depth 631=item $max_depth = $json->get_max_depth
615 632
616Sets the maximum nesting level (default C<512>) accepted while encoding 633Sets the maximum nesting level (default C<512>) accepted while encoding
617or decoding. If the JSON text or Perl data structure has an equal or 634or decoding. If a higher nesting level is detected in JSON text or a Perl
618higher nesting level then this limit, then the encoder and decoder will 635data structure, then the encoder and decoder will stop and croak at that
619stop and croak at that point. 636point.
620 637
621Nesting level is defined by number of hash- or arrayrefs that the encoder 638Nesting level is defined by number of hash- or arrayrefs that the encoder
622needs to traverse to reach a given point or the number of C<{> or C<[> 639needs to traverse to reach a given point or the number of C<{> or C<[>
623characters without their matching closing parenthesis crossed to reach a 640characters without their matching closing parenthesis crossed to reach a
624given character in a string. 641given character in a string.
625 642
626Setting the maximum depth to one disallows any nesting, so that ensures 643Setting the maximum depth to one disallows any nesting, so that ensures
627that the object is only a single hash/object or array. 644that the object is only a single hash/object or array.
628 645
629The argument to C<max_depth> will be rounded up to the next highest power
630of two. If no argument is given, the highest possible setting will be 646If no argument is given, the highest possible setting will be used, which
631used, which is rarely useful. 647is rarely useful.
648
649Note that nesting is implemented by recursion in C. The default value has
650been chosen to be as large as typical operating systems allow without
651crashing.
632 652
633See SECURITY CONSIDERATIONS, below, for more info on why this is useful. 653See SECURITY CONSIDERATIONS, below, for more info on why this is useful.
634 654
635=item $json = $json->max_size ([$maximum_string_size]) 655=item $json = $json->max_size ([$maximum_string_size])
636 656
637=item $max_size = $json->get_max_size 657=item $max_size = $json->get_max_size
638 658
639Set the maximum length a JSON text may have (in bytes) where decoding is 659Set the maximum length a JSON text may have (in bytes) where decoding is
640being attempted. The default is C<0>, meaning no limit. When C<decode> 660being attempted. The default is C<0>, meaning no limit. When C<decode>
641is called on a string longer then this number of characters it will not 661is called on a string that is longer then this many bytes, it will not
642attempt to decode the string but throw an exception. This setting has no 662attempt to decode the string but throw an exception. This setting has no
643effect on C<encode> (yet). 663effect on C<encode> (yet).
644 664
645The argument to C<max_size> will be rounded up to the next B<highest> 665If no argument is given, the limit check will be deactivated (same as when
646power of two (so may be more than requested). If no argument is given, the 666C<0> is specified).
647limit check will be deactivated (same as when C<0> is specified).
648 667
649See SECURITY CONSIDERATIONS, below, for more info on why this is useful. 668See SECURITY CONSIDERATIONS, below, for more info on why this is useful.
650 669
651=item $json_text = $json->encode ($perl_scalar) 670=item $json_text = $json->encode ($perl_scalar)
652 671
683=back 702=back
684 703
685 704
686=head1 INCREMENTAL PARSING 705=head1 INCREMENTAL PARSING
687 706
688[This section and the API it details is still EXPERIMENTAL]
689
690In some cases, there is the need for incremental parsing of JSON 707In some cases, there is the need for incremental parsing of JSON
691texts. While this module always has to keep both JSON text and resulting 708texts. While this module always has to keep both JSON text and resulting
692Perl data structure in memory at one time, it does allow you to parse a 709Perl data structure in memory at one time, it does allow you to parse a
693JSON stream incrementally. It does so by accumulating text until it has 710JSON stream incrementally. It does so by accumulating text until it has
694a full JSON object, which it then can decode. This process is similar to 711a full JSON object, which it then can decode. This process is similar to
695using C<decode_prefix> to see if a full JSON object is available, but is 712using C<decode_prefix> to see if a full JSON object is available, but
696much more efficient (JSON::XS will only attempt to parse the JSON text 713is much more efficient (and can be implemented with a minimum of method
714calls).
715
716JSON::XS will only attempt to parse the JSON text once it is sure it
697once it is sure it has enough text to get a decisive result, using a very 717has enough text to get a decisive result, using a very simple but
698simple but truly incremental parser). 718truly incremental parser. This means that it sometimes won't stop as
719early as the full parser, for example, it doesn't detect mismatched
720parentheses. The only thing it guarantees is that it starts decoding as
721soon as a syntactically valid JSON text has been seen. This means you need
722to set resource limits (e.g. C<max_size>) to ensure the parser will stop
723parsing in the presence if syntax errors.
699 724
700The following two methods deal with this. 725The following methods implement this incremental parser.
701 726
702=over 4 727=over 4
703 728
704=item [void, scalar or list context] = $json->incr_parse ([$string]) 729=item [void, scalar or list context] = $json->incr_parse ([$string])
705 730
716 741
717If the method is called in scalar context, then it will try to extract 742If the method is called in scalar context, then it will try to extract
718exactly I<one> JSON object. If that is successful, it will return this 743exactly I<one> JSON object. If that is successful, it will return this
719object, otherwise it will return C<undef>. If there is a parse error, 744object, otherwise it will return C<undef>. If there is a parse error,
720this method will croak just as C<decode> would do (one can then use 745this method will croak just as C<decode> would do (one can then use
721C<incr_skip> to skip the errornous part). This is the most common way of 746C<incr_skip> to skip the erroneous part). This is the most common way of
722using the method. 747using the method.
723 748
724And finally, in list context, it will try to extract as many objects 749And finally, in list context, it will try to extract as many objects
725from the stream as it can find and return them, or the empty list 750from the stream as it can find and return them, or the empty list
726otherwise. For this to work, there must be no separators between the JSON 751otherwise. For this to work, there must be no separators between the JSON
727objects or arrays, instead they must be concatenated back-to-back. If 752objects or arrays, instead they must be concatenated back-to-back. If
728an error occurs, an exception will be raised as in the scalar context 753an error occurs, an exception will be raised as in the scalar context
729case. Note that in this case, any previously-parsed JSON texts will be 754case. Note that in this case, any previously-parsed JSON texts will be
730lost. 755lost.
731 756
757Example: Parse some JSON arrays/objects in a given string and return
758them.
759
760 my @objs = JSON::XS->new->incr_parse ("[5][7][1,2]");
761
732=item $lvalue_string = $json->incr_text 762=item $lvalue_string = $json->incr_text
733 763
734This method returns the currently stored JSON fragment as an lvalue, that 764This method returns the currently stored JSON fragment as an lvalue, that
735is, you can manipulate it. This I<only> works when a preceding call to 765is, you can manipulate it. This I<only> works when a preceding call to
736C<incr_parse> in I<scalar context> successfully returned an object. Under 766C<incr_parse> in I<scalar context> successfully returned an object. Under
743JSON object or b) parsing multiple JSON objects separated by non-JSON text 773JSON object or b) parsing multiple JSON objects separated by non-JSON text
744(such as commas). 774(such as commas).
745 775
746=item $json->incr_skip 776=item $json->incr_skip
747 777
748This will reset the state of the incremental parser and will remove the 778This will reset the state of the incremental parser and will remove
749parsed text from the input buffer. This is useful after C<incr_parse> 779the parsed text from the input buffer so far. This is useful after
750died, in which case the input buffer and incremental parser state is left 780C<incr_parse> died, in which case the input buffer and incremental parser
751unchanged, to skip the text parsed so far and to reset the parse state. 781state is left unchanged, to skip the text parsed so far and to reset the
782parse state.
783
784The difference to C<incr_reset> is that only text until the parse error
785occurred is removed.
786
787=item $json->incr_reset
788
789This completely resets the incremental parser, that is, after this call,
790it will be as if the parser had never parsed anything.
791
792This is useful if you want to repeatedly parse JSON objects and want to
793ignore any trailing data, which means you have to reset the parser after
794each successful decode.
752 795
753=back 796=back
754 797
755=head2 LIMITATIONS 798=head2 LIMITATIONS
756 799
945If the number consists of digits only, JSON::XS will try to represent 988If the number consists of digits only, JSON::XS will try to represent
946it as an integer value. If that fails, it will try to represent it as 989it as an integer value. If that fails, it will try to represent it as
947a numeric (floating point) value if that is possible without loss of 990a numeric (floating point) value if that is possible without loss of
948precision. Otherwise it will preserve the number as a string value (in 991precision. Otherwise it will preserve the number as a string value (in
949which case you lose roundtripping ability, as the JSON number will be 992which case you lose roundtripping ability, as the JSON number will be
950re-encoded toa JSON string). 993re-encoded to a JSON string).
951 994
952Numbers containing a fractional or exponential part will always be 995Numbers containing a fractional or exponential part will always be
953represented as numeric (floating point) values, possibly at a loss of 996represented as numeric (floating point) values, possibly at a loss of
954precision (in which case you might lose perfect roundtripping ability, but 997precision (in which case you might lose perfect roundtripping ability, but
955the JSON number will still be re-encoded as a JSON number). 998the JSON number will still be re-encoded as a JSON number).
999
1000Note that precision is not accuracy - binary floating point values cannot
1001represent most decimal fractions exactly, and when converting from and to
1002floating point, JSON::XS only guarantees precision up to but not including
1003the least significant bit.
956 1004
957=item true, false 1005=item true, false
958 1006
959These JSON atoms become C<JSON::XS::true> and C<JSON::XS::false>, 1007These JSON atoms become C<JSON::XS::true> and C<JSON::XS::false>,
960respectively. They are overloaded to act almost exactly like the numbers 1008respectively. They are overloaded to act almost exactly like the numbers
997Other unblessed references are generally not allowed and will cause an 1045Other unblessed references are generally not allowed and will cause an
998exception to be thrown, except for references to the integers C<0> and 1046exception to be thrown, except for references to the integers C<0> and
999C<1>, which get turned into C<false> and C<true> atoms in JSON. You can 1047C<1>, which get turned into C<false> and C<true> atoms in JSON. You can
1000also use C<JSON::XS::false> and C<JSON::XS::true> to improve readability. 1048also use C<JSON::XS::false> and C<JSON::XS::true> to improve readability.
1001 1049
1002 encode_json [\0,JSON::XS::true] # yields [false,true] 1050 encode_json [\0, JSON::XS::true] # yields [false,true]
1003 1051
1004=item JSON::XS::true, JSON::XS::false 1052=item JSON::XS::true, JSON::XS::false
1005 1053
1006These special values become JSON true and JSON false values, 1054These special values become JSON true and JSON false values,
1007respectively. You can also use C<\1> and C<\0> directly if you want. 1055respectively. You can also use C<\1> and C<\0> directly if you want.
1047 $x *= 1; # same thing, the choice is yours. 1095 $x *= 1; # same thing, the choice is yours.
1048 1096
1049You can not currently force the type in other, less obscure, ways. Tell me 1097You can not currently force the type in other, less obscure, ways. Tell me
1050if you need this capability (but don't forget to explain why it's needed 1098if you need this capability (but don't forget to explain why it's needed
1051:). 1099:).
1100
1101Note that numerical precision has the same meaning as under Perl (so
1102binary to decimal conversion follows the same rules as in Perl, which
1103can differ to other languages). Also, your perl interpreter might expose
1104extensions to the floating point numbers of your platform, such as
1105infinities or NaN's - these cannot be represented in JSON, and it is an
1106error to pass those in.
1052 1107
1053=back 1108=back
1054 1109
1055 1110
1056=head1 ENCODING/CODESET FLAG NOTES 1111=head1 ENCODING/CODESET FLAG NOTES
1083=item C<utf8> flag disabled 1138=item C<utf8> flag disabled
1084 1139
1085When C<utf8> is disabled (the default), then C<encode>/C<decode> generate 1140When C<utf8> is disabled (the default), then C<encode>/C<decode> generate
1086and expect Unicode strings, that is, characters with high ordinal Unicode 1141and expect Unicode strings, that is, characters with high ordinal Unicode
1087values (> 255) will be encoded as such characters, and likewise such 1142values (> 255) will be encoded as such characters, and likewise such
1088characters are decoded as-is, no canges to them will be done, except 1143characters are decoded as-is, no changes to them will be done, except
1089"(re-)interpreting" them as Unicode codepoints or Unicode characters, 1144"(re-)interpreting" them as Unicode codepoints or Unicode characters,
1090respectively (to Perl, these are the same thing in strings unless you do 1145respectively (to Perl, these are the same thing in strings unless you do
1091funny/weird/dumb stuff). 1146funny/weird/dumb stuff).
1092 1147
1093This is useful when you want to do the encoding yourself (e.g. when you 1148This is useful when you want to do the encoding yourself (e.g. when you
1149proper subset of most 8-bit and multibyte encodings in use in the world. 1204proper subset of most 8-bit and multibyte encodings in use in the world.
1150 1205
1151=back 1206=back
1152 1207
1153 1208
1209=head2 JSON and ECMAscript
1210
1211JSON syntax is based on how literals are represented in javascript (the
1212not-standardised predecessor of ECMAscript) which is presumably why it is
1213called "JavaScript Object Notation".
1214
1215However, JSON is not a subset (and also not a superset of course) of
1216ECMAscript (the standard) or javascript (whatever browsers actually
1217implement).
1218
1219If you want to use javascript's C<eval> function to "parse" JSON, you
1220might run into parse errors for valid JSON texts, or the resulting data
1221structure might not be queryable:
1222
1223One of the problems is that U+2028 and U+2029 are valid characters inside
1224JSON strings, but are not allowed in ECMAscript string literals, so the
1225following Perl fragment will not output something that can be guaranteed
1226to be parsable by javascript's C<eval>:
1227
1228 use JSON::XS;
1229
1230 print encode_json [chr 0x2028];
1231
1232The right fix for this is to use a proper JSON parser in your javascript
1233programs, and not rely on C<eval> (see for example Douglas Crockford's
1234F<json2.js> parser).
1235
1236If this is not an option, you can, as a stop-gap measure, simply encode to
1237ASCII-only JSON:
1238
1239 use JSON::XS;
1240
1241 print JSON::XS->new->ascii->encode ([chr 0x2028]);
1242
1243Note that this will enlarge the resulting JSON text quite a bit if you
1244have many non-ASCII characters. You might be tempted to run some regexes
1245to only escape U+2028 and U+2029, e.g.:
1246
1247 # DO NOT USE THIS!
1248 my $json = JSON::XS->new->utf8->encode ([chr 0x2028]);
1249 $json =~ s/\xe2\x80\xa8/\\u2028/g; # escape U+2028
1250 $json =~ s/\xe2\x80\xa9/\\u2029/g; # escape U+2029
1251 print $json;
1252
1253Note that I<this is a bad idea>: the above only works for U+2028 and
1254U+2029 and thus only for fully ECMAscript-compliant parsers. Many existing
1255javascript implementations, however, have issues with other characters as
1256well - using C<eval> naively simply I<will> cause problems.
1257
1258Another problem is that some javascript implementations reserve
1259some property names for their own purposes (which probably makes
1260them non-ECMAscript-compliant). For example, Iceweasel reserves the
1261C<__proto__> property name for its own purposes.
1262
1263If that is a problem, you could parse try to filter the resulting JSON
1264output for these property strings, e.g.:
1265
1266 $json =~ s/"__proto__"\s*:/"__proto__renamed":/g;
1267
1268This works because C<__proto__> is not valid outside of strings, so every
1269occurrence of C<"__proto__"\s*:> must be a string used as property name.
1270
1271If you know of other incompatibilities, please let me know.
1272
1273
1154=head2 JSON and YAML 1274=head2 JSON and YAML
1155 1275
1156You often hear that JSON is a subset of YAML. This is, however, a mass 1276You often hear that JSON is a subset of YAML. This is, however, a mass
1157hysteria(*) and very far from the truth (as of the time of this writing), 1277hysteria(*) and very far from the truth (as of the time of this writing),
1158so let me state it clearly: I<in general, there is no way to configure 1278so let me state it clearly: I<in general, there is no way to configure
1166 my $yaml = $to_yaml->encode ($ref) . "\n"; 1286 my $yaml = $to_yaml->encode ($ref) . "\n";
1167 1287
1168This will I<usually> generate JSON texts that also parse as valid 1288This will I<usually> generate JSON texts that also parse as valid
1169YAML. Please note that YAML has hardcoded limits on (simple) object key 1289YAML. Please note that YAML has hardcoded limits on (simple) object key
1170lengths that JSON doesn't have and also has different and incompatible 1290lengths that JSON doesn't have and also has different and incompatible
1171unicode handling, so you should make sure that your hash keys are 1291unicode character escape syntax, so you should make sure that your hash
1172noticeably shorter than the 1024 "stream characters" YAML allows and that 1292keys are noticeably shorter than the 1024 "stream characters" YAML allows
1173you do not have characters with codepoint values outside the Unicode BMP 1293and that you do not have characters with codepoint values outside the
1174(basic multilingual page). YAML also does not allow C<\/> sequences in 1294Unicode BMP (basic multilingual page). YAML also does not allow C<\/>
1175strings (which JSON::XS does not I<currently> generate, but other JSON 1295sequences in strings (which JSON::XS does not I<currently> generate, but
1176generators might). 1296other JSON generators might).
1177 1297
1178There might be other incompatibilities that I am not aware of (or the YAML 1298There might be other incompatibilities that I am not aware of (or the YAML
1179specification has been changed yet again - it does so quite often). In 1299specification has been changed yet again - it does so quite often). In
1180general you should not try to generate YAML with a JSON generator or vice 1300general you should not try to generate YAML with a JSON generator or vice
1181versa, or try to parse JSON with a YAML parser or vice versa: chances are 1301versa, or try to parse JSON with a YAML parser or vice versa: chances are
1200that difficult or long) and finally make YAML compatible to it, and 1320that difficult or long) and finally make YAML compatible to it, and
1201educating users about the changes, instead of spreading lies about the 1321educating users about the changes, instead of spreading lies about the
1202real compatibility for many I<years> and trying to silence people who 1322real compatibility for many I<years> and trying to silence people who
1203point out that it isn't true. 1323point out that it isn't true.
1204 1324
1325Addendum/2009: the YAML 1.2 spec is still incompatible with JSON, even
1326though the incompatibilities have been documented (and are known to Brian)
1327for many years and the spec makes explicit claims that YAML is a superset
1328of JSON. It would be so easy to fix, but apparently, bullying people and
1329corrupting userdata is so much easier.
1330
1205=back 1331=back
1206 1332
1207 1333
1208=head2 SPEED 1334=head2 SPEED
1209 1335
1214 1340
1215First comes a comparison between various modules using 1341First comes a comparison between various modules using
1216a very short single-line JSON string (also available at 1342a very short single-line JSON string (also available at
1217L<http://dist.schmorp.de/misc/json/short.json>). 1343L<http://dist.schmorp.de/misc/json/short.json>).
1218 1344
1219 {"method": "handleMessage", "params": ["user1", "we were just talking"], \ 1345 {"method": "handleMessage", "params": ["user1",
1220 "id": null, "array":[1,11,234,-5,1e5,1e7, true, false]} 1346 "we were just talking"], "id": null, "array":[1,11,234,-5,1e5,1e7,
1347 1, 0]}
1221 1348
1222It shows the number of encodes/decodes per second (JSON::XS uses 1349It shows the number of encodes/decodes per second (JSON::XS uses
1223the functional interface, while JSON::XS/2 uses the OO interface 1350the functional interface, while JSON::XS/2 uses the OO interface
1224with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables 1351with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables
1225shrink). Higher is better: 1352shrink. JSON::DWIW/DS uses the deserialise function, while JSON::DWIW::FJ
1353uses the from_json method). Higher is better:
1226 1354
1227 module | encode | decode | 1355 module | encode | decode |
1228 -----------|------------|------------| 1356 --------------|------------|------------|
1229 JSON 1.x | 4990.842 | 4088.813 | 1357 JSON::DWIW/DS | 86302.551 | 102300.098 |
1230 JSON::DWIW | 51653.990 | 71575.154 | 1358 JSON::DWIW/FJ | 86302.551 | 75983.768 |
1231 JSON::PC | 65948.176 | 74631.744 | 1359 JSON::PP | 15827.562 | 6638.658 |
1232 JSON::PP | 8931.652 | 3817.168 | 1360 JSON::Syck | 63358.066 | 47662.545 |
1233 JSON::Syck | 24877.248 | 27776.848 | 1361 JSON::XS | 511500.488 | 511500.488 |
1234 JSON::XS | 388361.481 | 227951.304 | 1362 JSON::XS/2 | 291271.111 | 388361.481 |
1235 JSON::XS/2 | 227951.304 | 218453.333 | 1363 JSON::XS/3 | 361577.931 | 361577.931 |
1236 JSON::XS/3 | 338250.323 | 218453.333 | 1364 Storable | 66788.280 | 265462.278 |
1237 Storable | 16500.016 | 135300.129 |
1238 -----------+------------+------------+ 1365 --------------+------------+------------+
1239 1366
1240That is, JSON::XS is about five times faster than JSON::DWIW on encoding, 1367That is, JSON::XS is almost six times faster than JSON::DWIW on encoding,
1241about three times faster on decoding, and over forty times faster 1368about five times faster on decoding, and over thirty to seventy times
1242than JSON, even with pretty-printing and key sorting. It also compares 1369faster than JSON's pure perl implementation. It also compares favourably
1243favourably to Storable for small amounts of data. 1370to Storable for small amounts of data.
1244 1371
1245Using a longer test string (roughly 18KB, generated from Yahoo! Locals 1372Using a longer test string (roughly 18KB, generated from Yahoo! Locals
1246search API (L<http://dist.schmorp.de/misc/json/long.json>). 1373search API (L<http://dist.schmorp.de/misc/json/long.json>).
1247 1374
1248 module | encode | decode | 1375 module | encode | decode |
1249 -----------|------------|------------| 1376 --------------|------------|------------|
1250 JSON 1.x | 55.260 | 34.971 | 1377 JSON::DWIW/DS | 1647.927 | 2673.916 |
1251 JSON::DWIW | 825.228 | 1082.513 | 1378 JSON::DWIW/FJ | 1630.249 | 2596.128 |
1252 JSON::PC | 3571.444 | 2394.829 |
1253 JSON::PP | 210.987 | 32.574 | 1379 JSON::PP | 400.640 | 62.311 |
1254 JSON::Syck | 552.551 | 787.544 | 1380 JSON::Syck | 1481.040 | 1524.869 |
1255 JSON::XS | 5780.463 | 4854.519 | 1381 JSON::XS | 20661.596 | 9541.183 |
1256 JSON::XS/2 | 3869.998 | 4798.975 | 1382 JSON::XS/2 | 10683.403 | 9416.938 |
1257 JSON::XS/3 | 5862.880 | 4798.975 | 1383 JSON::XS/3 | 20661.596 | 9400.054 |
1258 Storable | 4445.002 | 5235.027 | 1384 Storable | 19765.806 | 10000.725 |
1259 -----------+------------+------------+ 1385 --------------+------------+------------+
1260 1386
1261Again, JSON::XS leads by far (except for Storable which non-surprisingly 1387Again, JSON::XS leads by far (except for Storable which non-surprisingly
1262decodes faster). 1388decodes a bit faster).
1263 1389
1264On large strings containing lots of high Unicode characters, some modules 1390On large strings containing lots of high Unicode characters, some modules
1265(such as JSON::PC) seem to decode faster than JSON::XS, but the result 1391(such as JSON::PC) seem to decode faster than JSON::XS, but the result
1266will be broken due to missing (or wrong) Unicode handling. Others refuse 1392will be broken due to missing (or wrong) Unicode handling. Others refuse
1267to decode or encode properly, so it was impossible to prepare a fair 1393to decode or encode properly, so it was impossible to prepare a fair
1303information you might want to make sure that exceptions thrown by JSON::XS 1429information you might want to make sure that exceptions thrown by JSON::XS
1304will not end up in front of untrusted eyes. 1430will not end up in front of untrusted eyes.
1305 1431
1306If you are using JSON::XS to return packets to consumption 1432If you are using JSON::XS to return packets to consumption
1307by JavaScript scripts in a browser you should have a look at 1433by JavaScript scripts in a browser you should have a look at
1308L<http://jpsykes.com/47/practical-csrf-and-json-security> to see whether 1434L<http://blog.archive.jpsykes.com/47/practical-csrf-and-json-security/> to
1309you are vulnerable to some common attack vectors (which really are browser 1435see whether you are vulnerable to some common attack vectors (which really
1310design bugs, but it is still you who will have to deal with it, as major 1436are browser design bugs, but it is still you who will have to deal with
1311browser developers care only for features, not about getting security 1437it, as major browser developers care only for features, not about getting
1312right). 1438security right).
1313 1439
1314 1440
1315=head1 THREADS 1441=head1 THREADS
1316 1442
1317This module is I<not> guaranteed to be thread safe and there are no 1443This module is I<not> guaranteed to be thread safe and there are no
1320process simulations - use fork, it's I<much> faster, cheaper, better). 1446process simulations - use fork, it's I<much> faster, cheaper, better).
1321 1447
1322(It might actually work, but you have been warned). 1448(It might actually work, but you have been warned).
1323 1449
1324 1450
1451=head1 THE PERILS OF SETLOCALE
1452
1453Sometimes people avoid the Perl locale support and directly call the
1454system's setlocale function with C<LC_ALL>.
1455
1456This breaks both perl and modules such as JSON::XS, as stringification of
1457numbers no longer works correctly (e.g. C<$x = 0.1; print "$x"+1> might
1458print C<1>, and JSON::XS might output illegal JSON as JSON::XS relies on
1459perl to stringify numbers).
1460
1461The solution is simple: don't call C<setlocale>, or use it for only those
1462categories you need, such as C<LC_MESSAGES> or C<LC_CTYPE>.
1463
1464If you need C<LC_NUMERIC>, you should enable it only around the code that
1465actually needs it (avoiding stringification of numbers), and restore it
1466afterwards.
1467
1468
1325=head1 BUGS 1469=head1 BUGS
1326 1470
1327While the goal of this module is to be correct, that unfortunately does 1471While the goal of this module is to be correct, that unfortunately does
1328not mean it's bug-free, only that I think its design is bug-free. It is 1472not mean it's bug-free, only that I think its design is bug-free. If you
1329still relatively early in its development. If you keep reporting bugs they 1473keep reporting bugs they will be fixed swiftly, though.
1330will be fixed swiftly, though.
1331 1474
1332Please refrain from using rt.cpan.org or any other bug reporting 1475Please refrain from using rt.cpan.org or any other bug reporting
1333service. I put the contact address into my modules for a reason. 1476service. I put the contact address into my modules for a reason.
1334 1477
1335=cut 1478=cut

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines