… | |
… | |
3 | JSON::XS - JSON serialising/deserialising, done correctly and fast |
3 | JSON::XS - JSON serialising/deserialising, done correctly and fast |
4 | |
4 | |
5 | =head1 SYNOPSIS |
5 | =head1 SYNOPSIS |
6 | |
6 | |
7 | use JSON::XS; |
7 | use JSON::XS; |
|
|
8 | |
|
|
9 | # exported functions, croak on error |
|
|
10 | |
|
|
11 | $utf8_encoded_json_text = to_json $perl_hash_or_arrayref; |
|
|
12 | $perl_hash_or_arrayref = from_json $utf8_encoded_json_text; |
|
|
13 | |
|
|
14 | # oo-interface |
|
|
15 | |
|
|
16 | $coder = JSON::XS->new->ascii->pretty->allow_nonref; |
|
|
17 | $pretty_printed_unencoded = $coder->encode ($perl_scalar); |
|
|
18 | $perl_scalar = $coder->decode ($unicode_json_text); |
8 | |
19 | |
9 | =head1 DESCRIPTION |
20 | =head1 DESCRIPTION |
10 | |
21 | |
11 | This module converts Perl data structures to JSON and vice versa. Its |
22 | This module converts Perl data structures to JSON and vice versa. Its |
12 | primary goal is to be I<correct> and its secondary goal is to be |
23 | primary goal is to be I<correct> and its secondary goal is to be |
… | |
… | |
147 | If C<$enable> is false, then the C<encode> method will return the JSON |
158 | If C<$enable> is false, then the C<encode> method will return the JSON |
148 | string as a (non-encoded) unicode string, while C<decode> expects thus a |
159 | string as a (non-encoded) unicode string, while C<decode> expects thus a |
149 | unicode string. Any decoding or encoding (e.g. to UTF-8 or UTF-16) needs |
160 | unicode string. Any decoding or encoding (e.g. to UTF-8 or UTF-16) needs |
150 | to be done yourself, e.g. using the Encode module. |
161 | to be done yourself, e.g. using the Encode module. |
151 | |
162 | |
|
|
163 | Example, output UTF-16-encoded JSON: |
|
|
164 | |
152 | =item $json = $json->pretty ([$enable]) |
165 | =item $json = $json->pretty ([$enable]) |
153 | |
166 | |
154 | This enables (or disables) all of the C<indent>, C<space_before> and |
167 | This enables (or disables) all of the C<indent>, C<space_before> and |
155 | C<space_after> (and in the future possibly more) flags in one call to |
168 | C<space_after> (and in the future possibly more) flags in one call to |
156 | generate the most readable (or most compact) form possible. |
169 | generate the most readable (or most compact) form possible. |
|
|
170 | |
|
|
171 | Example, pretty-print some simple structure: |
157 | |
172 | |
158 | my $json = JSON::XS->new->pretty(1)->encode ({a => [1,2]}) |
173 | my $json = JSON::XS->new->pretty(1)->encode ({a => [1,2]}) |
159 | => |
174 | => |
160 | { |
175 | { |
161 | "a" : [ |
176 | "a" : [ |
… | |
… | |
184 | space at those places. |
199 | space at those places. |
185 | |
200 | |
186 | This setting has no effect when decoding JSON strings. You will also most |
201 | This setting has no effect when decoding JSON strings. You will also most |
187 | likely combine this setting with C<space_after>. |
202 | likely combine this setting with C<space_after>. |
188 | |
203 | |
|
|
204 | Example, space_before enabled, space_after and indent disabled: |
|
|
205 | |
|
|
206 | {"key" :"value"} |
|
|
207 | |
189 | =item $json = $json->space_after ([$enable]) |
208 | =item $json = $json->space_after ([$enable]) |
190 | |
209 | |
191 | If C<$enable> is true (or missing), then the C<encode> method will add an extra |
210 | If C<$enable> is true (or missing), then the C<encode> method will add an extra |
192 | optional space after the C<:> separating keys from values in JSON objects |
211 | optional space after the C<:> separating keys from values in JSON objects |
193 | and extra whitespace after the C<,> separating key-value pairs and array |
212 | and extra whitespace after the C<,> separating key-value pairs and array |
… | |
… | |
196 | If C<$enable> is false, then the C<encode> method will not add any extra |
215 | If C<$enable> is false, then the C<encode> method will not add any extra |
197 | space at those places. |
216 | space at those places. |
198 | |
217 | |
199 | This setting has no effect when decoding JSON strings. |
218 | This setting has no effect when decoding JSON strings. |
200 | |
219 | |
|
|
220 | Example, space_before and indent disabled, space_after enabled: |
|
|
221 | |
|
|
222 | {"key": "value"} |
|
|
223 | |
201 | =item $json = $json->canonical ([$enable]) |
224 | =item $json = $json->canonical ([$enable]) |
202 | |
225 | |
203 | If C<$enable> is true (or missing), then the C<encode> method will output JSON objects |
226 | If C<$enable> is true (or missing), then the C<encode> method will output JSON objects |
204 | by sorting their keys. This is adding a comparatively high overhead. |
227 | by sorting their keys. This is adding a comparatively high overhead. |
205 | |
228 | |
… | |
… | |
223 | |
246 | |
224 | If C<$enable> is false, then the C<encode> method will croak if it isn't |
247 | If C<$enable> is false, then the C<encode> method will croak if it isn't |
225 | passed an arrayref or hashref, as JSON strings must either be an object |
248 | passed an arrayref or hashref, as JSON strings must either be an object |
226 | or array. Likewise, C<decode> will croak if given something that is not a |
249 | or array. Likewise, C<decode> will croak if given something that is not a |
227 | JSON object or array. |
250 | JSON object or array. |
|
|
251 | |
|
|
252 | Example, encode a Perl scalar as JSON value with enabled C<allow_nonref>, |
|
|
253 | resulting in an invalid JSON text: |
|
|
254 | |
|
|
255 | JSON::XS->new->allow_nonref->encode ("Hello, World!") |
|
|
256 | => "Hello, World!" |
228 | |
257 | |
229 | =item $json = $json->shrink ([$enable]) |
258 | =item $json = $json->shrink ([$enable]) |
230 | |
259 | |
231 | Perl usually over-allocates memory a bit when allocating space for |
260 | Perl usually over-allocates memory a bit when allocating space for |
232 | strings. This flag optionally resizes strings generated by either |
261 | strings. This flag optionally resizes strings generated by either |
… | |
… | |
512 | -----------+------------+------------+ |
541 | -----------+------------+------------+ |
513 | |
542 | |
514 | Again, JSON::XS leads by far in the encoding case, while still beating |
543 | Again, JSON::XS leads by far in the encoding case, while still beating |
515 | every other module in the decoding case. |
544 | every other module in the decoding case. |
516 | |
545 | |
517 | Last example is an almost 8MB large hash with many large binary values |
|
|
518 | (PNG files), resulting in a lot of escaping: |
|
|
519 | |
|
|
520 | =head1 RESOURCE LIMITS |
546 | =head1 RESOURCE LIMITS |
521 | |
547 | |
522 | JSON::XS does not impose any limits on the size of JSON texts or Perl |
548 | JSON::XS does not impose any limits on the size of JSON texts or Perl |
523 | values they represent - if your machine cna handle it, JSON::XS will |
549 | values they represent - if your machine can handle it, JSON::XS will |
524 | encode or decode it. Future versions might optionally impose structure |
550 | encode or decode it. Future versions might optionally impose structure |
525 | depth and memory use resource limits. |
551 | depth and memory use resource limits. |
526 | |
552 | |
527 | =head1 BUGS |
553 | =head1 BUGS |
528 | |
554 | |