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

Comparing JSON-XS/README (file contents):
Revision 1.3 by root, Thu Mar 22 23:24:18 2007 UTC vs.
Revision 1.5 by root, Sat Mar 24 01:15:22 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 strings 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_string = 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)". 74 "JSON::XS->new->utf8->encode ($perl_scalar)".
58 75
59 $perl_scalar = from_json $json_string 76 $perl_scalar = from_json $json_string
60 The opposite of "to_json": expects an UTF-8 (binary) string and 77 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 78 tries to parse that as an UTF-8 encoded JSON string, returning the
62 resulting simple scalar or reference. Croaks on error. 79 resulting simple scalar or reference. Croaks on error.
63 80
64 This function call is functionally identical to "JSON::XS->new->utf8 81 This function call is functionally identical to
65 (1)->decode ($json_string)". 82 "JSON::XS->new->utf8->decode ($json_string)".
66 83
67OBJECT-ORIENTED INTERFACE 84OBJECT-ORIENTED INTERFACE
68 The object oriented interface lets you configure your own encoding or 85 The object oriented interface lets you configure your own encoding or
69 decoding style, within the limits of supported formats. 86 decoding style, within the limits of supported formats.
70 87
… …
77 calls can be chained: 94 calls can be chained:
78 95
79 my $json = JSON::XS->new->utf8(1)->space_after(1)->encode ({a => [1,2]}) 96 my $json = JSON::XS->new->utf8(1)->space_after(1)->encode ({a => [1,2]})
80 => {"a": [1, 2]} 97 => {"a": [1, 2]}
81 98
82 $json = $json->ascii ($enable) 99 $json = $json->ascii ([$enable])
83 If $enable is true, then the "encode" method will not generate 100 If $enable is true (or missing), then the "encode" method will not
84 characters outside the code range 0..127. Any unicode characters 101 generate characters outside the code range 0..127. Any unicode
85 outside that range will be escaped using either a single \uXXXX (BMP 102 characters outside that range will be escaped using either a single
86 characters) or a double \uHHHH\uLLLLL escape sequence, as per 103 \uXXXX (BMP characters) or a double \uHHHH\uLLLLL escape sequence,
87 RFC4627. 104 as per RFC4627.
88 105
89 If $enable is false, then the "encode" method will not escape 106 If $enable is false, then the "encode" method will not escape
90 Unicode characters unless necessary. 107 Unicode characters unless necessary.
91 108
92 JSON::XS->new->ascii (1)->encode (chr 0x10401) 109 JSON::XS->new->ascii (1)->encode (chr 0x10401)
93 => \ud801\udc01 110 => \ud801\udc01
94 111
95 $json = $json->utf8 ($enable) 112 $json = $json->utf8 ([$enable])
96 If $enable is true, then the "encode" method will encode the JSON 113 If $enable is true (or missing), then the "encode" method will
97 string into UTF-8, as required by many protocols, while the "decode" 114 encode the JSON string into UTF-8, as required by many protocols,
98 method expects to be handled an UTF-8-encoded string. Please note 115 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 116 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. 117 characters outside the range 0..255, they are thus useful for
118 bytewise/binary I/O.
101 119
102 If $enable is false, then the "encode" method will return the JSON 120 If $enable is false, then the "encode" method will return the JSON
103 string as a (non-encoded) unicode string, while "decode" expects 121 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 122 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. 123 UTF-16) needs to be done yourself, e.g. using the Encode module.
106 124
125 Example, output UTF-16-encoded JSON:
126
107 $json = $json->pretty ($enable) 127 $json = $json->pretty ([$enable])
108 This enables (or disables) all of the "indent", "space_before" and 128 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 129 "space_after" (and in the future possibly more) flags in one call to
110 generate the most readable (or most compact) form possible. 130 generate the most readable (or most compact) form possible.
131
132 Example, pretty-print some simple structure:
111 133
112 my $json = JSON::XS->new->pretty(1)->encode ({a => [1,2]}) 134 my $json = JSON::XS->new->pretty(1)->encode ({a => [1,2]})
113 => 135 =>
114 { 136 {
115 "a" : [ 137 "a" : [
116 1, 138 1,
117 2 139 2
118 ] 140 ]
119 } 141 }
120 142
121 $json = $json->indent ($enable) 143 $json = $json->indent ([$enable])
122 If $enable is true, then the "encode" method will use a multiline 144 If $enable is true (or missing), then the "encode" method will use a
123 format as output, putting every array member or object/hash 145 multiline format as output, putting every array member or
124 key-value pair into its own line, identing them properly. 146 object/hash key-value pair into its own line, identing them
147 properly.
125 148
126 If $enable is false, no newlines or indenting will be produced, and 149 If $enable is false, no newlines or indenting will be produced, and
127 the resulting JSON strings is guarenteed not to contain any 150 the resulting JSON strings is guarenteed not to contain any
128 "newlines". 151 "newlines".
129 152
130 This setting has no effect when decoding JSON strings. 153 This setting has no effect when decoding JSON strings.
131 154
132 $json = $json->space_before ($enable) 155 $json = $json->space_before ([$enable])
133 If $enable is true, then the "encode" method will add an extra 156 If $enable is true (or missing), then the "encode" method will add
134 optional space before the ":" separating keys from values in JSON 157 an extra optional space before the ":" separating keys from values
135 objects. 158 in JSON objects.
136 159
137 If $enable is false, then the "encode" method will not add any extra 160 If $enable is false, then the "encode" method will not add any extra
138 space at those places. 161 space at those places.
139 162
140 This setting has no effect when decoding JSON strings. You will also 163 This setting has no effect when decoding JSON strings. You will also
141 most likely combine this setting with "space_after". 164 most likely combine this setting with "space_after".
142 165
166 Example, space_before enabled, space_after and indent disabled:
167
168 {"key" :"value"}
169
143 $json = $json->space_after ($enable) 170 $json = $json->space_after ([$enable])
144 If $enable is true, then the "encode" method will add an extra 171 If $enable is true (or missing), then the "encode" method will add
145 optional space after the ":" separating keys from values in JSON 172 an extra optional space after the ":" separating keys from values in
146 objects and extra whitespace after the "," separating key-value 173 JSON objects and extra whitespace after the "," separating key-value
147 pairs and array members. 174 pairs and array members.
148 175
149 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
150 space at those places. 177 space at those places.
151 178
152 This setting has no effect when decoding JSON strings. 179 This setting has no effect when decoding JSON strings.
153 180
181 Example, space_before and indent disabled, space_after enabled:
182
183 {"key": "value"}
184
154 $json = $json->canonical ($enable) 185 $json = $json->canonical ([$enable])
155 If $enable is true, then the "encode" method will output JSON 186 If $enable is true (or missing), then the "encode" method will
156 objects by sorting their keys. This is adding a comparatively high 187 output JSON objects by sorting their keys. This is adding a
157 overhead. 188 comparatively high overhead.
158 189
159 If $enable is false, then the "encode" method will output key-value 190 If $enable is false, then the "encode" method will output key-value
160 pairs in the order Perl stores them (which will likely change 191 pairs in the order Perl stores them (which will likely change
161 between runs of the same script). 192 between runs of the same script).
162 193
… …
166 contains the same data, as key-value pairs have no inherent ordering 197 contains the same data, as key-value pairs have no inherent ordering
167 in Perl. 198 in Perl.
168 199
169 This setting has no effect when decoding JSON strings. 200 This setting has no effect when decoding JSON strings.
170 201
171 $json = $json->allow_nonref ($enable) 202 $json = $json->allow_nonref ([$enable])
172 If $enable is true, then the "encode" method can convert a 203 If $enable is true (or missing), then the "encode" method can
173 non-reference into its corresponding string, number or null JSON 204 convert a non-reference into its corresponding string, number or
174 value, which is an extension to RFC4627. Likewise, "decode" will 205 null JSON value, which is an extension to RFC4627. Likewise,
175 accept those JSON values instead of croaking. 206 "decode" will accept those JSON values instead of croaking.
176 207
177 If $enable is false, then the "encode" method will croak if it isn't 208 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 209 passed an arrayref or hashref, as JSON strings must either be an
179 object or array. Likewise, "decode" will croak if given something 210 object or array. Likewise, "decode" will croak if given something
180 that is not a JSON object or array. 211 that is not a JSON object or array.
212
213 Example, encode a Perl scalar as JSON value with enabled
214 "allow_nonref", resulting in an invalid JSON text:
215
216 JSON::XS->new->allow_nonref->encode ("Hello, World!")
217 => "Hello, World!"
218
219 $json = $json->shrink ([$enable])
220 Perl usually over-allocates memory a bit when allocating space for
221 strings. This flag optionally resizes strings generated by either
222 "encode" or "decode" to their minimum size possible. This can save
223 memory when your JSON strings are either very very long or you have
224 many short strings. It will also try to downgrade any strings to
225 octet-form if possible: perl stores strings internally either in an
226 encoding called UTF-X or in octet-form. The latter cannot store
227 everything but uses less space in general.
228
229 If $enable is true (or missing), the string returned by "encode"
230 will be shrunk-to-fit, while all strings generated by "decode" will
231 also be shrunk-to-fit.
232
233 If $enable is false, then the normal perl allocation algorithms are
234 used. If you work with your data, then this is likely to be faster.
235
236 In the future, this setting might control other things, such as
237 converting strings that look like integers or floats into integers
238 or floats internally (there is no difference on the Perl level),
239 saving space.
181 240
182 $json_string = $json->encode ($perl_scalar) 241 $json_string = $json->encode ($perl_scalar)
183 Converts the given Perl data structure (a simple scalar or a 242 Converts the given Perl data structure (a simple scalar or a
184 reference to a hash or array) to its JSON representation. Simple 243 reference to a hash or array) to its JSON representation. Simple
185 scalars will be converted into JSON string or number sequences, 244 scalars will be converted into JSON string or number sequences,
… …
195 254
196 JSON numbers and strings become simple Perl scalars. JSON arrays 255 JSON numbers and strings become simple Perl scalars. JSON arrays
197 become Perl arrayrefs and JSON objects become Perl hashrefs. "true" 256 become Perl arrayrefs and JSON objects become Perl hashrefs. "true"
198 becomes 1, "false" becomes 0 and "null" becomes "undef". 257 becomes 1, "false" becomes 0 and "null" becomes "undef".
199 258
259MAPPING
260 This section describes how JSON::XS maps Perl values to JSON values and
261 vice versa. These mappings are designed to "do the right thing" in most
262 circumstances automatically, preserving round-tripping characteristics
263 (what you put in comes out as something equivalent).
264
265 For the more enlightened: note that in the following descriptions,
266 lowercase *perl* refers to the Perl interpreter, while uppcercase *Perl*
267 refers to the abstract Perl language itself.
268
269 JSON -> PERL
270 object
271 A JSON object becomes a reference to a hash in Perl. No ordering of
272 object keys is preserved (JSON does not preserver object key
273 ordering itself).
274
275 array
276 A JSON array becomes a reference to an array in Perl.
277
278 string
279 A JSON string becomes a string scalar in Perl - Unicode codepoints
280 in JSON are represented by the same codepoints in the Perl string,
281 so no manual decoding is necessary.
282
283 number
284 A JSON number becomes either an integer or numeric (floating point)
285 scalar in perl, depending on its range and any fractional parts. On
286 the Perl level, there is no difference between those as Perl handles
287 all the conversion details, but an integer may take slightly less
288 memory and might represent more values exactly than (floating point)
289 numbers.
290
291 true, false
292 These JSON atoms become 0, 1, respectively. Information is lost in
293 this process. Future versions might represent those values
294 differently, but they will be guarenteed to act like these integers
295 would normally in Perl.
296
297 null
298 A JSON null atom becomes "undef" in Perl.
299
300 PERL -> JSON
301 The mapping from Perl to JSON is slightly more difficult, as Perl is a
302 truly typeless language, so we can only guess which JSON type is meant
303 by a Perl value.
304
305 hash references
306 Perl hash references become JSON objects. As there is no inherent
307 ordering in hash keys, they will usually be encoded in a
308 pseudo-random order that can change between runs of the same program
309 but stays generally the same within a single run of a program.
310 JSON::XS can optionally sort the hash keys (determined by the
311 *canonical* flag), so the same datastructure will serialise to the
312 same JSON text (given same settings and version of JSON::XS), but
313 this incurs a runtime overhead.
314
315 array references
316 Perl array references become JSON arrays.
317
318 blessed objects
319 Blessed objects are not allowed. JSON::XS currently tries to encode
320 their underlying representation (hash- or arrayref), but this
321 behaviour might change in future versions.
322
323 simple scalars
324 Simple Perl scalars (any scalar that is not a reference) are the
325 most difficult objects to encode: JSON::XS will encode undefined
326 scalars as JSON null value, scalars that have last been used in a
327 string context before encoding as JSON strings and anything else as
328 number value:
329
330 # dump as number
331 to_json [2] # yields [2]
332 to_json [-3.0e17] # yields [-3e+17]
333 my $value = 5; to_json [$value] # yields [5]
334
335 # used as string, so dump as string
336 print $value;
337 to_json [$value] # yields ["5"]
338
339 # undef becomes null
340 to_json [undef] # yields [null]
341
342 You can force the type to be a string by stringifying it:
343
344 my $x = 3.1; # some variable containing a number
345 "$x"; # stringified
346 $x .= ""; # another, more awkward way to stringify
347 print $x; # perl does it for you, too, quite often
348
349 You can force the type to be a number by numifying it:
350
351 my $x = "3"; # some variable containing a string
352 $x += 0; # numify it, ensuring it will be dumped as a number
353 $x *= 1; # same thing, the choise is yours.
354
355 You can not currently output JSON booleans or force the type in
356 other, less obscure, ways. Tell me if you need this capability.
357
358 circular data structures
359 Those will be encoded until memory or stackspace runs out.
360
200COMPARISON 361COMPARISON
201 As already mentioned, this module was created because none of the 362 As already mentioned, this module was created because none of the
202 existing JSON modules could be made to work correctly. First I will 363 existing JSON modules could be made to work correctly. First I will
203 describe the problems (or pleasures) I encountered with various existing 364 describe the problems (or pleasures) I encountered with various existing
204 JSON modules, followed by some benchmark values. JSON::XS was designed 365 JSON modules, followed by some benchmark values. JSON::XS was designed
… …
280 It seems that JSON::XS is surprisingly fast, as shown in the following 441 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 442 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 443 in the JSON::XS distribution, to make it easy to compare on your own
283 system. 444 system.
284 445
285 First is a comparison between various modules using a very simple JSON 446 First comes a comparison between various modules using a very short JSON
286 string, showing the number of encodes/decodes per second (JSON::XS is 447 string (83 bytes), showing the number of encodes/decodes per second
287 the functional interface, while JSON::XS/2 is the OO interface with 448 (JSON::XS is the functional interface, while JSON::XS/2 is the OO
288 pretty-printing and hashkey sorting enabled). 449 interface with pretty-printing and hashkey sorting enabled). Higher is
450 better:
289 451
290 module | encode | decode | 452 module | encode | decode |
291 -----------|------------|------------| 453 -----------|------------|------------|
292 JSON | 14006 | 6820 | 454 JSON | 14006 | 6820 |
293 JSON::DWIW | 200937 | 120386 | 455 JSON::DWIW | 200937 | 120386 |
… …
298 -----------+------------+------------+ 460 -----------+------------+------------+
299 461
300 That is, JSON::XS is 6 times faster than than JSON::DWIW and about 80 462 That is, JSON::XS is 6 times faster than than JSON::DWIW and about 80
301 times faster than JSON, even with pretty-printing and key sorting. 463 times faster than JSON, even with pretty-printing and key sorting.
302 464
303 Using a longer test string (roughly 8KB, generated from Yahoo! Locals 465 Using a longer test string (roughly 18KB, generated from Yahoo! Locals
304 search API (http://nanoref.com/yahooapis/mgPdGg): 466 search API (http://nanoref.com/yahooapis/mgPdGg):
305 467
306 module | encode | decode | 468 module | encode | decode |
307 -----------|------------|------------| 469 -----------|------------|------------|
308 JSON | 673 | 38 | 470 JSON | 673 | 38 |
… …
314 -----------+------------+------------+ 476 -----------+------------+------------+
315 477
316 Again, JSON::XS leads by far in the encoding case, while still beating 478 Again, JSON::XS leads by far in the encoding case, while still beating
317 every other module in the decoding case. 479 every other module in the decoding case.
318 480
319 Last example is an almost 8MB large hash with many large binary values 481 On large strings containing lots of unicode characters, some modules
320 (PNG files), resulting in a lot of escaping: 482 (such as JSON::PC) decode faster than JSON::XS, but the result will be
483 broken due to missing unicode handling. Others refuse to decode or
484 encode properly, so it was impossible to prepare a fair comparison table
485 for that case.
486
487RESOURCE LIMITS
488 JSON::XS does not impose any limits on the size of JSON texts or Perl
489 values they represent - if your machine can handle it, JSON::XS will
490 encode or decode it. Future versions might optionally impose structure
491 depth and memory use resource limits.
321 492
322BUGS 493BUGS
323 While the goal of this module is to be correct, that unfortunately does 494 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 495 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 496 still very young and not well-tested. If you keep reporting bugs they

Diff Legend

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