ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/JSON-XS/README
(Generate patch)

Comparing JSON-XS/README (file contents):
Revision 1.2 by root, Thu Mar 22 21:13:58 2007 UTC vs.
Revision 1.7 by root, Sun Mar 25 00:47:42 2007 UTC

1NAME 1NAME
2 JSON::XS - JSON serialising/deserialising, done correctly and fast 2 JSON::XS - JSON serialising/deserialising, done correctly and fast
3 3
4SYNOPSIS 4SYNOPSIS
5 use JSON::XS; 5 use JSON::XS;
6
7 # exported functions, croak on error
8
9 $utf8_encoded_json_text = to_json $perl_hash_or_arrayref;
10 $perl_hash_or_arrayref = from_json $utf8_encoded_json_text;
11
12 # oo-interface
13
14 $coder = JSON::XS->new->ascii->pretty->allow_nonref;
15 $pretty_printed_unencoded = $coder->encode ($perl_scalar);
16 $perl_scalar = $coder->decode ($unicode_json_text);
6 17
7DESCRIPTION 18DESCRIPTION
8 This module converts Perl data structures to JSON and vice versa. Its 19 This module converts Perl data structures to JSON and vice versa. Its
9 primary goal is to be *correct* and its secondary goal is to be *fast*. 20 primary goal is to be *correct* and its secondary goal is to be *fast*.
10 To reach the latter goal it was written in C. 21 To reach the latter goal it was written in C.
… …
15 cases their maintainers are unresponsive, gone missing, or not listening 26 cases their maintainers are unresponsive, gone missing, or not listening
16 to bug reports for other reasons. 27 to bug reports for other reasons.
17 28
18 See COMPARISON, below, for a comparison to some other JSON modules. 29 See COMPARISON, below, for a comparison to some other JSON modules.
19 30
31 See MAPPING, below, on how JSON::XS maps perl values to JSON values and
32 vice versa.
33
20 FEATURES 34 FEATURES
21 * correct handling of unicode issues 35 * correct handling of unicode issues
22 This module knows how to handle Unicode, and even documents how it 36 This module knows how to handle Unicode, and even documents how and
23 does so. 37 when it does so.
24 38
25 * round-trip integrity 39 * round-trip integrity
26 When you serialise a perl data structure using only datatypes 40 When you serialise a perl data structure using only datatypes
27 supported by JSON, the deserialised data structure is identical on 41 supported by JSON, the deserialised data structure is identical on
28 the Perl level. (e.g. the string "2.0" doesn't suddenly become "2"). 42 the Perl level. (e.g. the string "2.0" doesn't suddenly become "2").
29 43
30 * strict checking of JSON correctness 44 * strict checking of JSON correctness
31 There is no guessing, no generating of illegal JSON strings by 45 There is no guessing, no generating of illegal JSON texts by
32 default, and only JSON is accepted as input (the latter is a 46 default, and only JSON is accepted as input by default (the latter
33 security feature). 47 is a security feature).
34 48
35 * fast 49 * fast
36 compared to other JSON modules, this module compares favourably. 50 Compared to other JSON modules, this module compares favourably in
51 terms of speed, too.
37 52
38 * simple to use 53 * simple to use
39 This module has both a simple functional interface as well as an OO 54 This module has both a simple functional interface as well as an OO
40 interface. 55 interface.
41 56
42 * reasonably versatile output formats 57 * reasonably versatile output formats
43 You can choose between the most compact format possible, a 58 You can choose between the most compact guarenteed single-line
44 pure-ascii format, or a pretty-printed format. Or you can combine 59 format possible (nice for simple line-based protocols), a pure-ascii
60 format (for when your transport is not 8-bit clean), or a
61 pretty-printed format (for when you want to read that stuff). Or you
45 those features in whatever way you like. 62 can combine those features in whatever way you like.
46 63
47FUNCTIONAL INTERFACE 64FUNCTIONAL INTERFACE
48 The following convinience methods are provided by this module. They are 65 The following convinience methods are provided by this module. They are
49 exported by default: 66 exported by default:
50 67
51 $json_string = to_json $perl_scalar 68 $json_text = to_json $perl_scalar
52 Converts the given Perl data structure (a simple scalar or a 69 Converts the given Perl data structure (a simple scalar or a
53 reference to a hash or array) to a UTF-8 encoded, binary string 70 reference to a hash or array) to a UTF-8 encoded, binary string
54 (that is, the string contains octets only). Croaks on error. 71 (that is, the string contains octets only). Croaks on error.
55 72
56 This function call is functionally identical to "JSON::XS->new->utf8 73 This function call is functionally identical to:
57 (1)->encode ($perl_scalar)".
58 74
75 $json_text = JSON::XS->new->utf8->encode ($perl_scalar)
76
77 except being faster.
78
59 $perl_scalar = from_json $json_string 79 $perl_scalar = from_json $json_text
60 The opposite of "to_json": expects an UTF-8 (binary) string and 80 The opposite of "to_json": expects an UTF-8 (binary) string and
61 tries to parse that as an UTF-8 encoded JSON string, returning the 81 tries to parse that as an UTF-8 encoded JSON text, returning the
62 resulting simple scalar or reference. Croaks on error. 82 resulting simple scalar or reference. Croaks on error.
63 83
64 This function call is functionally identical to "JSON::XS->new->utf8 84 This function call is functionally identical to:
65 (1)->decode ($json_string)". 85
86 $perl_scalar = JSON::XS->new->utf8->decode ($json_text)
87
88 except being faster.
66 89
67OBJECT-ORIENTED INTERFACE 90OBJECT-ORIENTED INTERFACE
68 The object oriented interface lets you configure your own encoding or 91 The object oriented interface lets you configure your own encoding or
69 decoding style, within the limits of supported formats. 92 decoding style, within the limits of supported formats.
70 93
… …
74 *disabled*. 97 *disabled*.
75 98
76 The mutators for flags all return the JSON object again and thus 99 The mutators for flags all return the JSON object again and thus
77 calls can be chained: 100 calls can be chained:
78 101
79 my $json = JSON::XS->new->utf8(1)->space_after(1)->encode ({a => [1,2]}) 102 my $json = JSON::XS->new->utf8->space_after->encode ({a => [1,2]})
80 => {"a": [1, 2]} 103 => {"a": [1, 2]}
81 104
82 $json = $json->ascii ($enable) 105 $json = $json->ascii ([$enable])
83 If $enable is true, then the "encode" method will not generate 106 If $enable is true (or missing), then the "encode" method will not
84 characters outside the code range 0..127. Any unicode characters 107 generate characters outside the code range 0..127 (which is ASCII).
85 outside that range will be escaped using either a single \uXXXX (BMP 108 Any unicode characters outside that range will be escaped using
86 characters) or a double \uHHHH\uLLLLL escape sequence, as per 109 either a single \uXXXX (BMP characters) or a double \uHHHH\uLLLLL
87 RFC4627. 110 escape sequence, as per RFC4627.
88 111
89 If $enable is false, then the "encode" method will not escape 112 If $enable is false, then the "encode" method will not escape
90 Unicode characters unless necessary. 113 Unicode characters unless required by the JSON syntax. This results
114 in a faster and more compact format.
91 115
92 JSON::XS->new->ascii (1)->encode (chr 0x10401) 116 JSON::XS->new->ascii (1)->encode ([chr 0x10401])
93 => \ud801\udc01 117 => ["\ud801\udc01"]
94 118
95 $json = $json->utf8 ($enable) 119 $json = $json->utf8 ([$enable])
96 If $enable is true, then the "encode" method will encode the JSON 120 If $enable is true (or missing), then the "encode" method will
97 string into UTF-8, as required by many protocols, while the "decode" 121 encode the JSON result into UTF-8, as required by many protocols,
98 method expects to be handled an UTF-8-encoded string. Please note 122 while the "decode" method expects to be handled an UTF-8-encoded
99 that UTF-8-encoded strings do not contain any characters outside the 123 string. Please note that UTF-8-encoded strings do not contain any
100 range 0..255, they are thus useful for bytewise/binary I/O. 124 characters outside the range 0..255, they are thus useful for
125 bytewise/binary I/O. In future versions, enabling this option might
126 enable autodetection of the UTF-16 and UTF-32 encoding families, as
127 described in RFC4627.
101 128
102 If $enable is false, then the "encode" method will return the JSON 129 If $enable is false, then the "encode" method will return the JSON
103 string as a (non-encoded) unicode string, while "decode" expects 130 string as a (non-encoded) unicode string, while "decode" expects
104 thus a unicode string. Any decoding or encoding (e.g. to UTF-8 or 131 thus a unicode string. Any decoding or encoding (e.g. to UTF-8 or
105 UTF-16) needs to be done yourself, e.g. using the Encode module. 132 UTF-16) needs to be done yourself, e.g. using the Encode module.
106 133
134 Example, output UTF-16BE-encoded JSON:
135
136 use Encode;
137 $jsontext = encode "UTF-16BE", JSON::XS->new->encode ($object);
138
139 Example, decode UTF-32LE-encoded JSON:
140
141 use Encode;
142 $object = JSON::XS->new->decode (decode "UTF-32LE", $jsontext);
143
107 $json = $json->pretty ($enable) 144 $json = $json->pretty ([$enable])
108 This enables (or disables) all of the "indent", "space_before" and 145 This enables (or disables) all of the "indent", "space_before" and
109 "space_after" (and in the future possibly more) flags in one call to 146 "space_after" (and in the future possibly more) flags in one call to
110 generate the most readable (or most compact) form possible. 147 generate the most readable (or most compact) form possible.
148
149 Example, pretty-print some simple structure:
111 150
112 my $json = JSON::XS->new->pretty(1)->encode ({a => [1,2]}) 151 my $json = JSON::XS->new->pretty(1)->encode ({a => [1,2]})
113 => 152 =>
114 { 153 {
115 "a" : [ 154 "a" : [
116 1, 155 1,
117 2 156 2
118 ] 157 ]
119 } 158 }
120 159
121 $json = $json->indent ($enable) 160 $json = $json->indent ([$enable])
122 If $enable is true, then the "encode" method will use a multiline 161 If $enable is true (or missing), then the "encode" method will use a
123 format as output, putting every array member or object/hash 162 multiline format as output, putting every array member or
124 key-value pair into its own line, identing them properly. 163 object/hash key-value pair into its own line, identing them
164 properly.
125 165
126 If $enable is false, no newlines or indenting will be produced, and 166 If $enable is false, no newlines or indenting will be produced, and
127 the resulting JSON strings is guarenteed not to contain any 167 the resulting JSON text is guarenteed not to contain any "newlines".
128 "newlines".
129 168
130 This setting has no effect when decoding JSON strings. 169 This setting has no effect when decoding JSON texts.
131 170
132 $json = $json->space_before ($enable) 171 $json = $json->space_before ([$enable])
133 If $enable is true, then the "encode" method will add an extra 172 If $enable is true (or missing), then the "encode" method will add
134 optional space before the ":" separating keys from values in JSON 173 an extra optional space before the ":" separating keys from values
135 objects. 174 in JSON objects.
136 175
137 If $enable is false, then the "encode" method will not add any extra 176 If $enable is false, then the "encode" method will not add any extra
138 space at those places. 177 space at those places.
139 178
140 This setting has no effect when decoding JSON strings. You will also 179 This setting has no effect when decoding JSON texts. You will also
141 most likely combine this setting with "space_after". 180 most likely combine this setting with "space_after".
142 181
182 Example, space_before enabled, space_after and indent disabled:
183
184 {"key" :"value"}
185
143 $json = $json->space_after ($enable) 186 $json = $json->space_after ([$enable])
144 If $enable is true, then the "encode" method will add an extra 187 If $enable is true (or missing), then the "encode" method will add
145 optional space after the ":" separating keys from values in JSON 188 an extra optional space after the ":" separating keys from values in
146 objects and extra whitespace after the "," separating key-value 189 JSON objects and extra whitespace after the "," separating key-value
147 pairs and array members. 190 pairs and array members.
148 191
149 If $enable is false, then the "encode" method will not add any extra 192 If $enable is false, then the "encode" method will not add any extra
150 space at those places. 193 space at those places.
151 194
152 This setting has no effect when decoding JSON strings. 195 This setting has no effect when decoding JSON texts.
153 196
197 Example, space_before and indent disabled, space_after enabled:
198
199 {"key": "value"}
200
154 $json = $json->canonical ($enable) 201 $json = $json->canonical ([$enable])
155 If $enable is true, then the "encode" method will output JSON 202 If $enable is true (or missing), then the "encode" method will
156 objects by sorting their keys. This is adding a comparatively high 203 output JSON objects by sorting their keys. This is adding a
157 overhead. 204 comparatively high overhead.
158 205
159 If $enable is false, then the "encode" method will output key-value 206 If $enable is false, then the "encode" method will output key-value
160 pairs in the order Perl stores them (which will likely change 207 pairs in the order Perl stores them (which will likely change
161 between runs of the same script). 208 between runs of the same script).
162 209
163 This option is useful if you want the same data structure to be 210 This option is useful if you want the same data structure to be
164 encoded as the same JSON string (given the same overall settings). 211 encoded as the same JSON text (given the same overall settings). If
165 If it is disabled, the same hash migh be encoded differently even if 212 it is disabled, the same hash migh be encoded differently even if
166 contains the same data, as key-value pairs have no inherent ordering 213 contains the same data, as key-value pairs have no inherent ordering
167 in Perl. 214 in Perl.
168 215
169 This setting has no effect when decoding JSON strings. 216 This setting has no effect when decoding JSON texts.
170 217
171 $json = $json->allow_nonref ($enable) 218 $json = $json->allow_nonref ([$enable])
172 If $enable is true, then the "encode" method can convert a 219 If $enable is true (or missing), then the "encode" method can
173 non-reference into its corresponding string, number or null JSON 220 convert a non-reference into its corresponding string, number or
174 value, which is an extension to RFC4627. Likewise, "decode" will 221 null JSON value, which is an extension to RFC4627. Likewise,
175 accept those JSON values instead of croaking. 222 "decode" will accept those JSON values instead of croaking.
176 223
177 If $enable is false, then the "encode" method will croak if it isn't 224 If $enable is false, then the "encode" method will croak if it isn't
178 passed an arrayref or hashref, as JSON strings must either be an 225 passed an arrayref or hashref, as JSON texts must either be an
179 object or array. Likewise, "decode" will croak if given something 226 object or array. Likewise, "decode" will croak if given something
180 that is not a JSON object or array. 227 that is not a JSON object or array.
181 228
229 Example, encode a Perl scalar as JSON value with enabled
230 "allow_nonref", resulting in an invalid JSON text:
231
232 JSON::XS->new->allow_nonref->encode ("Hello, World!")
233 => "Hello, World!"
234
235 $json = $json->shrink ([$enable])
236 Perl usually over-allocates memory a bit when allocating space for
237 strings. This flag optionally resizes strings generated by either
238 "encode" or "decode" to their minimum size possible. This can save
239 memory when your JSON texts are either very very long or you have
240 many short strings. It will also try to downgrade any strings to
241 octet-form if possible: perl stores strings internally either in an
242 encoding called UTF-X or in octet-form. The latter cannot store
243 everything but uses less space in general.
244
245 If $enable is true (or missing), the string returned by "encode"
246 will be shrunk-to-fit, while all strings generated by "decode" will
247 also be shrunk-to-fit.
248
249 If $enable is false, then the normal perl allocation algorithms are
250 used. If you work with your data, then this is likely to be faster.
251
252 In the future, this setting might control other things, such as
253 converting strings that look like integers or floats into integers
254 or floats internally (there is no difference on the Perl level),
255 saving space.
256
182 $json_string = $json->encode ($perl_scalar) 257 $json_text = $json->encode ($perl_scalar)
183 Converts the given Perl data structure (a simple scalar or a 258 Converts the given Perl data structure (a simple scalar or a
184 reference to a hash or array) to its JSON representation. Simple 259 reference to a hash or array) to its JSON representation. Simple
185 scalars will be converted into JSON string or number sequences, 260 scalars will be converted into JSON string or number sequences,
186 while references to arrays become JSON arrays and references to 261 while references to arrays become JSON arrays and references to
187 hashes become JSON objects. Undefined Perl values (e.g. "undef") 262 hashes become JSON objects. Undefined Perl values (e.g. "undef")
188 become JSON "null" values. Neither "true" nor "false" values will be 263 become JSON "null" values. Neither "true" nor "false" values will be
189 generated. 264 generated.
190 265
191 $perl_scalar = $json->decode ($json_string) 266 $perl_scalar = $json->decode ($json_text)
192 The opposite of "encode": expects a JSON string and tries to parse 267 The opposite of "encode": expects a JSON text and tries to parse it,
193 it, returning the resulting simple scalar or reference. Croaks on 268 returning the resulting simple scalar or reference. Croaks on error.
194 error.
195 269
196 JSON numbers and strings become simple Perl scalars. JSON arrays 270 JSON numbers and strings become simple Perl scalars. JSON arrays
197 become Perl arrayrefs and JSON objects become Perl hashrefs. "true" 271 become Perl arrayrefs and JSON objects become Perl hashrefs. "true"
198 becomes 1, "false" becomes 0 and "null" becomes "undef". 272 becomes 1, "false" becomes 0 and "null" becomes "undef".
273
274MAPPING
275 This section describes how JSON::XS maps Perl values to JSON values and
276 vice versa. These mappings are designed to "do the right thing" in most
277 circumstances automatically, preserving round-tripping characteristics
278 (what you put in comes out as something equivalent).
279
280 For the more enlightened: note that in the following descriptions,
281 lowercase *perl* refers to the Perl interpreter, while uppcercase *Perl*
282 refers to the abstract Perl language itself.
283
284 JSON -> PERL
285 object
286 A JSON object becomes a reference to a hash in Perl. No ordering of
287 object keys is preserved (JSON does not preserver object key
288 ordering itself).
289
290 array
291 A JSON array becomes a reference to an array in Perl.
292
293 string
294 A JSON string becomes a string scalar in Perl - Unicode codepoints
295 in JSON are represented by the same codepoints in the Perl string,
296 so no manual decoding is necessary.
297
298 number
299 A JSON number becomes either an integer or numeric (floating point)
300 scalar in perl, depending on its range and any fractional parts. On
301 the Perl level, there is no difference between those as Perl handles
302 all the conversion details, but an integer may take slightly less
303 memory and might represent more values exactly than (floating point)
304 numbers.
305
306 true, false
307 These JSON atoms become 0, 1, respectively. Information is lost in
308 this process. Future versions might represent those values
309 differently, but they will be guarenteed to act like these integers
310 would normally in Perl.
311
312 null
313 A JSON null atom becomes "undef" in Perl.
314
315 PERL -> JSON
316 The mapping from Perl to JSON is slightly more difficult, as Perl is a
317 truly typeless language, so we can only guess which JSON type is meant
318 by a Perl value.
319
320 hash references
321 Perl hash references become JSON objects. As there is no inherent
322 ordering in hash keys, they will usually be encoded in a
323 pseudo-random order that can change between runs of the same program
324 but stays generally the same within a single run of a program.
325 JSON::XS can optionally sort the hash keys (determined by the
326 *canonical* flag), so the same datastructure will serialise to the
327 same JSON text (given same settings and version of JSON::XS), but
328 this incurs a runtime overhead.
329
330 array references
331 Perl array references become JSON arrays.
332
333 blessed objects
334 Blessed objects are not allowed. JSON::XS currently tries to encode
335 their underlying representation (hash- or arrayref), but this
336 behaviour might change in future versions.
337
338 simple scalars
339 Simple Perl scalars (any scalar that is not a reference) are the
340 most difficult objects to encode: JSON::XS will encode undefined
341 scalars as JSON null value, scalars that have last been used in a
342 string context before encoding as JSON strings and anything else as
343 number value:
344
345 # dump as number
346 to_json [2] # yields [2]
347 to_json [-3.0e17] # yields [-3e+17]
348 my $value = 5; to_json [$value] # yields [5]
349
350 # used as string, so dump as string
351 print $value;
352 to_json [$value] # yields ["5"]
353
354 # undef becomes null
355 to_json [undef] # yields [null]
356
357 You can force the type to be a string by stringifying it:
358
359 my $x = 3.1; # some variable containing a number
360 "$x"; # stringified
361 $x .= ""; # another, more awkward way to stringify
362 print $x; # perl does it for you, too, quite often
363
364 You can force the type to be a number by numifying it:
365
366 my $x = "3"; # some variable containing a string
367 $x += 0; # numify it, ensuring it will be dumped as a number
368 $x *= 1; # same thing, the choise is yours.
369
370 You can not currently output JSON booleans or force the type in
371 other, less obscure, ways. Tell me if you need this capability.
372
373 circular data structures
374 Those will be encoded until memory or stackspace runs out.
199 375
200COMPARISON 376COMPARISON
201 As already mentioned, this module was created because none of the 377 As already mentioned, this module was created because none of the
202 existing JSON modules could be made to work correctly. First I will 378 existing JSON modules could be made to work correctly. First I will
203 describe the problems (or pleasures) I encountered with various existing 379 describe the problems (or pleasures) I encountered with various existing
204 JSON modules, followed by some benchmark values. JSON::XS was designed 380 JSON modules, followed by some benchmark values. JSON::XS was designed
205 not to suffer from any of these problems or limitations. 381 not to suffer from any of these problems or limitations.
206 382
207 JSON 383 JSON 1.07
208 Slow (but very portable, as it is written in pure Perl). 384 Slow (but very portable, as it is written in pure Perl).
209 385
210 Undocumented/buggy Unicode handling (how JSON handles unicode values 386 Undocumented/buggy Unicode handling (how JSON handles unicode values
211 is undocumented. One can get far by feeding it unicode strings and 387 is undocumented. One can get far by feeding it unicode strings and
212 doing en-/decoding oneself, but unicode escapes are not working 388 doing en-/decoding oneself, but unicode escapes are not working
… …
214 390
215 No roundtripping (strings get clobbered if they look like numbers, 391 No roundtripping (strings get clobbered if they look like numbers,
216 e.g. the string 2.0 will encode to 2.0 instead of "2.0", and that 392 e.g. the string 2.0 will encode to 2.0 instead of "2.0", and that
217 will decode into the number 2. 393 will decode into the number 2.
218 394
219 JSON::PC 395 JSON::PC 0.01
220 Very fast. 396 Very fast.
221 397
222 Undocumented/buggy Unicode handling. 398 Undocumented/buggy Unicode handling.
223 399
224 No roundtripping. 400 No roundtripping.
225 401
226 Has problems handling many Perl values (e.g. regex results and other 402 Has problems handling many Perl values (e.g. regex results and other
227 magic values will make it croak). 403 magic values will make it croak).
228 404
229 Does not even generate valid JSON ("{1,2}" gets converted to "{1:2}" 405 Does not even generate valid JSON ("{1,2}" gets converted to "{1:2}"
230 which is not a valid JSON string. 406 which is not a valid JSON text.
231 407
232 Unmaintained (maintainer unresponsive for many months, bugs are not 408 Unmaintained (maintainer unresponsive for many months, bugs are not
233 getting fixed). 409 getting fixed).
234 410
235 JSON::Syck 411 JSON::Syck 0.21
236 Very buggy (often crashes). 412 Very buggy (often crashes).
237 413
238 Very inflexible (no human-readable format supported, format pretty 414 Very inflexible (no human-readable format supported, format pretty
239 much undocumented. I need at least a format for easy reading by 415 much undocumented. I need at least a format for easy reading by
240 humans and a single-line compact format for use in a protocol, and 416 humans and a single-line compact format for use in a protocol, and
241 preferably a way to generate ASCII-only JSON strings). 417 preferably a way to generate ASCII-only JSON texts).
242 418
243 Completely broken (and confusingly documented) Unicode handling 419 Completely broken (and confusingly documented) Unicode handling
244 (unicode escapes are not working properly, you need to set 420 (unicode escapes are not working properly, you need to set
245 ImplicitUnicode to *different* values on en- and decoding to get 421 ImplicitUnicode to *different* values on en- and decoding to get
246 symmetric behaviour). 422 symmetric behaviour).
… …
259 other using JSON. One bank might parse a given non-JSON request and 435 other using JSON. One bank might parse a given non-JSON request and
260 deduct money, while the other might reject the transaction with a 436 deduct money, while the other might reject the transaction with a
261 syntax error. While a good protocol will at least recover, that is 437 syntax error. While a good protocol will at least recover, that is
262 extra unnecessary work and the transaction will still not succeed). 438 extra unnecessary work and the transaction will still not succeed).
263 439
264 JSON::DWIW 440 JSON::DWIW 0.04
265 Very fast. Very natural. Very nice. 441 Very fast. Very natural. Very nice.
266 442
267 Undocumented unicode handling (but the best of the pack. Unicode 443 Undocumented unicode handling (but the best of the pack. Unicode
268 escapes still don't get parsed properly). 444 escapes still don't get parsed properly).
269 445
270 Very inflexible. 446 Very inflexible.
271 447
272 No roundtripping. 448 No roundtripping.
273 449
274 Does not generate valid JSON (key strings are often unquoted, empty 450 Does not generate valid JSON texts (key strings are often unquoted,
275 keys result in nothing being output) 451 empty keys result in nothing being output)
276 452
277 Does not check input for validity. 453 Does not check input for validity.
278 454
279 SPEED 455 SPEED
280 It seems that JSON::XS is surprisingly fast, as shown in the following 456 It seems that JSON::XS is surprisingly fast, as shown in the following
281 tables. They have been generated with the help of the "eg/bench" program 457 tables. They have been generated with the help of the "eg/bench" program
282 in the JSON::XS distribution, to make it easy to compare on your own 458 in the JSON::XS distribution, to make it easy to compare on your own
283 system. 459 system.
284 460
285 First is a comparison between various modules using a very simple JSON 461 First comes a comparison between various modules using a very short JSON
462 string:
463
464 {"method": "handleMessage", "params": ["user1", "we were just talking"], "id": null}
465
286 string, showing the number of encodes/decodes per second (JSON::XS is 466 It shows the number of encodes/decodes per second (JSON::XS uses the
287 the functional interface, while JSON::XS/2 is the OO interface with 467 functional interface, while JSON::XS/2 uses the OO interface with
288 pretty-printing and hashkey sorting enabled). 468 pretty-printing and hashkey sorting enabled). Higher is better:
289 469
290 module | encode | decode | 470 module | encode | decode |
291 -----------|------------|------------| 471 -----------|------------|------------|
292 JSON | 14006 | 6820 | 472 JSON | 11488.516 | 7823.035 |
293 JSON::DWIW | 200937 | 120386 | 473 JSON::DWIW | 94708.054 | 129094.260 |
294 JSON::PC | 85065 | 129366 | 474 JSON::PC | 63884.157 | 128528.212 |
295 JSON::Syck | 59898 | 44232 | 475 JSON::Syck | 34898.677 | 42096.911 |
296 JSON::XS | 1171478 | 342435 | 476 JSON::XS | 654027.064 | 396423.669 |
297 JSON::XS/2 | 730760 | 328714 | 477 JSON::XS/2 | 371564.190 | 371725.613 |
298 -----------+------------+------------+ 478 -----------+------------+------------+
299 479
300 That is, JSON::XS is 6 times faster than than JSON::DWIW and about 80 480 That is, JSON::XS is more than six times faster than JSON::DWIW on
481 encoding, more than three times faster on decoding, and about thirty
301 times faster than JSON, even with pretty-printing and key sorting. 482 times faster than JSON, even with pretty-printing and key sorting.
302 483
303 Using a longer test string (roughly 8KB, generated from Yahoo! Locals 484 Using a longer test string (roughly 18KB, generated from Yahoo! Locals
304 search API (http://nanoref.com/yahooapis/mgPdGg): 485 search API (http://nanoref.com/yahooapis/mgPdGg):
305 486
306 module | encode | decode | 487 module | encode | decode |
307 -----------|------------|------------| 488 -----------|------------|------------|
308 JSON | 673 | 38 | 489 JSON | 273.023 | 44.674 |
309 JSON::DWIW | 5271 | 770 | 490 JSON::DWIW | 1089.383 | 1145.704 |
310 JSON::PC | 9901 | 2491 | 491 JSON::PC | 3097.419 | 2393.921 |
311 JSON::Syck | 2360 | 786 | 492 JSON::Syck | 514.060 | 843.053 |
312 JSON::XS | 37398 | 3202 | 493 JSON::XS | 6479.668 | 3636.364 |
313 JSON::XS/2 | 13765 | 3153 | 494 JSON::XS/2 | 3774.221 | 3599.124 |
314 -----------+------------+------------+ 495 -----------+------------+------------+
315 496
316 Again, JSON::XS leads by far in the encoding case, while still beating 497 Again, JSON::XS leads by far.
317 every other module in the decoding case.
318 498
319 Last example is an almost 8MB large hash with many large binary values 499 On large strings containing lots of high unicode characters, some
320 (PNG files), resulting in a lot of escaping: 500 modules (such as JSON::PC) seem to decode faster than JSON::XS, but the
501 result will be broken due to missing (or wrong) unicode handling. Others
502 refuse to decode or encode properly, so it was impossible to prepare a
503 fair comparison table for that case.
504
505RESOURCE LIMITS
506 JSON::XS does not impose any limits on the size of JSON texts or Perl
507 values they represent - if your machine can handle it, JSON::XS will
508 encode or decode it. Future versions might optionally impose structure
509 depth and memory use resource limits.
321 510
322BUGS 511BUGS
323 While the goal of this module is to be correct, that unfortunately does 512 While the goal of this module is to be correct, that unfortunately does
324 not mean its bug-free, only that I think its design is bug-free. It is 513 not mean its bug-free, only that I think its design is bug-free. It is
325 still very young and not well-tested. If you keep reporting bugs they 514 still very young and not well-tested. If you keep reporting bugs they

Diff Legend

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