… | |
… | |
40 | When you serialise a perl data structure using only datatypes |
40 | When you serialise a perl data structure using only datatypes |
41 | supported by JSON, the deserialised data structure is identical on |
41 | supported by JSON, the deserialised data structure is identical on |
42 | 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"). |
43 | |
43 | |
44 | * strict checking of JSON correctness |
44 | * strict checking of JSON correctness |
45 | There is no guessing, no generating of illegal JSON strings by |
45 | There is no guessing, no generating of illegal JSON texts by |
46 | default, and only JSON is accepted as input by default (the latter |
46 | default, and only JSON is accepted as input by default (the latter |
47 | is a security feature). |
47 | is a security feature). |
48 | |
48 | |
49 | * fast |
49 | * fast |
50 | Compared to other JSON modules, this module compares favourably in |
50 | Compared to other JSON modules, this module compares favourably in |
… | |
… | |
63 | |
63 | |
64 | FUNCTIONAL INTERFACE |
64 | FUNCTIONAL INTERFACE |
65 | The following convinience methods are provided by this module. They are |
65 | The following convinience methods are provided by this module. They are |
66 | exported by default: |
66 | exported by default: |
67 | |
67 | |
68 | $json_string = to_json $perl_scalar |
68 | $json_text = to_json $perl_scalar |
69 | Converts the given Perl data structure (a simple scalar or a |
69 | Converts the given Perl data structure (a simple scalar or a |
70 | 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 |
71 | (that is, the string contains octets only). Croaks on error. |
71 | (that is, the string contains octets only). Croaks on error. |
72 | |
72 | |
73 | This function call is functionally identical to |
73 | This function call is functionally identical to: |
|
|
74 | |
74 | "JSON::XS->new->utf8->encode ($perl_scalar)". |
75 | $json_text = JSON::XS->new->utf8->encode ($perl_scalar) |
75 | |
76 | |
|
|
77 | except being faster. |
|
|
78 | |
76 | $perl_scalar = from_json $json_string |
79 | $perl_scalar = from_json $json_text |
77 | 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 |
78 | 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 |
79 | resulting simple scalar or reference. Croaks on error. |
82 | resulting simple scalar or reference. Croaks on error. |
80 | |
83 | |
81 | This function call is functionally identical to |
84 | This function call is functionally identical to: |
|
|
85 | |
82 | "JSON::XS->new->utf8->decode ($json_string)". |
86 | $perl_scalar = JSON::XS->new->utf8->decode ($json_text) |
|
|
87 | |
|
|
88 | except being faster. |
83 | |
89 | |
84 | OBJECT-ORIENTED INTERFACE |
90 | OBJECT-ORIENTED INTERFACE |
85 | The object oriented interface lets you configure your own encoding or |
91 | The object oriented interface lets you configure your own encoding or |
86 | decoding style, within the limits of supported formats. |
92 | decoding style, within the limits of supported formats. |
87 | |
93 | |
… | |
… | |
91 | *disabled*. |
97 | *disabled*. |
92 | |
98 | |
93 | 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 |
94 | calls can be chained: |
100 | calls can be chained: |
95 | |
101 | |
96 | 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]}) |
97 | => {"a": [1, 2]} |
103 | => {"a": [1, 2]} |
98 | |
104 | |
99 | $json = $json->ascii ([$enable]) |
105 | $json = $json->ascii ([$enable]) |
100 | If $enable is true (or missing), then the "encode" method will not |
106 | If $enable is true (or missing), then the "encode" method will not |
101 | generate characters outside the code range 0..127. Any unicode |
107 | generate characters outside the code range 0..127 (which is ASCII). |
102 | characters outside that range will be escaped using either a single |
108 | Any unicode characters outside that range will be escaped using |
103 | \uXXXX (BMP characters) or a double \uHHHH\uLLLLL escape sequence, |
109 | either a single \uXXXX (BMP characters) or a double \uHHHH\uLLLLL |
104 | as per RFC4627. |
110 | escape sequence, as per RFC4627. |
105 | |
111 | |
106 | If $enable is false, then the "encode" method will not escape |
112 | If $enable is false, then the "encode" method will not escape |
107 | Unicode characters unless necessary. |
113 | Unicode characters unless required by the JSON syntax. This results |
|
|
114 | in a faster and more compact format. |
108 | |
115 | |
109 | JSON::XS->new->ascii (1)->encode (chr 0x10401) |
116 | JSON::XS->new->ascii (1)->encode ([chr 0x10401]) |
110 | => \ud801\udc01 |
117 | => ["\ud801\udc01"] |
111 | |
118 | |
112 | $json = $json->utf8 ([$enable]) |
119 | $json = $json->utf8 ([$enable]) |
113 | If $enable is true (or missing), then the "encode" method will |
120 | If $enable is true (or missing), then the "encode" method will |
114 | encode the JSON string into UTF-8, as required by many protocols, |
121 | encode the JSON result into UTF-8, as required by many protocols, |
115 | while the "decode" method expects to be handled an UTF-8-encoded |
122 | while the "decode" method expects to be handled an UTF-8-encoded |
116 | string. Please note that UTF-8-encoded strings do not contain any |
123 | string. Please note that UTF-8-encoded strings do not contain any |
117 | characters outside the range 0..255, they are thus useful for |
124 | characters outside the range 0..255, they are thus useful for |
118 | bytewise/binary I/O. |
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. |
119 | |
128 | |
120 | 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 |
121 | string as a (non-encoded) unicode string, while "decode" expects |
130 | string as a (non-encoded) unicode string, while "decode" expects |
122 | 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 |
123 | 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. |
124 | |
133 | |
125 | Example, output UTF-16-encoded JSON: |
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); |
126 | |
143 | |
127 | $json = $json->pretty ([$enable]) |
144 | $json = $json->pretty ([$enable]) |
128 | This enables (or disables) all of the "indent", "space_before" and |
145 | This enables (or disables) all of the "indent", "space_before" and |
129 | "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 |
130 | generate the most readable (or most compact) form possible. |
147 | generate the most readable (or most compact) form possible. |
… | |
… | |
145 | multiline format as output, putting every array member or |
162 | multiline format as output, putting every array member or |
146 | object/hash key-value pair into its own line, identing them |
163 | object/hash key-value pair into its own line, identing them |
147 | properly. |
164 | properly. |
148 | |
165 | |
149 | 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 |
150 | the resulting JSON strings is guarenteed not to contain any |
167 | the resulting JSON text is guarenteed not to contain any "newlines". |
151 | "newlines". |
|
|
152 | |
168 | |
153 | This setting has no effect when decoding JSON strings. |
169 | This setting has no effect when decoding JSON texts. |
154 | |
170 | |
155 | $json = $json->space_before ([$enable]) |
171 | $json = $json->space_before ([$enable]) |
156 | If $enable is true (or missing), then the "encode" method will add |
172 | If $enable is true (or missing), then the "encode" method will add |
157 | an extra optional space before the ":" separating keys from values |
173 | an extra optional space before the ":" separating keys from values |
158 | in JSON objects. |
174 | in JSON objects. |
159 | |
175 | |
160 | 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 |
161 | space at those places. |
177 | space at those places. |
162 | |
178 | |
163 | 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 |
164 | most likely combine this setting with "space_after". |
180 | most likely combine this setting with "space_after". |
165 | |
181 | |
166 | Example, space_before enabled, space_after and indent disabled: |
182 | Example, space_before enabled, space_after and indent disabled: |
167 | |
183 | |
168 | {"key" :"value"} |
184 | {"key" :"value"} |
… | |
… | |
174 | pairs and array members. |
190 | pairs and array members. |
175 | |
191 | |
176 | 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 |
177 | space at those places. |
193 | space at those places. |
178 | |
194 | |
179 | This setting has no effect when decoding JSON strings. |
195 | This setting has no effect when decoding JSON texts. |
180 | |
196 | |
181 | Example, space_before and indent disabled, space_after enabled: |
197 | Example, space_before and indent disabled, space_after enabled: |
182 | |
198 | |
183 | {"key": "value"} |
199 | {"key": "value"} |
184 | |
200 | |
… | |
… | |
190 | 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 |
191 | pairs in the order Perl stores them (which will likely change |
207 | pairs in the order Perl stores them (which will likely change |
192 | between runs of the same script). |
208 | between runs of the same script). |
193 | |
209 | |
194 | 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 |
195 | encoded as the same JSON string (given the same overall settings). |
211 | encoded as the same JSON text (given the same overall settings). If |
196 | 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 |
197 | 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 |
198 | in Perl. |
214 | in Perl. |
199 | |
215 | |
200 | This setting has no effect when decoding JSON strings. |
216 | This setting has no effect when decoding JSON texts. |
201 | |
217 | |
202 | $json = $json->allow_nonref ([$enable]) |
218 | $json = $json->allow_nonref ([$enable]) |
203 | If $enable is true (or missing), then the "encode" method can |
219 | If $enable is true (or missing), then the "encode" method can |
204 | convert a non-reference into its corresponding string, number or |
220 | convert a non-reference into its corresponding string, number or |
205 | null JSON value, which is an extension to RFC4627. Likewise, |
221 | null JSON value, which is an extension to RFC4627. Likewise, |
206 | "decode" will accept those JSON values instead of croaking. |
222 | "decode" will accept those JSON values instead of croaking. |
207 | |
223 | |
208 | 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 |
209 | 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 |
210 | object or array. Likewise, "decode" will croak if given something |
226 | object or array. Likewise, "decode" will croak if given something |
211 | that is not a JSON object or array. |
227 | that is not a JSON object or array. |
212 | |
228 | |
213 | Example, encode a Perl scalar as JSON value with enabled |
229 | Example, encode a Perl scalar as JSON value with enabled |
214 | "allow_nonref", resulting in an invalid JSON text: |
230 | "allow_nonref", resulting in an invalid JSON text: |
… | |
… | |
218 | |
234 | |
219 | $json = $json->shrink ([$enable]) |
235 | $json = $json->shrink ([$enable]) |
220 | Perl usually over-allocates memory a bit when allocating space for |
236 | Perl usually over-allocates memory a bit when allocating space for |
221 | strings. This flag optionally resizes strings generated by either |
237 | strings. This flag optionally resizes strings generated by either |
222 | "encode" or "decode" to their minimum size possible. This can save |
238 | "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 |
239 | memory when your JSON texts are either very very long or you have |
224 | many short strings. It will also try to downgrade any strings to |
240 | many short strings. It will also try to downgrade any strings to |
225 | octet-form if possible: perl stores strings internally either in an |
241 | octet-form if possible: perl stores strings internally either in an |
226 | encoding called UTF-X or in octet-form. The latter cannot store |
242 | encoding called UTF-X or in octet-form. The latter cannot store |
227 | everything but uses less space in general. |
243 | everything but uses less space in general. |
228 | |
244 | |
… | |
… | |
236 | In the future, this setting might control other things, such as |
252 | In the future, this setting might control other things, such as |
237 | converting strings that look like integers or floats into integers |
253 | converting strings that look like integers or floats into integers |
238 | or floats internally (there is no difference on the Perl level), |
254 | or floats internally (there is no difference on the Perl level), |
239 | saving space. |
255 | saving space. |
240 | |
256 | |
241 | $json_string = $json->encode ($perl_scalar) |
257 | $json_text = $json->encode ($perl_scalar) |
242 | Converts the given Perl data structure (a simple scalar or a |
258 | Converts the given Perl data structure (a simple scalar or a |
243 | reference to a hash or array) to its JSON representation. Simple |
259 | reference to a hash or array) to its JSON representation. Simple |
244 | scalars will be converted into JSON string or number sequences, |
260 | scalars will be converted into JSON string or number sequences, |
245 | while references to arrays become JSON arrays and references to |
261 | while references to arrays become JSON arrays and references to |
246 | hashes become JSON objects. Undefined Perl values (e.g. "undef") |
262 | hashes become JSON objects. Undefined Perl values (e.g. "undef") |
247 | become JSON "null" values. Neither "true" nor "false" values will be |
263 | become JSON "null" values. Neither "true" nor "false" values will be |
248 | generated. |
264 | generated. |
249 | |
265 | |
250 | $perl_scalar = $json->decode ($json_string) |
266 | $perl_scalar = $json->decode ($json_text) |
251 | 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, |
252 | it, returning the resulting simple scalar or reference. Croaks on |
268 | returning the resulting simple scalar or reference. Croaks on error. |
253 | error. |
|
|
254 | |
269 | |
255 | JSON numbers and strings become simple Perl scalars. JSON arrays |
270 | JSON numbers and strings become simple Perl scalars. JSON arrays |
256 | become Perl arrayrefs and JSON objects become Perl hashrefs. "true" |
271 | become Perl arrayrefs and JSON objects become Perl hashrefs. "true" |
257 | becomes 1, "false" becomes 0 and "null" becomes "undef". |
272 | becomes 1, "false" becomes 0 and "null" becomes "undef". |
258 | |
273 | |
… | |
… | |
386 | |
401 | |
387 | 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 |
388 | magic values will make it croak). |
403 | magic values will make it croak). |
389 | |
404 | |
390 | 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}" |
391 | which is not a valid JSON string. |
406 | which is not a valid JSON text. |
392 | |
407 | |
393 | Unmaintained (maintainer unresponsive for many months, bugs are not |
408 | Unmaintained (maintainer unresponsive for many months, bugs are not |
394 | getting fixed). |
409 | getting fixed). |
395 | |
410 | |
396 | JSON::Syck 0.21 |
411 | JSON::Syck 0.21 |
397 | Very buggy (often crashes). |
412 | Very buggy (often crashes). |
398 | |
413 | |
399 | Very inflexible (no human-readable format supported, format pretty |
414 | Very inflexible (no human-readable format supported, format pretty |
400 | 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 |
401 | 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 |
402 | preferably a way to generate ASCII-only JSON strings). |
417 | preferably a way to generate ASCII-only JSON texts). |
403 | |
418 | |
404 | Completely broken (and confusingly documented) Unicode handling |
419 | Completely broken (and confusingly documented) Unicode handling |
405 | (unicode escapes are not working properly, you need to set |
420 | (unicode escapes are not working properly, you need to set |
406 | ImplicitUnicode to *different* values on en- and decoding to get |
421 | ImplicitUnicode to *different* values on en- and decoding to get |
407 | symmetric behaviour). |
422 | symmetric behaviour). |
… | |
… | |
430 | |
445 | |
431 | Very inflexible. |
446 | Very inflexible. |
432 | |
447 | |
433 | No roundtripping. |
448 | No roundtripping. |
434 | |
449 | |
435 | Does not generate valid JSON (key strings are often unquoted, empty |
450 | Does not generate valid JSON texts (key strings are often unquoted, |
436 | keys result in nothing being output) |
451 | empty keys result in nothing being output) |
437 | |
452 | |
438 | Does not check input for validity. |
453 | Does not check input for validity. |
439 | |
454 | |
440 | SPEED |
455 | SPEED |
441 | 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 |