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.4 by root, Fri Mar 23 18:33:50 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,
… …
194 error. 253 error.
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".
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.
273
274 array
275 A JSON array becomes a reference to an array in Perl.
276
277 string
278 A JSON string becomes a string scalar in Perl - Unicode codepoints
279 in JSON are represented by the same codepoints in the Perl string,
280 so no manual decoding is necessary.
281
282 number
283 A JSON number becomes either an integer or numeric (floating point)
284 scalar in perl, depending on its range and any fractional parts. On
285 the Perl level, there is no difference between those as Perl handles
286 all the conversion details, but an integer may take slightly less
287 memory and might represent more values exactly than (floating point)
288 numbers.
289
290 true, false
291 These JSON atoms become 0, 1, respectively. Information is lost in
292 this process. Future versions might represent those values
293 differently, but they will be guarenteed to act like these integers
294 would normally in Perl.
295
296 null
297 A JSON null atom becomes "undef" in Perl.
298
299 PERL -> JSON
300 The mapping from Perl to JSON is slightly more difficult, as Perl is a
301 truly typeless language, so we can only guess which JSON type is meant
302 by a Perl value.
303
304 hash references
305 Perl hash references become JSON objects. As there is no inherent
306 ordering in hash keys, they will usually be encoded in a
307 pseudo-random order that can change between runs of the same program
308 but stays generally the same within the single run of a program.
309 JSON::XS can optionally sort the hash keys (determined by the
310 *canonical* flag), so the same datastructure will serialise to the
311 same JSON text (given same settings and version of JSON::XS), but
312 this incurs a runtime overhead.
313
314 array references
315 Perl array references become JSON arrays.
316
317 blessed objects
318 Blessed objects are not allowed. JSON::XS currently tries to encode
319 their underlying representation (hash- or arrayref), but this
320 behaviour might change in future versions.
321
322 simple scalars
323 Simple Perl scalars (any scalar that is not a reference) are the
324 most difficult objects to encode: JSON::XS will encode undefined
325 scalars as JSON null value, scalars that have last been used in a
326 string context before encoding as JSON strings and anything else as
327 number value:
328
329 # dump as number
330 to_json [2] # yields [2]
331 to_json [-3.0e17] # yields [-3e+17]
332 my $value = 5; to_json [$value] # yields [5]
333
334 # used as string, so dump as string
335 print $value;
336 to_json [$value] # yields ["5"]
337
338 # undef becomes null
339 to_json [undef] # yields [null]
340
341 You can force the type to be a string by stringifying it:
342
343 my $x = 3.1; # some variable containing a number
344 "$x"; # stringified
345 $x .= ""; # another, more awkward way to stringify
346 print $x; # perl does it for you, too, quite often
347
348 You can force the type to be a number by numifying it:
349
350 my $x = "3"; # some variable containing a string
351 $x += 0; # numify it, ensuring it will be dumped as a number
352 $x *= 1; # same thing, the choise is yours.
353
354 You can not currently output JSON booleans or force the type in
355 other, less obscure, ways. Tell me if you need this capability.
356
357 circular data structures
358 Those will be encoded until memory or stackspace runs out.
199 359
200COMPARISON 360COMPARISON
201 As already mentioned, this module was created because none of the 361 As already mentioned, this module was created because none of the
202 existing JSON modules could be made to work correctly. First I will 362 existing JSON modules could be made to work correctly. First I will
203 describe the problems (or pleasures) I encountered with various existing 363 describe the problems (or pleasures) I encountered with various existing
… …
314 -----------+------------+------------+ 474 -----------+------------+------------+
315 475
316 Again, JSON::XS leads by far in the encoding case, while still beating 476 Again, JSON::XS leads by far in the encoding case, while still beating
317 every other module in the decoding case. 477 every other module in the decoding case.
318 478
319 Last example is an almost 8MB large hash with many large binary values 479RESOURCE LIMITS
320 (PNG files), resulting in a lot of escaping: 480 JSON::XS does not impose any limits on the size of JSON texts or Perl
481 values they represent - if your machine can handle it, JSON::XS will
482 encode or decode it. Future versions might optionally impose structure
483 depth and memory use resource limits.
321 484
322BUGS 485BUGS
323 While the goal of this module is to be correct, that unfortunately does 486 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 487 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 488 still very young and not well-tested. If you keep reporting bugs they

Diff Legend

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