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.12 by root, Fri Mar 23 18:33:50 2007 UTC vs.
Revision 1.144 by root, Mon Oct 28 23:19:54 2013 UTC

1=head1 NAME 1=head1 NAME
2 2
3JSON::XS - JSON serialising/deserialising, done correctly and fast 3JSON::XS - JSON serialising/deserialising, done correctly and fast
4 4
5=encoding utf-8
6
7JSON::XS - 正しくて高速な JSON シリアライザ/デシリアライザ
8 (http://fleur.hio.jp/perldoc/mix/lib/JSON/XS.html)
9
5=head1 SYNOPSIS 10=head1 SYNOPSIS
6 11
7 use JSON::XS; 12 use JSON::XS;
8 13
9 # exported functions, croak on error 14 # exported functions, they croak on error
15 # and expect/generate UTF-8
10 16
11 $utf8_encoded_json_text = to_json $perl_hash_or_arrayref; 17 $utf8_encoded_json_text = encode_json $perl_hash_or_arrayref;
12 $perl_hash_or_arrayref = from_json $utf8_encoded_json_text; 18 $perl_hash_or_arrayref = decode_json $utf8_encoded_json_text;
13 19
14 # oo-interface 20 # OO-interface
15 21
16 $coder = JSON::XS->new->ascii->pretty->allow_nonref; 22 $coder = JSON::XS->new->ascii->pretty->allow_nonref;
17 $pretty_printed_unencoded = $coder->encode ($perl_scalar); 23 $pretty_printed_unencoded = $coder->encode ($perl_scalar);
18 $perl_scalar = $coder->decode ($unicode_json_text); 24 $perl_scalar = $coder->decode ($unicode_json_text);
19 25
26 # Note that JSON version 2.0 and above will automatically use JSON::XS
27 # if available, at virtually no speed overhead either, so you should
28 # be able to just:
29
30 use JSON;
31
32 # and do the same things, except that you have a pure-perl fallback now.
33
20=head1 DESCRIPTION 34=head1 DESCRIPTION
21 35
22This module converts Perl data structures to JSON and vice versa. Its 36This module converts Perl data structures to JSON and vice versa. Its
23primary goal is to be I<correct> and its secondary goal is to be 37primary goal is to be I<correct> and its secondary goal is to be
24I<fast>. To reach the latter goal it was written in C. 38I<fast>. To reach the latter goal it was written in C.
39
40Beginning with version 2.0 of the JSON module, when both JSON and
41JSON::XS are installed, then JSON will fall back on JSON::XS (this can be
42overridden) with no overhead due to emulation (by inheriting constructor
43and methods). If JSON::XS is not available, it will fall back to the
44compatible JSON::PP module as backend, so using JSON instead of JSON::XS
45gives you a portable JSON API that can be fast when you need and doesn't
46require a C compiler when that is a problem.
25 47
26As this is the n-th-something JSON module on CPAN, what was the reason 48As this is the n-th-something JSON module on CPAN, what was the reason
27to write yet another JSON module? While it seems there are many JSON 49to write yet another JSON module? While it seems there are many JSON
28modules, none of them correctly handle all corner cases, and in most cases 50modules, none of them correctly handle all corner cases, and in most cases
29their maintainers are unresponsive, gone missing, or not listening to bug 51their maintainers are unresponsive, gone missing, or not listening to bug
30reports for other reasons. 52reports for other reasons.
31 53
32See COMPARISON, below, for a comparison to some other JSON modules.
33
34See MAPPING, below, on how JSON::XS maps perl values to JSON values and 54See MAPPING, below, on how JSON::XS maps perl values to JSON values and
35vice versa. 55vice versa.
36 56
37=head2 FEATURES 57=head2 FEATURES
38 58
39=over 4 59=over 4
40 60
41=item * correct handling of unicode issues 61=item * correct Unicode handling
42 62
43This module knows how to handle Unicode, and even documents how and when 63This module knows how to handle Unicode, documents how and when it does
44it does so. 64so, and even documents what "correct" means.
45 65
46=item * round-trip integrity 66=item * round-trip integrity
47 67
48When you serialise a perl data structure using only datatypes supported 68When you serialise a perl data structure using only data types supported
49by JSON, the deserialised data structure is identical on the Perl level. 69by JSON and Perl, the deserialised data structure is identical on the Perl
50(e.g. the string "2.0" doesn't suddenly become "2"). 70level. (e.g. the string "2.0" doesn't suddenly become "2" just because
71it looks like a number). There I<are> minor exceptions to this, read the
72MAPPING section below to learn about those.
51 73
52=item * strict checking of JSON correctness 74=item * strict checking of JSON correctness
53 75
54There is no guessing, no generating of illegal JSON strings by default, 76There is no guessing, no generating of illegal JSON texts by default,
55and only JSON is accepted as input by default (the latter is a security 77and only JSON is accepted as input by default (the latter is a security
56feature). 78feature).
57 79
58=item * fast 80=item * fast
59 81
60Compared to other JSON modules, this module compares favourably in terms 82Compared to other JSON modules and other serialisers such as Storable,
61of speed, too. 83this module usually compares favourably in terms of speed, too.
62 84
63=item * simple to use 85=item * simple to use
64 86
65This module has both a simple functional interface as well as an OO 87This module has both a simple functional interface as well as an object
66interface. 88oriented interface.
67 89
68=item * reasonably versatile output formats 90=item * reasonably versatile output formats
69 91
70You can choose between the most compact guarenteed single-line format 92You can choose between the most compact guaranteed-single-line format
71possible (nice for simple line-based protocols), a pure-ascii format (for 93possible (nice for simple line-based protocols), a pure-ASCII format
72when your transport is not 8-bit clean), or a pretty-printed format (for 94(for when your transport is not 8-bit clean, still supports the whole
73when you want to read that stuff). Or you can combine those features in 95Unicode range), or a pretty-printed format (for when you want to read that
74whatever way you like. 96stuff). Or you can combine those features in whatever way you like.
75 97
76=back 98=back
77 99
78=cut 100=cut
79 101
80package JSON::XS; 102package JSON::XS;
81 103
82BEGIN { 104use common::sense;
105
83 $VERSION = '0.3'; 106our $VERSION = 2.34;
84 @ISA = qw(Exporter); 107our @ISA = qw(Exporter);
85 108
86 @EXPORT = qw(to_json from_json); 109our @EXPORT = qw(encode_json decode_json);
87 require Exporter;
88 110
89 require XSLoader; 111use Exporter;
90 XSLoader::load JSON::XS::, $VERSION; 112use XSLoader;
91} 113
114use Types::Serialiser ();
92 115
93=head1 FUNCTIONAL INTERFACE 116=head1 FUNCTIONAL INTERFACE
94 117
95The following convinience methods are provided by this module. They are 118The following convenience methods are provided by this module. They are
96exported by default: 119exported by default:
97 120
98=over 4 121=over 4
99 122
100=item $json_string = to_json $perl_scalar 123=item $json_text = encode_json $perl_scalar
101 124
102Converts the given Perl data structure (a simple scalar or a reference to 125Converts the given Perl data structure to a UTF-8 encoded, binary string
103a hash or array) to a UTF-8 encoded, binary string (that is, the string contains 126(that is, the string contains octets only). Croaks on error.
104octets only). Croaks on error.
105 127
106This function call is functionally identical to C<< JSON::XS->new->utf8->encode ($perl_scalar) >>. 128This function call is functionally identical to:
107 129
130 $json_text = JSON::XS->new->utf8->encode ($perl_scalar)
131
132Except being faster.
133
108=item $perl_scalar = from_json $json_string 134=item $perl_scalar = decode_json $json_text
109 135
110The opposite of C<to_json>: expects an UTF-8 (binary) string and tries to 136The opposite of C<encode_json>: expects an UTF-8 (binary) string and tries
111parse that as an UTF-8 encoded JSON string, returning the resulting simple 137to parse that as an UTF-8 encoded JSON text, returning the resulting
112scalar or reference. Croaks on error. 138reference. Croaks on error.
113 139
114This function call is functionally identical to C<< JSON::XS->new->utf8->decode ($json_string) >>. 140This function call is functionally identical to:
141
142 $perl_scalar = JSON::XS->new->utf8->decode ($json_text)
143
144Except being faster.
115 145
116=back 146=back
147
148
149=head1 A FEW NOTES ON UNICODE AND PERL
150
151Since this often leads to confusion, here are a few very clear words on
152how Unicode works in Perl, modulo bugs.
153
154=over 4
155
156=item 1. Perl strings can store characters with ordinal values > 255.
157
158This enables you to store Unicode characters as single characters in a
159Perl string - very natural.
160
161=item 2. Perl does I<not> associate an encoding with your strings.
162
163... until you force it to, e.g. when matching it against a regex, or
164printing the scalar to a file, in which case Perl either interprets your
165string as locale-encoded text, octets/binary, or as Unicode, depending
166on various settings. In no case is an encoding stored together with your
167data, it is I<use> that decides encoding, not any magical meta data.
168
169=item 3. The internal utf-8 flag has no meaning with regards to the
170encoding of your string.
171
172Just ignore that flag unless you debug a Perl bug, a module written in
173XS or want to dive into the internals of perl. Otherwise it will only
174confuse you, as, despite the name, it says nothing about how your string
175is encoded. You can have Unicode strings with that flag set, with that
176flag clear, and you can have binary data with that flag set and that flag
177clear. Other possibilities exist, too.
178
179If you didn't know about that flag, just the better, pretend it doesn't
180exist.
181
182=item 4. A "Unicode String" is simply a string where each character can be
183validly interpreted as a Unicode code point.
184
185If you have UTF-8 encoded data, it is no longer a Unicode string, but a
186Unicode string encoded in UTF-8, giving you a binary string.
187
188=item 5. A string containing "high" (> 255) character values is I<not> a UTF-8 string.
189
190It's a fact. Learn to live with it.
191
192=back
193
194I hope this helps :)
195
117 196
118=head1 OBJECT-ORIENTED INTERFACE 197=head1 OBJECT-ORIENTED INTERFACE
119 198
120The object oriented interface lets you configure your own encoding or 199The object oriented interface lets you configure your own encoding or
121decoding style, within the limits of supported formats. 200decoding style, within the limits of supported formats.
128strings. All boolean flags described below are by default I<disabled>. 207strings. All boolean flags described below are by default I<disabled>.
129 208
130The mutators for flags all return the JSON object again and thus calls can 209The mutators for flags all return the JSON object again and thus calls can
131be chained: 210be chained:
132 211
133 my $json = JSON::XS->new->utf8(1)->space_after(1)->encode ({a => [1,2]}) 212 my $json = JSON::XS->new->utf8->space_after->encode ({a => [1,2]})
134 => {"a": [1, 2]} 213 => {"a": [1, 2]}
135 214
136=item $json = $json->ascii ([$enable]) 215=item $json = $json->ascii ([$enable])
137 216
217=item $enabled = $json->get_ascii
218
138If C<$enable> is true (or missing), then the C<encode> method will 219If C<$enable> is true (or missing), then the C<encode> method will not
139not generate characters outside the code range C<0..127>. Any unicode 220generate characters outside the code range C<0..127> (which is ASCII). Any
140characters outside that range will be escaped using either a single 221Unicode characters outside that range will be escaped using either a
141\uXXXX (BMP characters) or a double \uHHHH\uLLLLL escape sequence, as per 222single \uXXXX (BMP characters) or a double \uHHHH\uLLLLL escape sequence,
142RFC4627. 223as per RFC4627. The resulting encoded JSON text can be treated as a native
224Unicode string, an ascii-encoded, latin1-encoded or UTF-8 encoded string,
225or any other superset of ASCII.
143 226
144If C<$enable> is false, then the C<encode> method will not escape Unicode 227If C<$enable> is false, then the C<encode> method will not escape Unicode
145characters unless necessary. 228characters unless required by the JSON syntax or other flags. This results
229in a faster and more compact format.
146 230
231See also the section I<ENCODING/CODESET FLAG NOTES> later in this
232document.
233
234The main use for this flag is to produce JSON texts that can be
235transmitted over a 7-bit channel, as the encoded JSON texts will not
236contain any 8 bit characters.
237
147 JSON::XS->new->ascii (1)->encode (chr 0x10401) 238 JSON::XS->new->ascii (1)->encode ([chr 0x10401])
148 => \ud801\udc01 239 => ["\ud801\udc01"]
240
241=item $json = $json->latin1 ([$enable])
242
243=item $enabled = $json->get_latin1
244
245If C<$enable> is true (or missing), then the C<encode> method will encode
246the resulting JSON text as latin1 (or iso-8859-1), escaping any characters
247outside the code range C<0..255>. The resulting string can be treated as a
248latin1-encoded JSON text or a native Unicode string. The C<decode> method
249will not be affected in any way by this flag, as C<decode> by default
250expects Unicode, which is a strict superset of latin1.
251
252If C<$enable> is false, then the C<encode> method will not escape Unicode
253characters unless required by the JSON syntax or other flags.
254
255See also the section I<ENCODING/CODESET FLAG NOTES> later in this
256document.
257
258The main use for this flag is efficiently encoding binary data as JSON
259text, as most octets will not be escaped, resulting in a smaller encoded
260size. The disadvantage is that the resulting JSON text is encoded
261in latin1 (and must correctly be treated as such when storing and
262transferring), a rare encoding for JSON. It is therefore most useful when
263you want to store data structures known to contain binary data efficiently
264in files or databases, not when talking to other JSON encoders/decoders.
265
266 JSON::XS->new->latin1->encode (["\x{89}\x{abc}"]
267 => ["\x{89}\\u0abc"] # (perl syntax, U+abc escaped, U+89 not)
149 268
150=item $json = $json->utf8 ([$enable]) 269=item $json = $json->utf8 ([$enable])
151 270
271=item $enabled = $json->get_utf8
272
152If C<$enable> is true (or missing), then the C<encode> method will encode 273If C<$enable> is true (or missing), then the C<encode> method will encode
153the JSON string into UTF-8, as required by many protocols, while the 274the JSON result into UTF-8, as required by many protocols, while the
154C<decode> method expects to be handled an UTF-8-encoded string. Please 275C<decode> method expects to be handled an UTF-8-encoded string. Please
155note that UTF-8-encoded strings do not contain any characters outside the 276note that UTF-8-encoded strings do not contain any characters outside the
156range C<0..255>, they are thus useful for bytewise/binary I/O. 277range C<0..255>, they are thus useful for bytewise/binary I/O. In future
278versions, enabling this option might enable autodetection of the UTF-16
279and UTF-32 encoding families, as described in RFC4627.
157 280
158If C<$enable> is false, then the C<encode> method will return the JSON 281If C<$enable> is false, then the C<encode> method will return the JSON
159string as a (non-encoded) unicode string, while C<decode> expects thus a 282string as a (non-encoded) Unicode string, while C<decode> expects thus a
160unicode string. Any decoding or encoding (e.g. to UTF-8 or UTF-16) needs 283Unicode string. Any decoding or encoding (e.g. to UTF-8 or UTF-16) needs
161to be done yourself, e.g. using the Encode module. 284to be done yourself, e.g. using the Encode module.
162 285
286See also the section I<ENCODING/CODESET FLAG NOTES> later in this
287document.
288
163Example, output UTF-16-encoded JSON: 289Example, output UTF-16BE-encoded JSON:
290
291 use Encode;
292 $jsontext = encode "UTF-16BE", JSON::XS->new->encode ($object);
293
294Example, decode UTF-32LE-encoded JSON:
295
296 use Encode;
297 $object = JSON::XS->new->decode (decode "UTF-32LE", $jsontext);
164 298
165=item $json = $json->pretty ([$enable]) 299=item $json = $json->pretty ([$enable])
166 300
167This enables (or disables) all of the C<indent>, C<space_before> and 301This enables (or disables) all of the C<indent>, C<space_before> and
168C<space_after> (and in the future possibly more) flags in one call to 302C<space_after> (and in the future possibly more) flags in one call to
179 ] 313 ]
180 } 314 }
181 315
182=item $json = $json->indent ([$enable]) 316=item $json = $json->indent ([$enable])
183 317
318=item $enabled = $json->get_indent
319
184If C<$enable> is true (or missing), then the C<encode> method will use a multiline 320If C<$enable> is true (or missing), then the C<encode> method will use a multiline
185format as output, putting every array member or object/hash key-value pair 321format as output, putting every array member or object/hash key-value pair
186into its own line, identing them properly. 322into its own line, indenting them properly.
187 323
188If C<$enable> is false, no newlines or indenting will be produced, and the 324If C<$enable> is false, no newlines or indenting will be produced, and the
189resulting JSON strings is guarenteed not to contain any C<newlines>. 325resulting JSON text is guaranteed not to contain any C<newlines>.
190 326
191This setting has no effect when decoding JSON strings. 327This setting has no effect when decoding JSON texts.
192 328
193=item $json = $json->space_before ([$enable]) 329=item $json = $json->space_before ([$enable])
330
331=item $enabled = $json->get_space_before
194 332
195If C<$enable> is true (or missing), then the C<encode> method will add an extra 333If C<$enable> is true (or missing), then the C<encode> method will add an extra
196optional space before the C<:> separating keys from values in JSON objects. 334optional space before the C<:> separating keys from values in JSON objects.
197 335
198If C<$enable> is false, then the C<encode> method will not add any extra 336If C<$enable> is false, then the C<encode> method will not add any extra
199space at those places. 337space at those places.
200 338
201This setting has no effect when decoding JSON strings. You will also most 339This setting has no effect when decoding JSON texts. You will also
202likely combine this setting with C<space_after>. 340most likely combine this setting with C<space_after>.
203 341
204Example, space_before enabled, space_after and indent disabled: 342Example, space_before enabled, space_after and indent disabled:
205 343
206 {"key" :"value"} 344 {"key" :"value"}
207 345
208=item $json = $json->space_after ([$enable]) 346=item $json = $json->space_after ([$enable])
347
348=item $enabled = $json->get_space_after
209 349
210If C<$enable> is true (or missing), then the C<encode> method will add an extra 350If C<$enable> is true (or missing), then the C<encode> method will add an extra
211optional space after the C<:> separating keys from values in JSON objects 351optional space after the C<:> separating keys from values in JSON objects
212and extra whitespace after the C<,> separating key-value pairs and array 352and extra whitespace after the C<,> separating key-value pairs and array
213members. 353members.
214 354
215If C<$enable> is false, then the C<encode> method will not add any extra 355If C<$enable> is false, then the C<encode> method will not add any extra
216space at those places. 356space at those places.
217 357
218This setting has no effect when decoding JSON strings. 358This setting has no effect when decoding JSON texts.
219 359
220Example, space_before and indent disabled, space_after enabled: 360Example, space_before and indent disabled, space_after enabled:
221 361
222 {"key": "value"} 362 {"key": "value"}
223 363
364=item $json = $json->relaxed ([$enable])
365
366=item $enabled = $json->get_relaxed
367
368If C<$enable> is true (or missing), then C<decode> will accept some
369extensions to normal JSON syntax (see below). C<encode> will not be
370affected in anyway. I<Be aware that this option makes you accept invalid
371JSON texts as if they were valid!>. I suggest only to use this option to
372parse application-specific files written by humans (configuration files,
373resource files etc.)
374
375If C<$enable> is false (the default), then C<decode> will only accept
376valid JSON texts.
377
378Currently accepted extensions are:
379
380=over 4
381
382=item * list items can have an end-comma
383
384JSON I<separates> array elements and key-value pairs with commas. This
385can be annoying if you write JSON texts manually and want to be able to
386quickly append elements, so this extension accepts comma at the end of
387such items not just between them:
388
389 [
390 1,
391 2, <- this comma not normally allowed
392 ]
393 {
394 "k1": "v1",
395 "k2": "v2", <- this comma not normally allowed
396 }
397
398=item * shell-style '#'-comments
399
400Whenever JSON allows whitespace, shell-style comments are additionally
401allowed. They are terminated by the first carriage-return or line-feed
402character, after which more white-space and comments are allowed.
403
404 [
405 1, # this comment not allowed in JSON
406 # neither this one...
407 ]
408
409=back
410
224=item $json = $json->canonical ([$enable]) 411=item $json = $json->canonical ([$enable])
412
413=item $enabled = $json->get_canonical
225 414
226If C<$enable> is true (or missing), then the C<encode> method will output JSON objects 415If C<$enable> is true (or missing), then the C<encode> method will output JSON objects
227by sorting their keys. This is adding a comparatively high overhead. 416by sorting their keys. This is adding a comparatively high overhead.
228 417
229If C<$enable> is false, then the C<encode> method will output key-value 418If C<$enable> is false, then the C<encode> method will output key-value
230pairs in the order Perl stores them (which will likely change between runs 419pairs in the order Perl stores them (which will likely change between runs
231of the same script). 420of the same script, and can change even within the same run from 5.18
421onwards).
232 422
233This option is useful if you want the same data structure to be encoded as 423This option is useful if you want the same data structure to be encoded as
234the same JSON string (given the same overall settings). If it is disabled, 424the same JSON text (given the same overall settings). If it is disabled,
235the same hash migh be encoded differently even if contains the same data, 425the same hash might be encoded differently even if contains the same data,
236as key-value pairs have no inherent ordering in Perl. 426as key-value pairs have no inherent ordering in Perl.
237 427
238This setting has no effect when decoding JSON strings. 428This setting has no effect when decoding JSON texts.
429
430This setting has currently no effect on tied hashes.
239 431
240=item $json = $json->allow_nonref ([$enable]) 432=item $json = $json->allow_nonref ([$enable])
433
434=item $enabled = $json->get_allow_nonref
241 435
242If C<$enable> is true (or missing), then the C<encode> method can convert a 436If C<$enable> is true (or missing), then the C<encode> method can convert a
243non-reference into its corresponding string, number or null JSON value, 437non-reference into its corresponding string, number or null JSON value,
244which is an extension to RFC4627. Likewise, C<decode> will accept those JSON 438which is an extension to RFC4627. Likewise, C<decode> will accept those JSON
245values instead of croaking. 439values instead of croaking.
246 440
247If C<$enable> is false, then the C<encode> method will croak if it isn't 441If C<$enable> is false, then the C<encode> method will croak if it isn't
248passed an arrayref or hashref, as JSON strings must either be an object 442passed an arrayref or hashref, as JSON texts must either be an object
249or array. Likewise, C<decode> will croak if given something that is not a 443or array. Likewise, C<decode> will croak if given something that is not a
250JSON object or array. 444JSON object or array.
251 445
252Example, encode a Perl scalar as JSON value with enabled C<allow_nonref>, 446Example, encode a Perl scalar as JSON value with enabled C<allow_nonref>,
253resulting in an invalid JSON text: 447resulting in an invalid JSON text:
254 448
255 JSON::XS->new->allow_nonref->encode ("Hello, World!") 449 JSON::XS->new->allow_nonref->encode ("Hello, World!")
256 => "Hello, World!" 450 => "Hello, World!"
257 451
452=item $json = $json->allow_unknown ([$enable])
453
454=item $enabled = $json->get_allow_unknown
455
456If C<$enable> is true (or missing), then C<encode> will I<not> throw an
457exception when it encounters values it cannot represent in JSON (for
458example, filehandles) but instead will encode a JSON C<null> value. Note
459that blessed objects are not included here and are handled separately by
460c<allow_nonref>.
461
462If C<$enable> is false (the default), then C<encode> will throw an
463exception when it encounters anything it cannot encode as JSON.
464
465This option does not affect C<decode> in any way, and it is recommended to
466leave it off unless you know your communications partner.
467
468=item $json = $json->allow_blessed ([$enable])
469
470=item $enabled = $json->get_allow_blessed
471
472If C<$enable> is true (or missing), then the C<encode> method will not
473barf when it encounters a blessed reference. Instead, the value of the
474B<convert_blessed> option will decide whether C<null> (C<convert_blessed>
475disabled or no C<TO_JSON> method found) or a representation of the
476object (C<convert_blessed> enabled and C<TO_JSON> method found) is being
477encoded. Has no effect on C<decode>.
478
479If C<$enable> is false (the default), then C<encode> will throw an
480exception when it encounters a blessed object.
481
482=item $json = $json->convert_blessed ([$enable])
483
484=item $enabled = $json->get_convert_blessed
485
486If C<$enable> is true (or missing), then C<encode>, upon encountering a
487blessed object, will check for the availability of the C<TO_JSON> method
488on the object's class. If found, it will be called in scalar context
489and the resulting scalar will be encoded instead of the object. If no
490C<TO_JSON> method is found, the value of C<allow_blessed> will decide what
491to do.
492
493The C<TO_JSON> method may safely call die if it wants. If C<TO_JSON>
494returns other blessed objects, those will be handled in the same
495way. C<TO_JSON> must take care of not causing an endless recursion cycle
496(== crash) in this case. The name of C<TO_JSON> was chosen because other
497methods called by the Perl core (== not by the user of the object) are
498usually in upper case letters and to avoid collisions with any C<to_json>
499function or method.
500
501This setting does not yet influence C<decode> in any way, but in the
502future, global hooks might get installed that influence C<decode> and are
503enabled by this setting.
504
505If C<$enable> is false, then the C<allow_blessed> setting will decide what
506to do when a blessed object is found.
507
508=item $json = $json->filter_json_object ([$coderef->($hashref)])
509
510When C<$coderef> is specified, it will be called from C<decode> each
511time it decodes a JSON object. The only argument is a reference to the
512newly-created hash. If the code references returns a single scalar (which
513need not be a reference), this value (i.e. a copy of that scalar to avoid
514aliasing) is inserted into the deserialised data structure. If it returns
515an empty list (NOTE: I<not> C<undef>, which is a valid scalar), the
516original deserialised hash will be inserted. This setting can slow down
517decoding considerably.
518
519When C<$coderef> is omitted or undefined, any existing callback will
520be removed and C<decode> will not change the deserialised hash in any
521way.
522
523Example, convert all JSON objects into the integer 5:
524
525 my $js = JSON::XS->new->filter_json_object (sub { 5 });
526 # returns [5]
527 $js->decode ('[{}]')
528 # throw an exception because allow_nonref is not enabled
529 # so a lone 5 is not allowed.
530 $js->decode ('{"a":1, "b":2}');
531
532=item $json = $json->filter_json_single_key_object ($key [=> $coderef->($value)])
533
534Works remotely similar to C<filter_json_object>, but is only called for
535JSON objects having a single key named C<$key>.
536
537This C<$coderef> is called before the one specified via
538C<filter_json_object>, if any. It gets passed the single value in the JSON
539object. If it returns a single value, it will be inserted into the data
540structure. If it returns nothing (not even C<undef> but the empty list),
541the callback from C<filter_json_object> will be called next, as if no
542single-key callback were specified.
543
544If C<$coderef> is omitted or undefined, the corresponding callback will be
545disabled. There can only ever be one callback for a given key.
546
547As this callback gets called less often then the C<filter_json_object>
548one, decoding speed will not usually suffer as much. Therefore, single-key
549objects make excellent targets to serialise Perl objects into, especially
550as single-key JSON objects are as close to the type-tagged value concept
551as JSON gets (it's basically an ID/VALUE tuple). Of course, JSON does not
552support this in any way, so you need to make sure your data never looks
553like a serialised Perl hash.
554
555Typical names for the single object key are C<__class_whatever__>, or
556C<$__dollars_are_rarely_used__$> or C<}ugly_brace_placement>, or even
557things like C<__class_md5sum(classname)__>, to reduce the risk of clashing
558with real hashes.
559
560Example, decode JSON objects of the form C<< { "__widget__" => <id> } >>
561into the corresponding C<< $WIDGET{<id>} >> object:
562
563 # return whatever is in $WIDGET{5}:
564 JSON::XS
565 ->new
566 ->filter_json_single_key_object (__widget__ => sub {
567 $WIDGET{ $_[0] }
568 })
569 ->decode ('{"__widget__": 5')
570
571 # this can be used with a TO_JSON method in some "widget" class
572 # for serialisation to json:
573 sub WidgetBase::TO_JSON {
574 my ($self) = @_;
575
576 unless ($self->{id}) {
577 $self->{id} = ..get..some..id..;
578 $WIDGET{$self->{id}} = $self;
579 }
580
581 { __widget__ => $self->{id} }
582 }
583
258=item $json = $json->shrink ([$enable]) 584=item $json = $json->shrink ([$enable])
259 585
586=item $enabled = $json->get_shrink
587
260Perl usually over-allocates memory a bit when allocating space for 588Perl usually over-allocates memory a bit when allocating space for
261strings. This flag optionally resizes strings generated by either 589strings. This flag optionally resizes strings generated by either
262C<encode> or C<decode> to their minimum size possible. This can save 590C<encode> or C<decode> to their minimum size possible. This can save
263memory when your JSON strings are either very very long or you have many 591memory when your JSON texts are either very very long or you have many
264short strings. It will also try to downgrade any strings to octet-form 592short strings. It will also try to downgrade any strings to octet-form
265if possible: perl stores strings internally either in an encoding called 593if possible: perl stores strings internally either in an encoding called
266UTF-X or in octet-form. The latter cannot store everything but uses less 594UTF-X or in octet-form. The latter cannot store everything but uses less
267space in general. 595space in general (and some buggy Perl or C code might even rely on that
596internal representation being used).
268 597
598The actual definition of what shrink does might change in future versions,
599but it will always try to save space at the expense of time.
600
269If C<$enable> is true (or missing), the string returned by C<encode> will be shrunk-to-fit, 601If C<$enable> is true (or missing), the string returned by C<encode> will
270while all strings generated by C<decode> will also be shrunk-to-fit. 602be shrunk-to-fit, while all strings generated by C<decode> will also be
603shrunk-to-fit.
271 604
272If C<$enable> is false, then the normal perl allocation algorithms are used. 605If C<$enable> is false, then the normal perl allocation algorithms are used.
273If you work with your data, then this is likely to be faster. 606If you work with your data, then this is likely to be faster.
274 607
275In the future, this setting might control other things, such as converting 608In the future, this setting might control other things, such as converting
276strings that look like integers or floats into integers or floats 609strings that look like integers or floats into integers or floats
277internally (there is no difference on the Perl level), saving space. 610internally (there is no difference on the Perl level), saving space.
278 611
612=item $json = $json->max_depth ([$maximum_nesting_depth])
613
614=item $max_depth = $json->get_max_depth
615
616Sets the maximum nesting level (default C<512>) accepted while encoding
617or decoding. If a higher nesting level is detected in JSON text or a Perl
618data structure, then the encoder and decoder will stop and croak at that
619point.
620
621Nesting level is defined by number of hash- or arrayrefs that the encoder
622needs to traverse to reach a given point or the number of C<{> or C<[>
623characters without their matching closing parenthesis crossed to reach a
624given character in a string.
625
626Setting the maximum depth to one disallows any nesting, so that ensures
627that the object is only a single hash/object or array.
628
629If no argument is given, the highest possible setting will be used, which
630is rarely useful.
631
632Note that nesting is implemented by recursion in C. The default value has
633been chosen to be as large as typical operating systems allow without
634crashing.
635
636See SECURITY CONSIDERATIONS, below, for more info on why this is useful.
637
638=item $json = $json->max_size ([$maximum_string_size])
639
640=item $max_size = $json->get_max_size
641
642Set the maximum length a JSON text may have (in bytes) where decoding is
643being attempted. The default is C<0>, meaning no limit. When C<decode>
644is called on a string that is longer then this many bytes, it will not
645attempt to decode the string but throw an exception. This setting has no
646effect on C<encode> (yet).
647
648If no argument is given, the limit check will be deactivated (same as when
649C<0> is specified).
650
651See SECURITY CONSIDERATIONS, below, for more info on why this is useful.
652
279=item $json_string = $json->encode ($perl_scalar) 653=item $json_text = $json->encode ($perl_scalar)
280 654
281Converts the given Perl data structure (a simple scalar or a reference 655Converts the given Perl value or data structure to its JSON
282to a hash or array) to its JSON representation. Simple scalars will be 656representation. Croaks on error.
283converted into JSON string or number sequences, while references to arrays
284become JSON arrays and references to hashes become JSON objects. Undefined
285Perl values (e.g. C<undef>) become JSON C<null> values. Neither C<true>
286nor C<false> values will be generated.
287 657
288=item $perl_scalar = $json->decode ($json_string) 658=item $perl_scalar = $json->decode ($json_text)
289 659
290The opposite of C<encode>: expects a JSON string and tries to parse it, 660The opposite of C<encode>: expects a JSON text and tries to parse it,
291returning the resulting simple scalar or reference. Croaks on error. 661returning the resulting simple scalar or reference. Croaks on error.
292 662
293JSON numbers and strings become simple Perl scalars. JSON arrays become 663=item ($perl_scalar, $characters) = $json->decode_prefix ($json_text)
294Perl arrayrefs and JSON objects become Perl hashrefs. C<true> becomes 664
295C<1>, C<false> becomes C<0> and C<null> becomes C<undef>. 665This works like the C<decode> method, but instead of raising an exception
666when there is trailing garbage after the first JSON object, it will
667silently stop parsing there and return the number of characters consumed
668so far.
669
670This is useful if your JSON texts are not delimited by an outer protocol
671and you need to know where the JSON text ends.
672
673 JSON::XS->new->decode_prefix ("[1] the tail")
674 => ([], 3)
296 675
297=back 676=back
677
678
679=head1 INCREMENTAL PARSING
680
681In some cases, there is the need for incremental parsing of JSON
682texts. While this module always has to keep both JSON text and resulting
683Perl data structure in memory at one time, it does allow you to parse a
684JSON stream incrementally. It does so by accumulating text until it has
685a full JSON object, which it then can decode. This process is similar to
686using C<decode_prefix> to see if a full JSON object is available, but
687is much more efficient (and can be implemented with a minimum of method
688calls).
689
690JSON::XS will only attempt to parse the JSON text once it is sure it
691has enough text to get a decisive result, using a very simple but
692truly incremental parser. This means that it sometimes won't stop as
693early as the full parser, for example, it doesn't detect mismatched
694parentheses. The only thing it guarantees is that it starts decoding as
695soon as a syntactically valid JSON text has been seen. This means you need
696to set resource limits (e.g. C<max_size>) to ensure the parser will stop
697parsing in the presence if syntax errors.
698
699The following methods implement this incremental parser.
700
701=over 4
702
703=item [void, scalar or list context] = $json->incr_parse ([$string])
704
705This is the central parsing function. It can both append new text and
706extract objects from the stream accumulated so far (both of these
707functions are optional).
708
709If C<$string> is given, then this string is appended to the already
710existing JSON fragment stored in the C<$json> object.
711
712After that, if the function is called in void context, it will simply
713return without doing anything further. This can be used to add more text
714in as many chunks as you want.
715
716If the method is called in scalar context, then it will try to extract
717exactly I<one> JSON object. If that is successful, it will return this
718object, otherwise it will return C<undef>. If there is a parse error,
719this method will croak just as C<decode> would do (one can then use
720C<incr_skip> to skip the erroneous part). This is the most common way of
721using the method.
722
723And finally, in list context, it will try to extract as many objects
724from the stream as it can find and return them, or the empty list
725otherwise. For this to work, there must be no separators between the JSON
726objects or arrays, instead they must be concatenated back-to-back. If
727an error occurs, an exception will be raised as in the scalar context
728case. Note that in this case, any previously-parsed JSON texts will be
729lost.
730
731Example: Parse some JSON arrays/objects in a given string and return
732them.
733
734 my @objs = JSON::XS->new->incr_parse ("[5][7][1,2]");
735
736=item $lvalue_string = $json->incr_text
737
738This method returns the currently stored JSON fragment as an lvalue, that
739is, you can manipulate it. This I<only> works when a preceding call to
740C<incr_parse> in I<scalar context> successfully returned an object. Under
741all other circumstances you must not call this function (I mean it.
742although in simple tests it might actually work, it I<will> fail under
743real world conditions). As a special exception, you can also call this
744method before having parsed anything.
745
746This function is useful in two cases: a) finding the trailing text after a
747JSON object or b) parsing multiple JSON objects separated by non-JSON text
748(such as commas).
749
750=item $json->incr_skip
751
752This will reset the state of the incremental parser and will remove
753the parsed text from the input buffer so far. This is useful after
754C<incr_parse> died, in which case the input buffer and incremental parser
755state is left unchanged, to skip the text parsed so far and to reset the
756parse state.
757
758The difference to C<incr_reset> is that only text until the parse error
759occurred is removed.
760
761=item $json->incr_reset
762
763This completely resets the incremental parser, that is, after this call,
764it will be as if the parser had never parsed anything.
765
766This is useful if you want to repeatedly parse JSON objects and want to
767ignore any trailing data, which means you have to reset the parser after
768each successful decode.
769
770=back
771
772=head2 LIMITATIONS
773
774All options that affect decoding are supported, except
775C<allow_nonref>. The reason for this is that it cannot be made to work
776sensibly: JSON objects and arrays are self-delimited, i.e. you can
777concatenate them back to back and still decode them perfectly. This does
778not hold true for JSON numbers, however.
779
780For example, is the string C<1> a single JSON number, or is it simply the
781start of C<12>? Or is C<12> a single JSON number, or the concatenation
782of C<1> and C<2>? In neither case you can tell, and this is why JSON::XS
783takes the conservative route and disallows this case.
784
785=head2 EXAMPLES
786
787Some examples will make all this clearer. First, a simple example that
788works similarly to C<decode_prefix>: We want to decode the JSON object at
789the start of a string and identify the portion after the JSON object:
790
791 my $text = "[1,2,3] hello";
792
793 my $json = new JSON::XS;
794
795 my $obj = $json->incr_parse ($text)
796 or die "expected JSON object or array at beginning of string";
797
798 my $tail = $json->incr_text;
799 # $tail now contains " hello"
800
801Easy, isn't it?
802
803Now for a more complicated example: Imagine a hypothetical protocol where
804you read some requests from a TCP stream, and each request is a JSON
805array, without any separation between them (in fact, it is often useful to
806use newlines as "separators", as these get interpreted as whitespace at
807the start of the JSON text, which makes it possible to test said protocol
808with C<telnet>...).
809
810Here is how you'd do it (it is trivial to write this in an event-based
811manner):
812
813 my $json = new JSON::XS;
814
815 # read some data from the socket
816 while (sysread $socket, my $buf, 4096) {
817
818 # split and decode as many requests as possible
819 for my $request ($json->incr_parse ($buf)) {
820 # act on the $request
821 }
822 }
823
824Another complicated example: Assume you have a string with JSON objects
825or arrays, all separated by (optional) comma characters (e.g. C<[1],[2],
826[3]>). To parse them, we have to skip the commas between the JSON texts,
827and here is where the lvalue-ness of C<incr_text> comes in useful:
828
829 my $text = "[1],[2], [3]";
830 my $json = new JSON::XS;
831
832 # void context, so no parsing done
833 $json->incr_parse ($text);
834
835 # now extract as many objects as possible. note the
836 # use of scalar context so incr_text can be called.
837 while (my $obj = $json->incr_parse) {
838 # do something with $obj
839
840 # now skip the optional comma
841 $json->incr_text =~ s/^ \s* , //x;
842 }
843
844Now lets go for a very complex example: Assume that you have a gigantic
845JSON array-of-objects, many gigabytes in size, and you want to parse it,
846but you cannot load it into memory fully (this has actually happened in
847the real world :).
848
849Well, you lost, you have to implement your own JSON parser. But JSON::XS
850can still help you: You implement a (very simple) array parser and let
851JSON decode the array elements, which are all full JSON objects on their
852own (this wouldn't work if the array elements could be JSON numbers, for
853example):
854
855 my $json = new JSON::XS;
856
857 # open the monster
858 open my $fh, "<bigfile.json"
859 or die "bigfile: $!";
860
861 # first parse the initial "["
862 for (;;) {
863 sysread $fh, my $buf, 65536
864 or die "read error: $!";
865 $json->incr_parse ($buf); # void context, so no parsing
866
867 # Exit the loop once we found and removed(!) the initial "[".
868 # In essence, we are (ab-)using the $json object as a simple scalar
869 # we append data to.
870 last if $json->incr_text =~ s/^ \s* \[ //x;
871 }
872
873 # now we have the skipped the initial "[", so continue
874 # parsing all the elements.
875 for (;;) {
876 # in this loop we read data until we got a single JSON object
877 for (;;) {
878 if (my $obj = $json->incr_parse) {
879 # do something with $obj
880 last;
881 }
882
883 # add more data
884 sysread $fh, my $buf, 65536
885 or die "read error: $!";
886 $json->incr_parse ($buf); # void context, so no parsing
887 }
888
889 # in this loop we read data until we either found and parsed the
890 # separating "," between elements, or the final "]"
891 for (;;) {
892 # first skip whitespace
893 $json->incr_text =~ s/^\s*//;
894
895 # if we find "]", we are done
896 if ($json->incr_text =~ s/^\]//) {
897 print "finished.\n";
898 exit;
899 }
900
901 # if we find ",", we can continue with the next element
902 if ($json->incr_text =~ s/^,//) {
903 last;
904 }
905
906 # if we find anything else, we have a parse error!
907 if (length $json->incr_text) {
908 die "parse error near ", $json->incr_text;
909 }
910
911 # else add more data
912 sysread $fh, my $buf, 65536
913 or die "read error: $!";
914 $json->incr_parse ($buf); # void context, so no parsing
915 }
916
917This is a complex example, but most of the complexity comes from the fact
918that we are trying to be correct (bear with me if I am wrong, I never ran
919the above example :).
920
921
298 922
299=head1 MAPPING 923=head1 MAPPING
300 924
301This section describes how JSON::XS maps Perl values to JSON values and 925This section describes how JSON::XS maps Perl values to JSON values and
302vice versa. These mappings are designed to "do the right thing" in most 926vice versa. These mappings are designed to "do the right thing" in most
303circumstances automatically, preserving round-tripping characteristics 927circumstances automatically, preserving round-tripping characteristics
304(what you put in comes out as something equivalent). 928(what you put in comes out as something equivalent).
305 929
306For the more enlightened: note that in the following descriptions, 930For the more enlightened: note that in the following descriptions,
307lowercase I<perl> refers to the Perl interpreter, while uppcercase I<Perl> 931lowercase I<perl> refers to the Perl interpreter, while uppercase I<Perl>
308refers to the abstract Perl language itself. 932refers to the abstract Perl language itself.
309 933
934
310=head2 JSON -> PERL 935=head2 JSON -> PERL
311 936
312=over 4 937=over 4
313 938
314=item object 939=item object
315 940
316A JSON object becomes a reference to a hash in Perl. No ordering of object 941A JSON object becomes a reference to a hash in Perl. No ordering of object
317keys is preserved. 942keys is preserved (JSON does not preserve object key ordering itself).
318 943
319=item array 944=item array
320 945
321A JSON array becomes a reference to an array in Perl. 946A JSON array becomes a reference to an array in Perl.
322 947
326are represented by the same codepoints in the Perl string, so no manual 951are represented by the same codepoints in the Perl string, so no manual
327decoding is necessary. 952decoding is necessary.
328 953
329=item number 954=item number
330 955
331A JSON number becomes either an integer or numeric (floating point) 956A JSON number becomes either an integer, numeric (floating point) or
332scalar in perl, depending on its range and any fractional parts. On the 957string scalar in perl, depending on its range and any fractional parts. On
333Perl level, there is no difference between those as Perl handles all the 958the Perl level, there is no difference between those as Perl handles all
334conversion details, but an integer may take slightly less memory and might 959the conversion details, but an integer may take slightly less memory and
335represent more values exactly than (floating point) numbers. 960might represent more values exactly than floating point numbers.
961
962If the number consists of digits only, JSON::XS will try to represent
963it as an integer value. If that fails, it will try to represent it as
964a numeric (floating point) value if that is possible without loss of
965precision. Otherwise it will preserve the number as a string value (in
966which case you lose roundtripping ability, as the JSON number will be
967re-encoded to a JSON string).
968
969Numbers containing a fractional or exponential part will always be
970represented as numeric (floating point) values, possibly at a loss of
971precision (in which case you might lose perfect roundtripping ability, but
972the JSON number will still be re-encoded as a JSON number).
973
974Note that precision is not accuracy - binary floating point values cannot
975represent most decimal fractions exactly, and when converting from and to
976floating point, JSON::XS only guarantees precision up to but not including
977the least significant bit.
336 978
337=item true, false 979=item true, false
338 980
339These JSON atoms become C<0>, C<1>, respectively. Information is lost in 981These JSON atoms become C<Types::Serialiser::true> and
340this process. Future versions might represent those values differently, 982C<Types::Serialiser::false>, respectively. They are overloaded to act
341but they will be guarenteed to act like these integers would normally in 983almost exactly like the numbers C<1> and C<0>. You can check whether
342Perl. 984a scalar is a JSON boolean by using the C<Types::Serialiser::is_bool>
985function (after C<use Types::Serialier>, of course).
343 986
344=item null 987=item null
345 988
346A JSON null atom becomes C<undef> in Perl. 989A JSON null atom becomes C<undef> in Perl.
347 990
348=back 991=back
992
349 993
350=head2 PERL -> JSON 994=head2 PERL -> JSON
351 995
352The mapping from Perl to JSON is slightly more difficult, as Perl is a 996The mapping from Perl to JSON is slightly more difficult, as Perl is a
353truly typeless language, so we can only guess which JSON type is meant by 997truly typeless language, so we can only guess which JSON type is meant by
355 999
356=over 4 1000=over 4
357 1001
358=item hash references 1002=item hash references
359 1003
360Perl hash references become JSON objects. As there is no inherent ordering 1004Perl hash references become JSON objects. As there is no inherent
361in hash keys, they will usually be encoded in a pseudo-random order that 1005ordering in hash keys (or JSON objects), they will usually be encoded
362can change between runs of the same program but stays generally the same 1006in a pseudo-random order. JSON::XS can optionally sort the hash keys
363within the single run of a program. JSON::XS can optionally sort the hash
364keys (determined by the I<canonical> flag), so the same datastructure 1007(determined by the I<canonical> flag), so the same datastructure will
365will serialise to the same JSON text (given same settings and version of 1008serialise to the same JSON text (given same settings and version of
366JSON::XS), but this incurs a runtime overhead. 1009JSON::XS), but this incurs a runtime overhead and is only rarely useful,
1010e.g. when you want to compare some JSON text against another for equality.
367 1011
368=item array references 1012=item array references
369 1013
370Perl array references become JSON arrays. 1014Perl array references become JSON arrays.
371 1015
1016=item other references
1017
1018Other unblessed references are generally not allowed and will cause an
1019exception to be thrown, except for references to the integers C<0> and
1020C<1>, which get turned into C<false> and C<true> atoms in JSON.
1021
1022Since C<JSON::XS> uses the boolean model from L<Types::Serialiser>, you
1023can also C<use Types::Serialiser> and then use C<Types::Serialiser::false>
1024and C<Types::Serialiser::true> to improve readability.
1025
1026 use Types::Serialiser;
1027 encode_json [\0, Types::Serialiser::true] # yields [false,true]
1028
1029=item Types::Serialiser::true, Types::Serialiser::false
1030
1031These special values from the L<Types::Serialiser> module become JSON true
1032and JSON false values, respectively. You can also use C<\1> and C<\0>
1033directly if you want.
1034
372=item blessed objects 1035=item blessed objects
373 1036
374Blessed objects are not allowed. JSON::XS currently tries to encode their 1037Blessed objects are not directly representable in JSON. See the
375underlying representation (hash- or arrayref), but this behaviour might 1038C<allow_blessed> and C<convert_blessed> methods on various options on
376change in future versions. 1039how to deal with this: basically, you can choose between throwing an
1040exception, encoding the reference as if it weren't blessed, or provide
1041your own serialiser method.
377 1042
378=item simple scalars 1043=item simple scalars
379 1044
380Simple Perl scalars (any scalar that is not a reference) are the most 1045Simple Perl scalars (any scalar that is not a reference) are the most
381difficult objects to encode: JSON::XS will encode undefined scalars as 1046difficult objects to encode: JSON::XS will encode undefined scalars as
382JSON null value, scalars that have last been used in a string context 1047JSON C<null> values, scalars that have last been used in a string context
383before encoding as JSON strings and anything else as number value: 1048before encoding as JSON strings, and anything else as number value:
384 1049
385 # dump as number 1050 # dump as number
386 to_json [2] # yields [2] 1051 encode_json [2] # yields [2]
387 to_json [-3.0e17] # yields [-3e+17] 1052 encode_json [-3.0e17] # yields [-3e+17]
388 my $value = 5; to_json [$value] # yields [5] 1053 my $value = 5; encode_json [$value] # yields [5]
389 1054
390 # used as string, so dump as string 1055 # used as string, so dump as string
391 print $value; 1056 print $value;
392 to_json [$value] # yields ["5"] 1057 encode_json [$value] # yields ["5"]
393 1058
394 # undef becomes null 1059 # undef becomes null
395 to_json [undef] # yields [null] 1060 encode_json [undef] # yields [null]
396 1061
397You can force the type to be a string by stringifying it: 1062You can force the type to be a JSON string by stringifying it:
398 1063
399 my $x = 3.1; # some variable containing a number 1064 my $x = 3.1; # some variable containing a number
400 "$x"; # stringified 1065 "$x"; # stringified
401 $x .= ""; # another, more awkward way to stringify 1066 $x .= ""; # another, more awkward way to stringify
402 print $x; # perl does it for you, too, quite often 1067 print $x; # perl does it for you, too, quite often
403 1068
404You can force the type to be a number by numifying it: 1069You can force the type to be a JSON number by numifying it:
405 1070
406 my $x = "3"; # some variable containing a string 1071 my $x = "3"; # some variable containing a string
407 $x += 0; # numify it, ensuring it will be dumped as a number 1072 $x += 0; # numify it, ensuring it will be dumped as a number
408 $x *= 1; # same thing, the choise is yours. 1073 $x *= 1; # same thing, the choice is yours.
409 1074
410You can not currently output JSON booleans or force the type in other, 1075You can not currently force the type in other, less obscure, ways. Tell me
411less obscure, ways. Tell me if you need this capability. 1076if you need this capability (but don't forget to explain why it's needed
1077:).
412 1078
413=item circular data structures 1079Note that numerical precision has the same meaning as under Perl (so
414 1080binary to decimal conversion follows the same rules as in Perl, which
415Those will be encoded until memory or stackspace runs out. 1081can differ to other languages). Also, your perl interpreter might expose
1082extensions to the floating point numbers of your platform, such as
1083infinities or NaN's - these cannot be represented in JSON, and it is an
1084error to pass those in.
416 1085
417=back 1086=back
418 1087
419=head1 COMPARISON
420 1088
421As already mentioned, this module was created because none of the existing 1089=head1 ENCODING/CODESET FLAG NOTES
422JSON modules could be made to work correctly. First I will describe the 1090
423problems (or pleasures) I encountered with various existing JSON modules, 1091The interested reader might have seen a number of flags that signify
424followed by some benchmark values. JSON::XS was designed not to suffer 1092encodings or codesets - C<utf8>, C<latin1> and C<ascii>. There seems to be
425from any of these problems or limitations. 1093some confusion on what these do, so here is a short comparison:
1094
1095C<utf8> controls whether the JSON text created by C<encode> (and expected
1096by C<decode>) is UTF-8 encoded or not, while C<latin1> and C<ascii> only
1097control whether C<encode> escapes character values outside their respective
1098codeset range. Neither of these flags conflict with each other, although
1099some combinations make less sense than others.
1100
1101Care has been taken to make all flags symmetrical with respect to
1102C<encode> and C<decode>, that is, texts encoded with any combination of
1103these flag values will be correctly decoded when the same flags are used
1104- in general, if you use different flag settings while encoding vs. when
1105decoding you likely have a bug somewhere.
1106
1107Below comes a verbose discussion of these flags. Note that a "codeset" is
1108simply an abstract set of character-codepoint pairs, while an encoding
1109takes those codepoint numbers and I<encodes> them, in our case into
1110octets. Unicode is (among other things) a codeset, UTF-8 is an encoding,
1111and ISO-8859-1 (= latin 1) and ASCII are both codesets I<and> encodings at
1112the same time, which can be confusing.
426 1113
427=over 4 1114=over 4
428 1115
429=item JSON 1.07 1116=item C<utf8> flag disabled
430 1117
431Slow (but very portable, as it is written in pure Perl). 1118When C<utf8> is disabled (the default), then C<encode>/C<decode> generate
1119and expect Unicode strings, that is, characters with high ordinal Unicode
1120values (> 255) will be encoded as such characters, and likewise such
1121characters are decoded as-is, no changes to them will be done, except
1122"(re-)interpreting" them as Unicode codepoints or Unicode characters,
1123respectively (to Perl, these are the same thing in strings unless you do
1124funny/weird/dumb stuff).
432 1125
433Undocumented/buggy Unicode handling (how JSON handles unicode values is 1126This is useful when you want to do the encoding yourself (e.g. when you
434undocumented. One can get far by feeding it unicode strings and doing 1127want to have UTF-16 encoded JSON texts) or when some other layer does
435en-/decoding oneself, but unicode escapes are not working properly). 1128the encoding for you (for example, when printing to a terminal using a
1129filehandle that transparently encodes to UTF-8 you certainly do NOT want
1130to UTF-8 encode your data first and have Perl encode it another time).
436 1131
437No roundtripping (strings get clobbered if they look like numbers, e.g. 1132=item C<utf8> flag enabled
438the string C<2.0> will encode to C<2.0> instead of C<"2.0">, and that will
439decode into the number 2.
440 1133
441=item JSON::PC 0.01 1134If the C<utf8>-flag is enabled, C<encode>/C<decode> will encode all
1135characters using the corresponding UTF-8 multi-byte sequence, and will
1136expect your input strings to be encoded as UTF-8, that is, no "character"
1137of the input string must have any value > 255, as UTF-8 does not allow
1138that.
442 1139
443Very fast. 1140The C<utf8> flag therefore switches between two modes: disabled means you
1141will get a Unicode string in Perl, enabled means you get an UTF-8 encoded
1142octet/binary string in Perl.
444 1143
445Undocumented/buggy Unicode handling. 1144=item C<latin1> or C<ascii> flags enabled
446 1145
447No roundtripping. 1146With C<latin1> (or C<ascii>) enabled, C<encode> will escape characters
1147with ordinal values > 255 (> 127 with C<ascii>) and encode the remaining
1148characters as specified by the C<utf8> flag.
448 1149
449Has problems handling many Perl values (e.g. regex results and other magic 1150If C<utf8> is disabled, then the result is also correctly encoded in those
450values will make it croak). 1151character sets (as both are proper subsets of Unicode, meaning that a
1152Unicode string with all character values < 256 is the same thing as a
1153ISO-8859-1 string, and a Unicode string with all character values < 128 is
1154the same thing as an ASCII string in Perl).
451 1155
452Does not even generate valid JSON (C<{1,2}> gets converted to C<{1:2}> 1156If C<utf8> is enabled, you still get a correct UTF-8-encoded string,
453which is not a valid JSON string. 1157regardless of these flags, just some more characters will be escaped using
1158C<\uXXXX> then before.
454 1159
455Unmaintained (maintainer unresponsive for many months, bugs are not 1160Note that ISO-8859-1-I<encoded> strings are not compatible with UTF-8
456getting fixed). 1161encoding, while ASCII-encoded strings are. That is because the ISO-8859-1
1162encoding is NOT a subset of UTF-8 (despite the ISO-8859-1 I<codeset> being
1163a subset of Unicode), while ASCII is.
457 1164
458=item JSON::Syck 0.21 1165Surprisingly, C<decode> will ignore these flags and so treat all input
1166values as governed by the C<utf8> flag. If it is disabled, this allows you
1167to decode ISO-8859-1- and ASCII-encoded strings, as both strict subsets of
1168Unicode. If it is enabled, you can correctly decode UTF-8 encoded strings.
459 1169
460Very buggy (often crashes). 1170So neither C<latin1> nor C<ascii> are incompatible with the C<utf8> flag -
1171they only govern when the JSON output engine escapes a character or not.
461 1172
462Very inflexible (no human-readable format supported, format pretty much 1173The main use for C<latin1> is to relatively efficiently store binary data
463undocumented. I need at least a format for easy reading by humans and a 1174as JSON, at the expense of breaking compatibility with most JSON decoders.
464single-line compact format for use in a protocol, and preferably a way to
465generate ASCII-only JSON strings).
466 1175
467Completely broken (and confusingly documented) Unicode handling (unicode 1176The main use for C<ascii> is to force the output to not contain characters
468escapes are not working properly, you need to set ImplicitUnicode to 1177with values > 127, which means you can interpret the resulting string
469I<different> values on en- and decoding to get symmetric behaviour). 1178as UTF-8, ISO-8859-1, ASCII, KOI8-R or most about any character set and
470 11798-bit-encoding, and still get the same data structure back. This is useful
471No roundtripping (simple cases work, but this depends on wether the scalar 1180when your channel for JSON transfer is not 8-bit clean or the encoding
472value was used in a numeric context or not). 1181might be mangled in between (e.g. in mail), and works because ASCII is a
473 1182proper subset of most 8-bit and multibyte encodings in use in the world.
474Dumping hashes may skip hash values depending on iterator state.
475
476Unmaintained (maintainer unresponsive for many months, bugs are not
477getting fixed).
478
479Does not check input for validity (i.e. will accept non-JSON input and
480return "something" instead of raising an exception. This is a security
481issue: imagine two banks transfering money between each other using
482JSON. One bank might parse a given non-JSON request and deduct money,
483while the other might reject the transaction with a syntax error. While a
484good protocol will at least recover, that is extra unnecessary work and
485the transaction will still not succeed).
486
487=item JSON::DWIW 0.04
488
489Very fast. Very natural. Very nice.
490
491Undocumented unicode handling (but the best of the pack. Unicode escapes
492still don't get parsed properly).
493
494Very inflexible.
495
496No roundtripping.
497
498Does not generate valid JSON (key strings are often unquoted, empty keys
499result in nothing being output)
500
501Does not check input for validity.
502 1183
503=back 1184=back
1185
1186
1187=head2 JSON and ECMAscript
1188
1189JSON syntax is based on how literals are represented in javascript (the
1190not-standardised predecessor of ECMAscript) which is presumably why it is
1191called "JavaScript Object Notation".
1192
1193However, JSON is not a subset (and also not a superset of course) of
1194ECMAscript (the standard) or javascript (whatever browsers actually
1195implement).
1196
1197If you want to use javascript's C<eval> function to "parse" JSON, you
1198might run into parse errors for valid JSON texts, or the resulting data
1199structure might not be queryable:
1200
1201One of the problems is that U+2028 and U+2029 are valid characters inside
1202JSON strings, but are not allowed in ECMAscript string literals, so the
1203following Perl fragment will not output something that can be guaranteed
1204to be parsable by javascript's C<eval>:
1205
1206 use JSON::XS;
1207
1208 print encode_json [chr 0x2028];
1209
1210The right fix for this is to use a proper JSON parser in your javascript
1211programs, and not rely on C<eval> (see for example Douglas Crockford's
1212F<json2.js> parser).
1213
1214If this is not an option, you can, as a stop-gap measure, simply encode to
1215ASCII-only JSON:
1216
1217 use JSON::XS;
1218
1219 print JSON::XS->new->ascii->encode ([chr 0x2028]);
1220
1221Note that this will enlarge the resulting JSON text quite a bit if you
1222have many non-ASCII characters. You might be tempted to run some regexes
1223to only escape U+2028 and U+2029, e.g.:
1224
1225 # DO NOT USE THIS!
1226 my $json = JSON::XS->new->utf8->encode ([chr 0x2028]);
1227 $json =~ s/\xe2\x80\xa8/\\u2028/g; # escape U+2028
1228 $json =~ s/\xe2\x80\xa9/\\u2029/g; # escape U+2029
1229 print $json;
1230
1231Note that I<this is a bad idea>: the above only works for U+2028 and
1232U+2029 and thus only for fully ECMAscript-compliant parsers. Many existing
1233javascript implementations, however, have issues with other characters as
1234well - using C<eval> naively simply I<will> cause problems.
1235
1236Another problem is that some javascript implementations reserve
1237some property names for their own purposes (which probably makes
1238them non-ECMAscript-compliant). For example, Iceweasel reserves the
1239C<__proto__> property name for its own purposes.
1240
1241If that is a problem, you could parse try to filter the resulting JSON
1242output for these property strings, e.g.:
1243
1244 $json =~ s/"__proto__"\s*:/"__proto__renamed":/g;
1245
1246This works because C<__proto__> is not valid outside of strings, so every
1247occurrence of C<"__proto__"\s*:> must be a string used as property name.
1248
1249If you know of other incompatibilities, please let me know.
1250
1251
1252=head2 JSON and YAML
1253
1254You often hear that JSON is a subset of YAML. This is, however, a mass
1255hysteria(*) and very far from the truth (as of the time of this writing),
1256so let me state it clearly: I<in general, there is no way to configure
1257JSON::XS to output a data structure as valid YAML> that works in all
1258cases.
1259
1260If you really must use JSON::XS to generate YAML, you should use this
1261algorithm (subject to change in future versions):
1262
1263 my $to_yaml = JSON::XS->new->utf8->space_after (1);
1264 my $yaml = $to_yaml->encode ($ref) . "\n";
1265
1266This will I<usually> generate JSON texts that also parse as valid
1267YAML. Please note that YAML has hardcoded limits on (simple) object key
1268lengths that JSON doesn't have and also has different and incompatible
1269unicode character escape syntax, so you should make sure that your hash
1270keys are noticeably shorter than the 1024 "stream characters" YAML allows
1271and that you do not have characters with codepoint values outside the
1272Unicode BMP (basic multilingual page). YAML also does not allow C<\/>
1273sequences in strings (which JSON::XS does not I<currently> generate, but
1274other JSON generators might).
1275
1276There might be other incompatibilities that I am not aware of (or the YAML
1277specification has been changed yet again - it does so quite often). In
1278general you should not try to generate YAML with a JSON generator or vice
1279versa, or try to parse JSON with a YAML parser or vice versa: chances are
1280high that you will run into severe interoperability problems when you
1281least expect it.
1282
1283=over 4
1284
1285=item (*)
1286
1287I have been pressured multiple times by Brian Ingerson (one of the
1288authors of the YAML specification) to remove this paragraph, despite him
1289acknowledging that the actual incompatibilities exist. As I was personally
1290bitten by this "JSON is YAML" lie, I refused and said I will continue to
1291educate people about these issues, so others do not run into the same
1292problem again and again. After this, Brian called me a (quote)I<complete
1293and worthless idiot>(unquote).
1294
1295In my opinion, instead of pressuring and insulting people who actually
1296clarify issues with YAML and the wrong statements of some of its
1297proponents, I would kindly suggest reading the JSON spec (which is not
1298that difficult or long) and finally make YAML compatible to it, and
1299educating users about the changes, instead of spreading lies about the
1300real compatibility for many I<years> and trying to silence people who
1301point out that it isn't true.
1302
1303Addendum/2009: the YAML 1.2 spec is still incompatible with JSON, even
1304though the incompatibilities have been documented (and are known to Brian)
1305for many years and the spec makes explicit claims that YAML is a superset
1306of JSON. It would be so easy to fix, but apparently, bullying people and
1307corrupting userdata is so much easier.
1308
1309=back
1310
504 1311
505=head2 SPEED 1312=head2 SPEED
506 1313
507It seems that JSON::XS is surprisingly fast, as shown in the following 1314It seems that JSON::XS is surprisingly fast, as shown in the following
508tables. They have been generated with the help of the C<eg/bench> program 1315tables. They have been generated with the help of the C<eg/bench> program
509in the JSON::XS distribution, to make it easy to compare on your own 1316in the JSON::XS distribution, to make it easy to compare on your own
510system. 1317system.
511 1318
512First is a comparison between various modules using a very simple JSON 1319First comes a comparison between various modules using
1320a very short single-line JSON string (also available at
1321L<http://dist.schmorp.de/misc/json/short.json>).
1322
1323 {"method": "handleMessage", "params": ["user1",
1324 "we were just talking"], "id": null, "array":[1,11,234,-5,1e5,1e7,
1325 1, 0]}
1326
513string, showing the number of encodes/decodes per second (JSON::XS is 1327It shows the number of encodes/decodes per second (JSON::XS uses
514the functional interface, while JSON::XS/2 is the OO interface with 1328the functional interface, while JSON::XS/2 uses the OO interface
515pretty-printing and hashkey sorting enabled). 1329with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables
1330shrink. JSON::DWIW/DS uses the deserialise function, while JSON::DWIW::FJ
1331uses the from_json method). Higher is better:
516 1332
517 module | encode | decode | 1333 module | encode | decode |
518 -----------|------------|------------| 1334 --------------|------------|------------|
519 JSON | 14006 | 6820 | 1335 JSON::DWIW/DS | 86302.551 | 102300.098 |
520 JSON::DWIW | 200937 | 120386 | 1336 JSON::DWIW/FJ | 86302.551 | 75983.768 |
521 JSON::PC | 85065 | 129366 | 1337 JSON::PP | 15827.562 | 6638.658 |
522 JSON::Syck | 59898 | 44232 | 1338 JSON::Syck | 63358.066 | 47662.545 |
523 JSON::XS | 1171478 | 342435 | 1339 JSON::XS | 511500.488 | 511500.488 |
524 JSON::XS/2 | 730760 | 328714 | 1340 JSON::XS/2 | 291271.111 | 388361.481 |
1341 JSON::XS/3 | 361577.931 | 361577.931 |
1342 Storable | 66788.280 | 265462.278 |
525 -----------+------------+------------+ 1343 --------------+------------+------------+
526 1344
527That is, JSON::XS is 6 times faster than than JSON::DWIW and about 80 1345That is, JSON::XS is almost six times faster than JSON::DWIW on encoding,
528times faster than JSON, even with pretty-printing and key sorting. 1346about five times faster on decoding, and over thirty to seventy times
1347faster than JSON's pure perl implementation. It also compares favourably
1348to Storable for small amounts of data.
529 1349
530Using a longer test string (roughly 8KB, generated from Yahoo! Locals 1350Using a longer test string (roughly 18KB, generated from Yahoo! Locals
531search API (http://nanoref.com/yahooapis/mgPdGg): 1351search API (L<http://dist.schmorp.de/misc/json/long.json>).
532 1352
533 module | encode | decode | 1353 module | encode | decode |
534 -----------|------------|------------| 1354 --------------|------------|------------|
535 JSON | 673 | 38 | 1355 JSON::DWIW/DS | 1647.927 | 2673.916 |
536 JSON::DWIW | 5271 | 770 | 1356 JSON::DWIW/FJ | 1630.249 | 2596.128 |
537 JSON::PC | 9901 | 2491 | 1357 JSON::PP | 400.640 | 62.311 |
538 JSON::Syck | 2360 | 786 | 1358 JSON::Syck | 1481.040 | 1524.869 |
539 JSON::XS | 37398 | 3202 | 1359 JSON::XS | 20661.596 | 9541.183 |
540 JSON::XS/2 | 13765 | 3153 | 1360 JSON::XS/2 | 10683.403 | 9416.938 |
1361 JSON::XS/3 | 20661.596 | 9400.054 |
1362 Storable | 19765.806 | 10000.725 |
541 -----------+------------+------------+ 1363 --------------+------------+------------+
542 1364
543Again, JSON::XS leads by far in the encoding case, while still beating 1365Again, JSON::XS leads by far (except for Storable which non-surprisingly
544every other module in the decoding case. 1366decodes a bit faster).
545 1367
546=head1 RESOURCE LIMITS 1368On large strings containing lots of high Unicode characters, some modules
1369(such as JSON::PC) seem to decode faster than JSON::XS, but the result
1370will be broken due to missing (or wrong) Unicode handling. Others refuse
1371to decode or encode properly, so it was impossible to prepare a fair
1372comparison table for that case.
547 1373
548JSON::XS does not impose any limits on the size of JSON texts or Perl 1374
549values they represent - if your machine can handle it, JSON::XS will 1375=head1 SECURITY CONSIDERATIONS
550encode or decode it. Future versions might optionally impose structure 1376
551depth and memory use resource limits. 1377When you are using JSON in a protocol, talking to untrusted potentially
1378hostile creatures requires relatively few measures.
1379
1380First of all, your JSON decoder should be secure, that is, should not have
1381any buffer overflows. Obviously, this module should ensure that and I am
1382trying hard on making that true, but you never know.
1383
1384Second, you need to avoid resource-starving attacks. That means you should
1385limit the size of JSON texts you accept, or make sure then when your
1386resources run out, that's just fine (e.g. by using a separate process that
1387can crash safely). The size of a JSON text in octets or characters is
1388usually a good indication of the size of the resources required to decode
1389it into a Perl structure. While JSON::XS can check the size of the JSON
1390text, it might be too late when you already have it in memory, so you
1391might want to check the size before you accept the string.
1392
1393Third, JSON::XS recurses using the C stack when decoding objects and
1394arrays. The C stack is a limited resource: for instance, on my amd64
1395machine with 8MB of stack size I can decode around 180k nested arrays but
1396only 14k nested JSON objects (due to perl itself recursing deeply on croak
1397to free the temporary). If that is exceeded, the program crashes. To be
1398conservative, the default nesting limit is set to 512. If your process
1399has a smaller stack, you should adjust this setting accordingly with the
1400C<max_depth> method.
1401
1402Something else could bomb you, too, that I forgot to think of. In that
1403case, you get to keep the pieces. I am always open for hints, though...
1404
1405Also keep in mind that JSON::XS might leak contents of your Perl data
1406structures in its error messages, so when you serialise sensitive
1407information you might want to make sure that exceptions thrown by JSON::XS
1408will not end up in front of untrusted eyes.
1409
1410If you are using JSON::XS to return packets to consumption
1411by JavaScript scripts in a browser you should have a look at
1412L<http://blog.archive.jpsykes.com/47/practical-csrf-and-json-security/> to
1413see whether you are vulnerable to some common attack vectors (which really
1414are browser design bugs, but it is still you who will have to deal with
1415it, as major browser developers care only for features, not about getting
1416security right).
1417
1418
1419=head1 INTEROPERABILITY WITH OTHER MODULES
1420
1421C<JSON::XS> uses the L<Types::Serialiser> module to provide boolean
1422constants. That means that the JSON true and false values will be
1423comaptible to true and false values of iother modules that do the same,
1424such as L<JSON::PP> and L<CBOR::XS>.
1425
1426
1427=head1 THREADS
1428
1429This module is I<not> guaranteed to be thread safe and there are no
1430plans to change this until Perl gets thread support (as opposed to the
1431horribly slow so-called "threads" which are simply slow and bloated
1432process simulations - use fork, it's I<much> faster, cheaper, better).
1433
1434(It might actually work, but you have been warned).
1435
1436
1437=head1 THE PERILS OF SETLOCALE
1438
1439Sometimes people avoid the Perl locale support and directly call the
1440system's setlocale function with C<LC_ALL>.
1441
1442This breaks both perl and modules such as JSON::XS, as stringification of
1443numbers no longer works correctly (e.g. C<$x = 0.1; print "$x"+1> might
1444print C<1>, and JSON::XS might output illegal JSON as JSON::XS relies on
1445perl to stringify numbers).
1446
1447The solution is simple: don't call C<setlocale>, or use it for only those
1448categories you need, such as C<LC_MESSAGES> or C<LC_CTYPE>.
1449
1450If you need C<LC_NUMERIC>, you should enable it only around the code that
1451actually needs it (avoiding stringification of numbers), and restore it
1452afterwards.
1453
552 1454
553=head1 BUGS 1455=head1 BUGS
554 1456
555While the goal of this module is to be correct, that unfortunately does 1457While the goal of this module is to be correct, that unfortunately does
556not mean its bug-free, only that I think its design is bug-free. It is 1458not mean it's bug-free, only that I think its design is bug-free. If you
557still very young and not well-tested. If you keep reporting bugs they will 1459keep reporting bugs they will be fixed swiftly, though.
558be fixed swiftly, though. 1460
1461Please refrain from using rt.cpan.org or any other bug reporting
1462service. I put the contact address into my modules for a reason.
559 1463
560=cut 1464=cut
561 1465
5621; 1466BEGIN {
1467 *true = \$Types::Serialiser::true;
1468 *true = \&Types::Serialiser::true;
1469 *false = \$Types::Serialiser::false;
1470 *false = \&Types::Serialiser::false;
1471 *is_bool = \&Types::Serialiser::is_bool;
1472
1473 *JSON::XS::Boolean:: = *Types::Serialiser::Boolean::;
1474}
1475
1476XSLoader::load "JSON::XS", $VERSION;
1477
1478=head1 SEE ALSO
1479
1480The F<json_xs> command line utility for quick experiments.
563 1481
564=head1 AUTHOR 1482=head1 AUTHOR
565 1483
566 Marc Lehmann <schmorp@schmorp.de> 1484 Marc Lehmann <schmorp@schmorp.de>
567 http://home.schmorp.de/ 1485 http://home.schmorp.de/
568 1486
569=cut 1487=cut
570 1488
14891
1490

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines