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

Comparing JSON-XS/XS.pm (file contents):
Revision 1.11 by root, Fri Mar 23 17:48:59 2007 UTC vs.
Revision 1.12 by root, Fri Mar 23 18:33:50 2007 UTC

… …
3JSON::XS - JSON serialising/deserialising, done correctly and fast 3JSON::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
11This module converts Perl data structures to JSON and vice versa. Its 22This module converts Perl data structures to JSON and vice versa. Its
12primary goal is to be I<correct> and its secondary goal is to be 23primary goal is to be I<correct> and its secondary goal is to be
… …
147If C<$enable> is false, then the C<encode> method will return the JSON 158If C<$enable> is false, then the C<encode> method will return the JSON
148string as a (non-encoded) unicode string, while C<decode> expects thus a 159string as a (non-encoded) unicode string, while C<decode> expects thus a
149unicode string. Any decoding or encoding (e.g. to UTF-8 or UTF-16) needs 160unicode string. Any decoding or encoding (e.g. to UTF-8 or UTF-16) needs
150to be done yourself, e.g. using the Encode module. 161to be done yourself, e.g. using the Encode module.
151 162
163Example, output UTF-16-encoded JSON:
164
152=item $json = $json->pretty ([$enable]) 165=item $json = $json->pretty ([$enable])
153 166
154This enables (or disables) all of the C<indent>, C<space_before> and 167This enables (or disables) all of the C<indent>, C<space_before> and
155C<space_after> (and in the future possibly more) flags in one call to 168C<space_after> (and in the future possibly more) flags in one call to
156generate the most readable (or most compact) form possible. 169generate the most readable (or most compact) form possible.
170
171Example, 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" : [
… …
184space at those places. 199space at those places.
185 200
186This setting has no effect when decoding JSON strings. You will also most 201This setting has no effect when decoding JSON strings. You will also most
187likely combine this setting with C<space_after>. 202likely combine this setting with C<space_after>.
188 203
204Example, 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
191If C<$enable> is true (or missing), then the C<encode> method will add an extra 210If C<$enable> is true (or missing), then the C<encode> method will add an extra
192optional space after the C<:> separating keys from values in JSON objects 211optional space after the C<:> separating keys from values in JSON objects
193and extra whitespace after the C<,> separating key-value pairs and array 212and extra whitespace after the C<,> separating key-value pairs and array
… …
196If C<$enable> is false, then the C<encode> method will not add any extra 215If C<$enable> is false, then the C<encode> method will not add any extra
197space at those places. 216space at those places.
198 217
199This setting has no effect when decoding JSON strings. 218This setting has no effect when decoding JSON strings.
200 219
220Example, 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
203If C<$enable> is true (or missing), then the C<encode> method will output JSON objects 226If C<$enable> is true (or missing), then the C<encode> method will output JSON objects
204by sorting their keys. This is adding a comparatively high overhead. 227by sorting their keys. This is adding a comparatively high overhead.
205 228
… …
223 246
224If C<$enable> is false, then the C<encode> method will croak if it isn't 247If C<$enable> is false, then the C<encode> method will croak if it isn't
225passed an arrayref or hashref, as JSON strings must either be an object 248passed an arrayref or hashref, as JSON strings must either be an object
226or array. Likewise, C<decode> will croak if given something that is not a 249or array. Likewise, C<decode> will croak if given something that is not a
227JSON object or array. 250JSON object or array.
251
252Example, encode a Perl scalar as JSON value with enabled C<allow_nonref>,
253resulting 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
231Perl usually over-allocates memory a bit when allocating space for 260Perl usually over-allocates memory a bit when allocating space for
232strings. This flag optionally resizes strings generated by either 261strings. This flag optionally resizes strings generated by either
… …
512 -----------+------------+------------+ 541 -----------+------------+------------+
513 542
514Again, JSON::XS leads by far in the encoding case, while still beating 543Again, JSON::XS leads by far in the encoding case, while still beating
515every other module in the decoding case. 544every other module in the decoding case.
516 545
517Last 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
522JSON::XS does not impose any limits on the size of JSON texts or Perl 548JSON::XS does not impose any limits on the size of JSON texts or Perl
523values they represent - if your machine cna handle it, JSON::XS will 549values they represent - if your machine can handle it, JSON::XS will
524encode or decode it. Future versions might optionally impose structure 550encode or decode it. Future versions might optionally impose structure
525depth and memory use resource limits. 551depth and memory use resource limits.
526 552
527=head1 BUGS 553=head1 BUGS
528 554

Diff Legend

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