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.49 by root, Sun Jul 1 14:08:03 2007 UTC vs.
Revision 1.84 by root, Wed Mar 19 02:52:15 2008 UTC

1=encoding utf-8
2
1=head1 NAME 3=head1 NAME
2 4
3JSON::XS - JSON serialising/deserialising, done correctly and fast 5JSON::XS - JSON serialising/deserialising, done correctly and fast
6
7JSON::XS - 正しくて高速な JSON シリアライザ/デシリアライザ
8 (http://fleur.hio.jp/perldoc/mix/lib/JSON/XS.html)
4 9
5=head1 SYNOPSIS 10=head1 SYNOPSIS
6 11
7 use JSON::XS; 12 use JSON::XS;
8 13
9 # exported functions, they croak on error 14 # exported functions, they croak on error
10 # and expect/generate UTF-8 15 # and expect/generate UTF-8
11 16
12 $utf8_encoded_json_text = to_json $perl_hash_or_arrayref; 17 $utf8_encoded_json_text = encode_json $perl_hash_or_arrayref;
13 $perl_hash_or_arrayref = from_json $utf8_encoded_json_text; 18 $perl_hash_or_arrayref = decode_json $utf8_encoded_json_text;
14 19
15 # OO-interface 20 # OO-interface
16 21
17 $coder = JSON::XS->new->ascii->pretty->allow_nonref; 22 $coder = JSON::XS->new->ascii->pretty->allow_nonref;
18 $pretty_printed_unencoded = $coder->encode ($perl_scalar); 23 $pretty_printed_unencoded = $coder->encode ($perl_scalar);
19 $perl_scalar = $coder->decode ($unicode_json_text); 24 $perl_scalar = $coder->decode ($unicode_json_text);
20 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
21=head1 DESCRIPTION 34=head1 DESCRIPTION
22 35
23This module converts Perl data structures to JSON and vice versa. Its 36This module converts Perl data structures to JSON and vice versa. Its
24primary 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
25I<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
42overriden) with no overhead due to emulation (by inheritign 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.
26 47
27As 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
28to 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
29modules, 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
30their maintainers are unresponsive, gone missing, or not listening to bug 51their maintainers are unresponsive, gone missing, or not listening to bug
… …
37 58
38=head2 FEATURES 59=head2 FEATURES
39 60
40=over 4 61=over 4
41 62
42=item * correct unicode handling 63=item * correct Unicode handling
43 64
44This module knows how to handle Unicode, and even documents how and when 65This module knows how to handle Unicode, documents how and when it does
45it does so. 66so, and even documents what "correct" means.
46 67
47=item * round-trip integrity 68=item * round-trip integrity
48 69
49When you serialise a perl data structure using only datatypes supported 70When you serialise a perl data structure using only datatypes supported
50by JSON, the deserialised data structure is identical on the Perl level. 71by JSON, the deserialised data structure is identical on the Perl level.
51(e.g. the string "2.0" doesn't suddenly become "2" just because it looks 72(e.g. the string "2.0" doesn't suddenly become "2" just because it looks
52like a number). 73like a number). There minor I<are> exceptions to this, read the MAPPING
74section below to learn about those.
53 75
54=item * strict checking of JSON correctness 76=item * strict checking of JSON correctness
55 77
56There is no guessing, no generating of illegal JSON texts by default, 78There is no guessing, no generating of illegal JSON texts by default,
57and only JSON is accepted as input by default (the latter is a security 79and only JSON is accepted as input by default (the latter is a security
58feature). 80feature).
59 81
60=item * fast 82=item * fast
61 83
62Compared to other JSON modules, this module compares favourably in terms 84Compared to other JSON modules and other serialisers such as Storable,
63of speed, too. 85this module usually compares favourably in terms of speed, too.
64 86
65=item * simple to use 87=item * simple to use
66 88
67This module has both a simple functional interface as well as an OO 89This module has both a simple functional interface as well as an objetc
68interface. 90oriented interface interface.
69 91
70=item * reasonably versatile output formats 92=item * reasonably versatile output formats
71 93
72You can choose between the most compact guarenteed single-line format 94You can choose between the most compact guaranteed-single-line format
73possible (nice for simple line-based protocols), a pure-ascii format 95possible (nice for simple line-based protocols), a pure-ascii format
74(for when your transport is not 8-bit clean, still supports the whole 96(for when your transport is not 8-bit clean, still supports the whole
75unicode range), or a pretty-printed format (for when you want to read that 97Unicode range), or a pretty-printed format (for when you want to read that
76stuff). Or you can combine those features in whatever way you like. 98stuff). Or you can combine those features in whatever way you like.
77 99
78=back 100=back
79 101
80=cut 102=cut
81 103
82package JSON::XS; 104package JSON::XS;
83 105
84use strict; 106use strict;
85 107
86our $VERSION = '1.4'; 108our $VERSION = '2.01';
87our @ISA = qw(Exporter); 109our @ISA = qw(Exporter);
88 110
89our @EXPORT = qw(to_json from_json); 111our @EXPORT = qw(encode_json decode_json to_json from_json);
112
113sub to_json($) {
114 require Carp;
115 Carp::croak ("JSON::XS::to_json has been renamed to encode_json, either downgrade to pre-2.0 versions of JSON::XS or rename the call");
116}
117
118sub from_json($) {
119 require Carp;
120 Carp::croak ("JSON::XS::from_json has been renamed to decode_json, either downgrade to pre-2.0 versions of JSON::XS or rename the call");
121}
90 122
91use Exporter; 123use Exporter;
92use XSLoader; 124use XSLoader;
93 125
94=head1 FUNCTIONAL INTERFACE 126=head1 FUNCTIONAL INTERFACE
95 127
96The following convinience methods are provided by this module. They are 128The following convenience methods are provided by this module. They are
97exported by default: 129exported by default:
98 130
99=over 4 131=over 4
100 132
101=item $json_text = to_json $perl_scalar 133=item $json_text = encode_json $perl_scalar
102 134
103Converts the given Perl data structure (a simple scalar or a reference to 135Converts the given Perl data structure to a UTF-8 encoded, binary string
104a hash or array) to a UTF-8 encoded, binary string (that is, the string contains 136(that is, the string contains octets only). Croaks on error.
105octets only). Croaks on error.
106 137
107This function call is functionally identical to: 138This function call is functionally identical to:
108 139
109 $json_text = JSON::XS->new->utf8->encode ($perl_scalar) 140 $json_text = JSON::XS->new->utf8->encode ($perl_scalar)
110 141
111except being faster. 142except being faster.
112 143
113=item $perl_scalar = from_json $json_text 144=item $perl_scalar = decode_json $json_text
114 145
115The opposite of C<to_json>: expects an UTF-8 (binary) string and tries to 146The opposite of C<encode_json>: expects an UTF-8 (binary) string and tries
116parse that as an UTF-8 encoded JSON text, returning the resulting simple 147to parse that as an UTF-8 encoded JSON text, returning the resulting
117scalar or reference. Croaks on error. 148reference. Croaks on error.
118 149
119This function call is functionally identical to: 150This function call is functionally identical to:
120 151
121 $perl_scalar = JSON::XS->new->utf8->decode ($json_text) 152 $perl_scalar = JSON::XS->new->utf8->decode ($json_text)
122 153
… …
132Perl. 163Perl.
133 164
134=back 165=back
135 166
136 167
168=head1 A FEW NOTES ON UNICODE AND PERL
169
170Since this often leads to confusion, here are a few very clear words on
171how Unicode works in Perl, modulo bugs.
172
173=over 4
174
175=item 1. Perl strings can store characters with ordinal values > 255.
176
177This enables you to store Unicode characters as single characters in a
178Perl string - very natural.
179
180=item 2. Perl does I<not> associate an encoding with your strings.
181
182... until you force it to, e.g. when matching it against a regex, or
183printing the scalar to a file, in which case Perl either interprets your
184string as locale-encoded text, octets/binary, or as Unicode, depending
185on various settings. In no case is an encoding stored together with your
186data, it is I<use> that decides encoding, not any magical meta data.
187
188=item 3. The internal utf-8 flag has no meaning with regards to the
189encoding of your string.
190
191Just ignore that flag unless you debug a Perl bug, a module written in
192XS or want to dive into the internals of perl. Otherwise it will only
193confuse you, as, despite the name, it says nothing about how your string
194is encoded. You can have Unicode strings with that flag set, with that
195flag clear, and you can have binary data with that flag set and that flag
196clear. Other possibilities exist, too.
197
198If you didn't know about that flag, just the better, pretend it doesn't
199exist.
200
201=item 4. A "Unicode String" is simply a string where each character can be
202validly interpreted as a Unicode codepoint.
203
204If you have UTF-8 encoded data, it is no longer a Unicode string, but a
205Unicode string encoded in UTF-8, giving you a binary string.
206
207=item 5. A string containing "high" (> 255) character values is I<not> a UTF-8 string.
208
209It's a fact. Learn to live with it.
210
211=back
212
213I hope this helps :)
214
215
137=head1 OBJECT-ORIENTED INTERFACE 216=head1 OBJECT-ORIENTED INTERFACE
138 217
139The object oriented interface lets you configure your own encoding or 218The object oriented interface lets you configure your own encoding or
140decoding style, within the limits of supported formats. 219decoding style, within the limits of supported formats.
141 220
… …
152 my $json = JSON::XS->new->utf8->space_after->encode ({a => [1,2]}) 231 my $json = JSON::XS->new->utf8->space_after->encode ({a => [1,2]})
153 => {"a": [1, 2]} 232 => {"a": [1, 2]}
154 233
155=item $json = $json->ascii ([$enable]) 234=item $json = $json->ascii ([$enable])
156 235
236=item $enabled = $json->get_ascii
237
157If C<$enable> is true (or missing), then the C<encode> method will not 238If C<$enable> is true (or missing), then the C<encode> method will not
158generate characters outside the code range C<0..127> (which is ASCII). Any 239generate characters outside the code range C<0..127> (which is ASCII). Any
159unicode characters outside that range will be escaped using either a 240Unicode characters outside that range will be escaped using either a
160single \uXXXX (BMP characters) or a double \uHHHH\uLLLLL escape sequence, 241single \uXXXX (BMP characters) or a double \uHHHH\uLLLLL escape sequence,
161as per RFC4627. The resulting encoded JSON text can be treated as a native 242as per RFC4627. The resulting encoded JSON text can be treated as a native
162unicode string, an ascii-encoded, latin1-encoded or UTF-8 encoded string, 243Unicode string, an ascii-encoded, latin1-encoded or UTF-8 encoded string,
163or any other superset of ASCII. 244or any other superset of ASCII.
164 245
165If C<$enable> is false, then the C<encode> method will not escape Unicode 246If C<$enable> is false, then the C<encode> method will not escape Unicode
166characters unless required by the JSON syntax or other flags. This results 247characters unless required by the JSON syntax or other flags. This results
167in a faster and more compact format. 248in a faster and more compact format.
… …
173 JSON::XS->new->ascii (1)->encode ([chr 0x10401]) 254 JSON::XS->new->ascii (1)->encode ([chr 0x10401])
174 => ["\ud801\udc01"] 255 => ["\ud801\udc01"]
175 256
176=item $json = $json->latin1 ([$enable]) 257=item $json = $json->latin1 ([$enable])
177 258
259=item $enabled = $json->get_latin1
260
178If C<$enable> is true (or missing), then the C<encode> method will encode 261If C<$enable> is true (or missing), then the C<encode> method will encode
179the resulting JSON text as latin1 (or iso-8859-1), escaping any characters 262the resulting JSON text as latin1 (or iso-8859-1), escaping any characters
180outside the code range C<0..255>. The resulting string can be treated as a 263outside the code range C<0..255>. The resulting string can be treated as a
181latin1-encoded JSON text or a native unicode string. The C<decode> method 264latin1-encoded JSON text or a native Unicode string. The C<decode> method
182will not be affected in any way by this flag, as C<decode> by default 265will not be affected in any way by this flag, as C<decode> by default
183expects unicode, which is a strict superset of latin1. 266expects Unicode, which is a strict superset of latin1.
184 267
185If C<$enable> is false, then the C<encode> method will not escape Unicode 268If C<$enable> is false, then the C<encode> method will not escape Unicode
186characters unless required by the JSON syntax or other flags. 269characters unless required by the JSON syntax or other flags.
187 270
188The main use for this flag is efficiently encoding binary data as JSON 271The main use for this flag is efficiently encoding binary data as JSON
189text, as most octets will not be escaped, resulting in a smaller encoded 272text, as most octets will not be escaped, resulting in a smaller encoded
190size. The disadvantage is that the resulting JSON text is encoded 273size. The disadvantage is that the resulting JSON text is encoded
191in latin1 (and must correctly be treated as such when storing and 274in latin1 (and must correctly be treated as such when storing and
192transfering), a rare encoding for JSON. It is therefore most useful when 275transferring), a rare encoding for JSON. It is therefore most useful when
193you want to store data structures known to contain binary data efficiently 276you want to store data structures known to contain binary data efficiently
194in files or databases, not when talking to other JSON encoders/decoders. 277in files or databases, not when talking to other JSON encoders/decoders.
195 278
196 JSON::XS->new->latin1->encode (["\x{89}\x{abc}"] 279 JSON::XS->new->latin1->encode (["\x{89}\x{abc}"]
197 => ["\x{89}\\u0abc"] # (perl syntax, U+abc escaped, U+89 not) 280 => ["\x{89}\\u0abc"] # (perl syntax, U+abc escaped, U+89 not)
198 281
199=item $json = $json->utf8 ([$enable]) 282=item $json = $json->utf8 ([$enable])
283
284=item $enabled = $json->get_utf8
200 285
201If C<$enable> is true (or missing), then the C<encode> method will encode 286If C<$enable> is true (or missing), then the C<encode> method will encode
202the JSON result into UTF-8, as required by many protocols, while the 287the JSON result into UTF-8, as required by many protocols, while the
203C<decode> method expects to be handled an UTF-8-encoded string. Please 288C<decode> method expects to be handled an UTF-8-encoded string. Please
204note that UTF-8-encoded strings do not contain any characters outside the 289note that UTF-8-encoded strings do not contain any characters outside the
205range C<0..255>, they are thus useful for bytewise/binary I/O. In future 290range C<0..255>, they are thus useful for bytewise/binary I/O. In future
206versions, enabling this option might enable autodetection of the UTF-16 291versions, enabling this option might enable autodetection of the UTF-16
207and UTF-32 encoding families, as described in RFC4627. 292and UTF-32 encoding families, as described in RFC4627.
208 293
209If C<$enable> is false, then the C<encode> method will return the JSON 294If C<$enable> is false, then the C<encode> method will return the JSON
210string as a (non-encoded) unicode string, while C<decode> expects thus a 295string as a (non-encoded) Unicode string, while C<decode> expects thus a
211unicode string. Any decoding or encoding (e.g. to UTF-8 or UTF-16) needs 296Unicode string. Any decoding or encoding (e.g. to UTF-8 or UTF-16) needs
212to be done yourself, e.g. using the Encode module. 297to be done yourself, e.g. using the Encode module.
213 298
214Example, output UTF-16BE-encoded JSON: 299Example, output UTF-16BE-encoded JSON:
215 300
216 use Encode; 301 use Encode;
… …
238 ] 323 ]
239 } 324 }
240 325
241=item $json = $json->indent ([$enable]) 326=item $json = $json->indent ([$enable])
242 327
328=item $enabled = $json->get_indent
329
243If C<$enable> is true (or missing), then the C<encode> method will use a multiline 330If C<$enable> is true (or missing), then the C<encode> method will use a multiline
244format as output, putting every array member or object/hash key-value pair 331format as output, putting every array member or object/hash key-value pair
245into its own line, identing them properly. 332into its own line, indenting them properly.
246 333
247If C<$enable> is false, no newlines or indenting will be produced, and the 334If C<$enable> is false, no newlines or indenting will be produced, and the
248resulting JSON text is guarenteed not to contain any C<newlines>. 335resulting JSON text is guaranteed not to contain any C<newlines>.
249 336
250This setting has no effect when decoding JSON texts. 337This setting has no effect when decoding JSON texts.
251 338
252=item $json = $json->space_before ([$enable]) 339=item $json = $json->space_before ([$enable])
340
341=item $enabled = $json->get_space_before
253 342
254If C<$enable> is true (or missing), then the C<encode> method will add an extra 343If C<$enable> is true (or missing), then the C<encode> method will add an extra
255optional space before the C<:> separating keys from values in JSON objects. 344optional space before the C<:> separating keys from values in JSON objects.
256 345
257If C<$enable> is false, then the C<encode> method will not add any extra 346If C<$enable> is false, then the C<encode> method will not add any extra
… …
263Example, space_before enabled, space_after and indent disabled: 352Example, space_before enabled, space_after and indent disabled:
264 353
265 {"key" :"value"} 354 {"key" :"value"}
266 355
267=item $json = $json->space_after ([$enable]) 356=item $json = $json->space_after ([$enable])
357
358=item $enabled = $json->get_space_after
268 359
269If C<$enable> is true (or missing), then the C<encode> method will add an extra 360If C<$enable> is true (or missing), then the C<encode> method will add an extra
270optional space after the C<:> separating keys from values in JSON objects 361optional space after the C<:> separating keys from values in JSON objects
271and extra whitespace after the C<,> separating key-value pairs and array 362and extra whitespace after the C<,> separating key-value pairs and array
272members. 363members.
… …
278 369
279Example, space_before and indent disabled, space_after enabled: 370Example, space_before and indent disabled, space_after enabled:
280 371
281 {"key": "value"} 372 {"key": "value"}
282 373
374=item $json = $json->relaxed ([$enable])
375
376=item $enabled = $json->get_relaxed
377
378If C<$enable> is true (or missing), then C<decode> will accept some
379extensions to normal JSON syntax (see below). C<encode> will not be
380affected in anyway. I<Be aware that this option makes you accept invalid
381JSON texts as if they were valid!>. I suggest only to use this option to
382parse application-specific files written by humans (configuration files,
383resource files etc.)
384
385If C<$enable> is false (the default), then C<decode> will only accept
386valid JSON texts.
387
388Currently accepted extensions are:
389
390=over 4
391
392=item * list items can have an end-comma
393
394JSON I<separates> array elements and key-value pairs with commas. This
395can be annoying if you write JSON texts manually and want to be able to
396quickly append elements, so this extension accepts comma at the end of
397such items not just between them:
398
399 [
400 1,
401 2, <- this comma not normally allowed
402 ]
403 {
404 "k1": "v1",
405 "k2": "v2", <- this comma not normally allowed
406 }
407
408=item * shell-style '#'-comments
409
410Whenever JSON allows whitespace, shell-style comments are additionally
411allowed. They are terminated by the first carriage-return or line-feed
412character, after which more white-space and comments are allowed.
413
414 [
415 1, # this comment not allowed in JSON
416 # neither this one...
417 ]
418
419=back
420
283=item $json = $json->canonical ([$enable]) 421=item $json = $json->canonical ([$enable])
422
423=item $enabled = $json->get_canonical
284 424
285If C<$enable> is true (or missing), then the C<encode> method will output JSON objects 425If C<$enable> is true (or missing), then the C<encode> method will output JSON objects
286by sorting their keys. This is adding a comparatively high overhead. 426by sorting their keys. This is adding a comparatively high overhead.
287 427
288If C<$enable> is false, then the C<encode> method will output key-value 428If C<$enable> is false, then the C<encode> method will output key-value
289pairs in the order Perl stores them (which will likely change between runs 429pairs in the order Perl stores them (which will likely change between runs
290of the same script). 430of the same script).
291 431
292This option is useful if you want the same data structure to be encoded as 432This option is useful if you want the same data structure to be encoded as
293the same JSON text (given the same overall settings). If it is disabled, 433the same JSON text (given the same overall settings). If it is disabled,
294the same hash migh be encoded differently even if contains the same data, 434the same hash might be encoded differently even if contains the same data,
295as key-value pairs have no inherent ordering in Perl. 435as key-value pairs have no inherent ordering in Perl.
296 436
297This setting has no effect when decoding JSON texts. 437This setting has no effect when decoding JSON texts.
298 438
299=item $json = $json->allow_nonref ([$enable]) 439=item $json = $json->allow_nonref ([$enable])
440
441=item $enabled = $json->get_allow_nonref
300 442
301If C<$enable> is true (or missing), then the C<encode> method can convert a 443If C<$enable> is true (or missing), then the C<encode> method can convert a
302non-reference into its corresponding string, number or null JSON value, 444non-reference into its corresponding string, number or null JSON value,
303which is an extension to RFC4627. Likewise, C<decode> will accept those JSON 445which is an extension to RFC4627. Likewise, C<decode> will accept those JSON
304values instead of croaking. 446values instead of croaking.
… …
314 JSON::XS->new->allow_nonref->encode ("Hello, World!") 456 JSON::XS->new->allow_nonref->encode ("Hello, World!")
315 => "Hello, World!" 457 => "Hello, World!"
316 458
317=item $json = $json->allow_blessed ([$enable]) 459=item $json = $json->allow_blessed ([$enable])
318 460
461=item $enabled = $json->get_allow_blessed
462
319If C<$enable> is true (or missing), then the C<encode> method will not 463If C<$enable> is true (or missing), then the C<encode> method will not
320barf when it encounters a blessed reference. Instead, the value of the 464barf when it encounters a blessed reference. Instead, the value of the
321B<convert_blessed> option will decide wether C<null> (C<convert_blessed> 465B<convert_blessed> option will decide whether C<null> (C<convert_blessed>
322disabled or no C<to_json> method found) or a representation of the 466disabled or no C<TO_JSON> method found) or a representation of the
323object (C<convert_blessed> enabled and C<to_json> method found) is being 467object (C<convert_blessed> enabled and C<TO_JSON> method found) is being
324encoded. Has no effect on C<decode>. 468encoded. Has no effect on C<decode>.
325 469
326If C<$enable> is false (the default), then C<encode> will throw an 470If C<$enable> is false (the default), then C<encode> will throw an
327exception when it encounters a blessed object. 471exception when it encounters a blessed object.
328 472
329=item $json = $json->convert_blessed ([$enable]) 473=item $json = $json->convert_blessed ([$enable])
474
475=item $enabled = $json->get_convert_blessed
330 476
331If C<$enable> is true (or missing), then C<encode>, upon encountering a 477If C<$enable> is true (or missing), then C<encode>, upon encountering a
332blessed object, will check for the availability of the C<TO_JSON> method 478blessed object, will check for the availability of the C<TO_JSON> method
333on the object's class. If found, it will be called in scalar context 479on the object's class. If found, it will be called in scalar context
334and the resulting scalar will be encoded instead of the object. If no 480and the resulting scalar will be encoded instead of the object. If no
… …
338The C<TO_JSON> method may safely call die if it wants. If C<TO_JSON> 484The C<TO_JSON> method may safely call die if it wants. If C<TO_JSON>
339returns other blessed objects, those will be handled in the same 485returns other blessed objects, those will be handled in the same
340way. C<TO_JSON> must take care of not causing an endless recursion cycle 486way. C<TO_JSON> must take care of not causing an endless recursion cycle
341(== crash) in this case. The name of C<TO_JSON> was chosen because other 487(== crash) in this case. The name of C<TO_JSON> was chosen because other
342methods called by the Perl core (== not by the user of the object) are 488methods called by the Perl core (== not by the user of the object) are
343usually in upper case letters and to avoid collisions with the C<to_json> 489usually in upper case letters and to avoid collisions with any C<to_json>
344function. 490function or method.
345 491
346This setting does not yet influence C<decode> in any way, but in the 492This setting does not yet influence C<decode> in any way, but in the
347future, global hooks might get installed that influence C<decode> and are 493future, global hooks might get installed that influence C<decode> and are
348enabled by this setting. 494enabled by this setting.
349 495
350If C<$enable> is false, then the C<allow_blessed> setting will decide what 496If C<$enable> is false, then the C<allow_blessed> setting will decide what
351to do when a blessed object is found. 497to do when a blessed object is found.
352 498
499=item $json = $json->filter_json_object ([$coderef->($hashref)])
500
501When C<$coderef> is specified, it will be called from C<decode> each
502time it decodes a JSON object. The only argument is a reference to the
503newly-created hash. If the code references returns a single scalar (which
504need not be a reference), this value (i.e. a copy of that scalar to avoid
505aliasing) is inserted into the deserialised data structure. If it returns
506an empty list (NOTE: I<not> C<undef>, which is a valid scalar), the
507original deserialised hash will be inserted. This setting can slow down
508decoding considerably.
509
510When C<$coderef> is omitted or undefined, any existing callback will
511be removed and C<decode> will not change the deserialised hash in any
512way.
513
514Example, convert all JSON objects into the integer 5:
515
516 my $js = JSON::XS->new->filter_json_object (sub { 5 });
517 # returns [5]
518 $js->decode ('[{}]')
519 # throw an exception because allow_nonref is not enabled
520 # so a lone 5 is not allowed.
521 $js->decode ('{"a":1, "b":2}');
522
523=item $json = $json->filter_json_single_key_object ($key [=> $coderef->($value)])
524
525Works remotely similar to C<filter_json_object>, but is only called for
526JSON objects having a single key named C<$key>.
527
528This C<$coderef> is called before the one specified via
529C<filter_json_object>, if any. It gets passed the single value in the JSON
530object. If it returns a single value, it will be inserted into the data
531structure. If it returns nothing (not even C<undef> but the empty list),
532the callback from C<filter_json_object> will be called next, as if no
533single-key callback were specified.
534
535If C<$coderef> is omitted or undefined, the corresponding callback will be
536disabled. There can only ever be one callback for a given key.
537
538As this callback gets called less often then the C<filter_json_object>
539one, decoding speed will not usually suffer as much. Therefore, single-key
540objects make excellent targets to serialise Perl objects into, especially
541as single-key JSON objects are as close to the type-tagged value concept
542as JSON gets (it's basically an ID/VALUE tuple). Of course, JSON does not
543support this in any way, so you need to make sure your data never looks
544like a serialised Perl hash.
545
546Typical names for the single object key are C<__class_whatever__>, or
547C<$__dollars_are_rarely_used__$> or C<}ugly_brace_placement>, or even
548things like C<__class_md5sum(classname)__>, to reduce the risk of clashing
549with real hashes.
550
551Example, decode JSON objects of the form C<< { "__widget__" => <id> } >>
552into the corresponding C<< $WIDGET{<id>} >> object:
553
554 # return whatever is in $WIDGET{5}:
555 JSON::XS
556 ->new
557 ->filter_json_single_key_object (__widget__ => sub {
558 $WIDGET{ $_[0] }
559 })
560 ->decode ('{"__widget__": 5')
561
562 # this can be used with a TO_JSON method in some "widget" class
563 # for serialisation to json:
564 sub WidgetBase::TO_JSON {
565 my ($self) = @_;
566
567 unless ($self->{id}) {
568 $self->{id} = ..get..some..id..;
569 $WIDGET{$self->{id}} = $self;
570 }
571
572 { __widget__ => $self->{id} }
573 }
574
353=item $json = $json->shrink ([$enable]) 575=item $json = $json->shrink ([$enable])
576
577=item $enabled = $json->get_shrink
354 578
355Perl usually over-allocates memory a bit when allocating space for 579Perl usually over-allocates memory a bit when allocating space for
356strings. This flag optionally resizes strings generated by either 580strings. This flag optionally resizes strings generated by either
357C<encode> or C<decode> to their minimum size possible. This can save 581C<encode> or C<decode> to their minimum size possible. This can save
358memory when your JSON texts are either very very long or you have many 582memory when your JSON texts are either very very long or you have many
… …
376strings that look like integers or floats into integers or floats 600strings that look like integers or floats into integers or floats
377internally (there is no difference on the Perl level), saving space. 601internally (there is no difference on the Perl level), saving space.
378 602
379=item $json = $json->max_depth ([$maximum_nesting_depth]) 603=item $json = $json->max_depth ([$maximum_nesting_depth])
380 604
605=item $max_depth = $json->get_max_depth
606
381Sets the maximum nesting level (default C<512>) accepted while encoding 607Sets the maximum nesting level (default C<512>) accepted while encoding
382or decoding. If the JSON text or Perl data structure has an equal or 608or decoding. If the JSON text or Perl data structure has an equal or
383higher nesting level then this limit, then the encoder and decoder will 609higher nesting level then this limit, then the encoder and decoder will
384stop and croak at that point. 610stop and croak at that point.
385 611
… …
396used, which is rarely useful. 622used, which is rarely useful.
397 623
398See SECURITY CONSIDERATIONS, below, for more info on why this is useful. 624See SECURITY CONSIDERATIONS, below, for more info on why this is useful.
399 625
400=item $json = $json->max_size ([$maximum_string_size]) 626=item $json = $json->max_size ([$maximum_string_size])
627
628=item $max_size = $json->get_max_size
401 629
402Set the maximum length a JSON text may have (in bytes) where decoding is 630Set the maximum length a JSON text may have (in bytes) where decoding is
403being attempted. The default is C<0>, meaning no limit. When C<decode> 631being attempted. The default is C<0>, meaning no limit. When C<decode>
404is called on a string longer then this number of characters it will not 632is called on a string longer then this number of characters it will not
405attempt to decode the string but throw an exception. This setting has no 633attempt to decode the string but throw an exception. This setting has no
… …
452vice versa. These mappings are designed to "do the right thing" in most 680vice versa. These mappings are designed to "do the right thing" in most
453circumstances automatically, preserving round-tripping characteristics 681circumstances automatically, preserving round-tripping characteristics
454(what you put in comes out as something equivalent). 682(what you put in comes out as something equivalent).
455 683
456For the more enlightened: note that in the following descriptions, 684For the more enlightened: note that in the following descriptions,
457lowercase I<perl> refers to the Perl interpreter, while uppcercase I<Perl> 685lowercase I<perl> refers to the Perl interpreter, while uppercase I<Perl>
458refers to the abstract Perl language itself. 686refers to the abstract Perl language itself.
459 687
460 688
461=head2 JSON -> PERL 689=head2 JSON -> PERL
462 690
463=over 4 691=over 4
464 692
465=item object 693=item object
466 694
467A JSON object becomes a reference to a hash in Perl. No ordering of object 695A JSON object becomes a reference to a hash in Perl. No ordering of object
468keys is preserved (JSON does not preserver object key ordering itself). 696keys is preserved (JSON does not preserve object key ordering itself).
469 697
470=item array 698=item array
471 699
472A JSON array becomes a reference to an array in Perl. 700A JSON array becomes a reference to an array in Perl.
473 701
… …
477are represented by the same codepoints in the Perl string, so no manual 705are represented by the same codepoints in the Perl string, so no manual
478decoding is necessary. 706decoding is necessary.
479 707
480=item number 708=item number
481 709
482A JSON number becomes either an integer or numeric (floating point) 710A JSON number becomes either an integer, numeric (floating point) or
483scalar in perl, depending on its range and any fractional parts. On the 711string scalar in perl, depending on its range and any fractional parts. On
484Perl level, there is no difference between those as Perl handles all the 712the Perl level, there is no difference between those as Perl handles all
485conversion details, but an integer may take slightly less memory and might 713the conversion details, but an integer may take slightly less memory and
486represent more values exactly than (floating point) numbers. 714might represent more values exactly than floating point numbers.
715
716If the number consists of digits only, JSON::XS will try to represent
717it as an integer value. If that fails, it will try to represent it as
718a numeric (floating point) value if that is possible without loss of
719precision. Otherwise it will preserve the number as a string value (in
720which case you lose roundtripping ability, as the JSON number will be
721re-encoded toa JSON string).
722
723Numbers containing a fractional or exponential part will always be
724represented as numeric (floating point) values, possibly at a loss of
725precision (in which case you might lose perfect roundtripping ability, but
726the JSON number will still be re-encoded as a JSON number).
487 727
488=item true, false 728=item true, false
489 729
490These JSON atoms become C<JSON::XS::true> and C<JSON::XS::false>, 730These JSON atoms become C<JSON::XS::true> and C<JSON::XS::false>,
491respectively. They are overloaded to act almost exactly like the numbers 731respectively. They are overloaded to act almost exactly like the numbers
492C<1> and C<0>. You can check wether a scalar is a JSON boolean by using 732C<1> and C<0>. You can check whether a scalar is a JSON boolean by using
493the C<JSON::XS::is_bool> function. 733the C<JSON::XS::is_bool> function.
494 734
495=item null 735=item null
496 736
497A JSON null atom becomes C<undef> in Perl. 737A JSON null atom becomes C<undef> in Perl.
… …
528Other unblessed references are generally not allowed and will cause an 768Other unblessed references are generally not allowed and will cause an
529exception to be thrown, except for references to the integers C<0> and 769exception to be thrown, except for references to the integers C<0> and
530C<1>, which get turned into C<false> and C<true> atoms in JSON. You can 770C<1>, which get turned into C<false> and C<true> atoms in JSON. You can
531also use C<JSON::XS::false> and C<JSON::XS::true> to improve readability. 771also use C<JSON::XS::false> and C<JSON::XS::true> to improve readability.
532 772
533 to_json [\0,JSON::XS::true] # yields [false,true] 773 encode_json [\0,JSON::XS::true] # yields [false,true]
534 774
535=item JSON::XS::true, JSON::XS::false 775=item JSON::XS::true, JSON::XS::false
536 776
537These special values become JSON true and JSON false values, 777These special values become JSON true and JSON false values,
538respectively. You cna alos use C<\1> and C<\0> directly if you want. 778respectively. You can also use C<\1> and C<\0> directly if you want.
539 779
540=item blessed objects 780=item blessed objects
541 781
542Blessed objects are not allowed. JSON::XS currently tries to encode their 782Blessed objects are not directly representable in JSON. See the
543underlying representation (hash- or arrayref), but this behaviour might 783C<allow_blessed> and C<convert_blessed> methods on various options on
544change in future versions. 784how to deal with this: basically, you can choose between throwing an
785exception, encoding the reference as if it weren't blessed, or provide
786your own serialiser method.
545 787
546=item simple scalars 788=item simple scalars
547 789
548Simple Perl scalars (any scalar that is not a reference) are the most 790Simple Perl scalars (any scalar that is not a reference) are the most
549difficult objects to encode: JSON::XS will encode undefined scalars as 791difficult objects to encode: JSON::XS will encode undefined scalars as
550JSON null value, scalars that have last been used in a string context 792JSON C<null> values, scalars that have last been used in a string context
551before encoding as JSON strings and anything else as number value: 793before encoding as JSON strings, and anything else as number value:
552 794
553 # dump as number 795 # dump as number
554 to_json [2] # yields [2] 796 encode_json [2] # yields [2]
555 to_json [-3.0e17] # yields [-3e+17] 797 encode_json [-3.0e17] # yields [-3e+17]
556 my $value = 5; to_json [$value] # yields [5] 798 my $value = 5; encode_json [$value] # yields [5]
557 799
558 # used as string, so dump as string 800 # used as string, so dump as string
559 print $value; 801 print $value;
560 to_json [$value] # yields ["5"] 802 encode_json [$value] # yields ["5"]
561 803
562 # undef becomes null 804 # undef becomes null
563 to_json [undef] # yields [null] 805 encode_json [undef] # yields [null]
564 806
565You can force the type to be a string by stringifying it: 807You can force the type to be a JSON string by stringifying it:
566 808
567 my $x = 3.1; # some variable containing a number 809 my $x = 3.1; # some variable containing a number
568 "$x"; # stringified 810 "$x"; # stringified
569 $x .= ""; # another, more awkward way to stringify 811 $x .= ""; # another, more awkward way to stringify
570 print $x; # perl does it for you, too, quite often 812 print $x; # perl does it for you, too, quite often
571 813
572You can force the type to be a number by numifying it: 814You can force the type to be a JSON number by numifying it:
573 815
574 my $x = "3"; # some variable containing a string 816 my $x = "3"; # some variable containing a string
575 $x += 0; # numify it, ensuring it will be dumped as a number 817 $x += 0; # numify it, ensuring it will be dumped as a number
576 $x *= 1; # same thing, the choise is yours. 818 $x *= 1; # same thing, the choice is yours.
577 819
578You can not currently output JSON booleans or force the type in other, 820You can not currently force the type in other, less obscure, ways. Tell me
579less obscure, ways. Tell me if you need this capability. 821if you need this capability (but don't forget to explain why its needed
822:).
823
824=back
825
826
827=head1 ENCODING/CODESET FLAG NOTES
828
829The interested reader might have seen a number of flags that signify
830encodings or codesets - C<utf8>, C<latin1> and C<ascii>. There seems to be
831some confusion on what these do, so here is a short comparison:
832
833C<utf8> controls wether the JSON text created by C<encode> (and expected
834by C<decode>) is UTF-8 encoded or not, while C<latin1> and C<ascii> only
835control wether C<encode> escapes character values outside their respective
836codeset range. Neither of these flags conflict with each other, although
837some combinations make less sense than others.
838
839Care has been taken to make all flags symmetrical with respect to
840C<encode> and C<decode>, that is, texts encoded with any combination of
841these flag values will be correctly decoded when the same flags are used
842- in general, if you use different flag settings while encoding vs. when
843decoding you likely have a bug somewhere.
844
845Below comes a verbose discussion of these flags. Note that a "codeset" is
846simply an abstract set of character-codepoint pairs, while an encoding
847takes those codepoint numbers and I<encodes> them, in our case into
848octets. Unicode is (among other things) a codeset, UTF-8 is an encoding,
849and ISO-8859-1 (= latin 1) and ASCII are both codesets I<and> encodings at
850the same time, which can be confusing.
851
852=over 4
853
854=item C<utf8> flag disabled
855
856When C<utf8> is disabled (the default), then C<encode>/C<decode> generate
857and expect Unicode strings, that is, characters with high ordinal Unicode
858values (> 255) will be encoded as such characters, and likewise such
859characters are decoded as-is, no canges to them will be done, except
860"(re-)interpreting" them as Unicode codepoints or Unicode characters,
861respectively (to Perl, these are the same thing in strings unless you do
862funny/weird/dumb stuff).
863
864This is useful when you want to do the encoding yourself (e.g. when you
865want to have UTF-16 encoded JSON texts) or when some other layer does
866the encoding for you (for example, when printing to a terminal using a
867filehandle that transparently encodes to UTF-8 you certainly do NOT want
868to UTF-8 encode your data first and have Perl encode it another time).
869
870=item C<utf8> flag enabled
871
872If the C<utf8>-flag is enabled, C<encode>/C<decode> will encode all
873characters using the corresponding UTF-8 multi-byte sequence, and will
874expect your input strings to be encoded as UTF-8, that is, no "character"
875of the input string must have any value > 255, as UTF-8 does not allow
876that.
877
878The C<utf8> flag therefore switches between two modes: disabled means you
879will get a Unicode string in Perl, enabled means you get an UTF-8 encoded
880octet/binary string in Perl.
881
882=item C<latin1> or C<ascii> flags enabled
883
884With C<latin1> (or C<ascii>) enabled, C<encode> will escape characters
885with ordinal values > 255 (> 127 with C<ascii>) and encode the remaining
886characters as specified by the C<utf8> flag.
887
888If C<utf8> is disabled, then the result is also correctly encoded in those
889character sets (as both are proper subsets of Unicode, meaning that a
890Unicode string with all character values < 256 is the same thing as a
891ISO-8859-1 string, and a Unicode string with all character values < 128 is
892the same thing as an ASCII string in Perl).
893
894If C<utf8> is enabled, you still get a correct UTF-8-encoded string,
895regardless of these flags, just some more characters will be escaped using
896C<\uXXXX> then before.
897
898Note that ISO-8859-1-I<encoded> strings are not compatible with UTF-8
899encoding, while ASCII-encoded strings are. That is because the ISO-8859-1
900encoding is NOT a subset of UTF-8 (despite the ISO-8859-1 I<codeset> being
901a subset of Unicode), while ASCII is.
902
903Surprisingly, C<decode> will ignore these flags and so treat all input
904values as governed by the C<utf8> flag. If it is disabled, this allows you
905to decode ISO-8859-1- and ASCII-encoded strings, as both strict subsets of
906Unicode. If it is enabled, you can correctly decode UTF-8 encoded strings.
907
908So neither C<latin1> nor C<ascii> are incompatible with the C<utf8> flag -
909they only govern when the JSON output engine escapes a character or not.
910
911The main use for C<latin1> is to relatively efficiently store binary data
912as JSON, at the expense of breaking compatibility with most JSON decoders.
913
914The main use for C<ascii> is to force the output to not contain characters
915with values > 127, which means you can interpret the resulting string
916as UTF-8, ISO-8859-1, ASCII, KOI8-R or most about any character set and
9178-bit-encoding, and still get the same data structure back. This is useful
918when your channel for JSON transfer is not 8-bit clean or the encoding
919might be mangled in between (e.g. in mail), and works because ASCII is a
920proper subset of most 8-bit and multibyte encodings in use in the world.
580 921
581=back 922=back
582 923
583 924
584=head1 COMPARISON 925=head1 COMPARISON
… …
589followed by some benchmark values. JSON::XS was designed not to suffer 930followed by some benchmark values. JSON::XS was designed not to suffer
590from any of these problems or limitations. 931from any of these problems or limitations.
591 932
592=over 4 933=over 4
593 934
935=item JSON 2.xx
936
937A marvellous piece of engineering, this module either uses JSON::XS
938directly when available (so will be 100% compatible with it, including
939speed), or it uses JSON::PP, which is basically JSON::XS translated to
940Pure Perl, which should be 100% compatible with JSON::XS, just a bit
941slower.
942
943You cannot really lose by using this module.
944
594=item JSON 1.07 945=item JSON 1.07
595 946
596Slow (but very portable, as it is written in pure Perl). 947Slow (but very portable, as it is written in pure Perl).
597 948
598Undocumented/buggy Unicode handling (how JSON handles unicode values is 949Undocumented/buggy Unicode handling (how JSON handles Unicode values is
599undocumented. One can get far by feeding it unicode strings and doing 950undocumented. One can get far by feeding it Unicode strings and doing
600en-/decoding oneself, but unicode escapes are not working properly). 951en-/decoding oneself, but Unicode escapes are not working properly).
601 952
602No roundtripping (strings get clobbered if they look like numbers, e.g. 953No round-tripping (strings get clobbered if they look like numbers, e.g.
603the string C<2.0> will encode to C<2.0> instead of C<"2.0">, and that will 954the string C<2.0> will encode to C<2.0> instead of C<"2.0">, and that will
604decode into the number 2. 955decode into the number 2.
605 956
606=item JSON::PC 0.01 957=item JSON::PC 0.01
607 958
608Very fast. 959Very fast.
609 960
610Undocumented/buggy Unicode handling. 961Undocumented/buggy Unicode handling.
611 962
612No roundtripping. 963No round-tripping.
613 964
614Has problems handling many Perl values (e.g. regex results and other magic 965Has problems handling many Perl values (e.g. regex results and other magic
615values will make it croak). 966values will make it croak).
616 967
617Does not even generate valid JSON (C<{1,2}> gets converted to C<{1:2}> 968Does not even generate valid JSON (C<{1,2}> gets converted to C<{1:2}>
… …
627Very inflexible (no human-readable format supported, format pretty much 978Very inflexible (no human-readable format supported, format pretty much
628undocumented. I need at least a format for easy reading by humans and a 979undocumented. I need at least a format for easy reading by humans and a
629single-line compact format for use in a protocol, and preferably a way to 980single-line compact format for use in a protocol, and preferably a way to
630generate ASCII-only JSON texts). 981generate ASCII-only JSON texts).
631 982
632Completely broken (and confusingly documented) Unicode handling (unicode 983Completely broken (and confusingly documented) Unicode handling (Unicode
633escapes are not working properly, you need to set ImplicitUnicode to 984escapes are not working properly, you need to set ImplicitUnicode to
634I<different> values on en- and decoding to get symmetric behaviour). 985I<different> values on en- and decoding to get symmetric behaviour).
635 986
636No roundtripping (simple cases work, but this depends on wether the scalar 987No round-tripping (simple cases work, but this depends on whether the scalar
637value was used in a numeric context or not). 988value was used in a numeric context or not).
638 989
639Dumping hashes may skip hash values depending on iterator state. 990Dumping hashes may skip hash values depending on iterator state.
640 991
641Unmaintained (maintainer unresponsive for many months, bugs are not 992Unmaintained (maintainer unresponsive for many months, bugs are not
642getting fixed). 993getting fixed).
643 994
644Does not check input for validity (i.e. will accept non-JSON input and 995Does not check input for validity (i.e. will accept non-JSON input and
645return "something" instead of raising an exception. This is a security 996return "something" instead of raising an exception. This is a security
646issue: imagine two banks transfering money between each other using 997issue: imagine two banks transferring money between each other using
647JSON. One bank might parse a given non-JSON request and deduct money, 998JSON. One bank might parse a given non-JSON request and deduct money,
648while the other might reject the transaction with a syntax error. While a 999while the other might reject the transaction with a syntax error. While a
649good protocol will at least recover, that is extra unnecessary work and 1000good protocol will at least recover, that is extra unnecessary work and
650the transaction will still not succeed). 1001the transaction will still not succeed).
651 1002
652=item JSON::DWIW 0.04 1003=item JSON::DWIW 0.04
653 1004
654Very fast. Very natural. Very nice. 1005Very fast. Very natural. Very nice.
655 1006
656Undocumented unicode handling (but the best of the pack. Unicode escapes 1007Undocumented Unicode handling (but the best of the pack. Unicode escapes
657still don't get parsed properly). 1008still don't get parsed properly).
658 1009
659Very inflexible. 1010Very inflexible.
660 1011
661No roundtripping. 1012No round-tripping.
662 1013
663Does not generate valid JSON texts (key strings are often unquoted, empty keys 1014Does not generate valid JSON texts (key strings are often unquoted, empty keys
664result in nothing being output) 1015result in nothing being output)
665 1016
666Does not check input for validity. 1017Does not check input for validity.
… …
668=back 1019=back
669 1020
670 1021
671=head2 JSON and YAML 1022=head2 JSON and YAML
672 1023
673You often hear that JSON is a subset (or a close subset) of YAML. This is, 1024You often hear that JSON is a subset of YAML. This is, however, a mass
674however, a mass hysteria and very far from the truth. In general, there is 1025hysteria(*) and very far from the truth. In general, there is no way to
675no way to configure JSON::XS to output a data structure as valid YAML. 1026configure JSON::XS to output a data structure as valid YAML that works for
1027all cases.
676 1028
677If you really must use JSON::XS to generate YAML, you should use this 1029If you really must use JSON::XS to generate YAML, you should use this
678algorithm (subject to change in future versions): 1030algorithm (subject to change in future versions):
679 1031
680 my $to_yaml = JSON::XS->new->utf8->space_after (1); 1032 my $to_yaml = JSON::XS->new->utf8->space_after (1);
681 my $yaml = $to_yaml->encode ($ref) . "\n"; 1033 my $yaml = $to_yaml->encode ($ref) . "\n";
682 1034
683This will usually generate JSON texts that also parse as valid 1035This will I<usually> generate JSON texts that also parse as valid
684YAML. Please note that YAML has hardcoded limits on (simple) object key 1036YAML. Please note that YAML has hardcoded limits on (simple) object key
685lengths that JSON doesn't have, so you should make sure that your hash 1037lengths that JSON doesn't have and also has different and incompatible
1038unicode handling, so you should make sure that your hash keys are
686keys are noticably shorter than the 1024 characters YAML allows. 1039noticeably shorter than the 1024 "stream characters" YAML allows and that
1040you do not have codepoints with values outside the Unicode BMP (basic
1041multilingual page). YAML also does not allow C<\/> sequences in strings
1042(which JSON::XS does not I<currently> generate).
687 1043
688There might be other incompatibilities that I am not aware of. In general 1044There might be other incompatibilities that I am not aware of (or the YAML
1045specification has been changed yet again - it does so quite often). In
689you should not try to generate YAML with a JSON generator or vice versa, 1046general you should not try to generate YAML with a JSON generator or vice
690or try to parse JSON with a YAML parser or vice versa: chances are high 1047versa, or try to parse JSON with a YAML parser or vice versa: chances are
691that you will run into severe interoperability problems. 1048high that you will run into severe interoperability problems when you
1049least expect it.
1050
1051=over 4
1052
1053=item (*)
1054
1055This is spread actively by the YAML team, however. For many years now they
1056claim YAML were a superset of JSON, even when proven otherwise.
1057
1058Even the author of this manpage was at some point accused of providing
1059"incorrect" information, despite the evidence presented (claims ranged
1060from "your documentation contains inaccurate and negative statements about
1061YAML" (the only negative comment is this footnote, and it didn't exist
1062back then; the question on which claims were inaccurate was never answered
1063etc.) to "the YAML spec is not up-to-date" (the *real* and supposedly
1064JSON-compatible spec is apparently not currently publicly available)
1065to actual requests to replace this section by *incorrect* information,
1066suppressing information about the real problem).
1067
1068So whenever you are told that YAML was a superset of JSON, first check
1069wether it is really true (it might be when you check it, but it certainly
1070was not true when this was written). I would much prefer if the YAML team
1071would spent their time on actually making JSON compatibility a truth
1072(JSON, after all, has a very small and simple specification) instead of
1073trying to lobby/force people into reporting untruths.
1074
1075=back
692 1076
693 1077
694=head2 SPEED 1078=head2 SPEED
695 1079
696It seems that JSON::XS is surprisingly fast, as shown in the following 1080It seems that JSON::XS is surprisingly fast, as shown in the following
… …
707It shows the number of encodes/decodes per second (JSON::XS uses 1091It shows the number of encodes/decodes per second (JSON::XS uses
708the functional interface, while JSON::XS/2 uses the OO interface 1092the functional interface, while JSON::XS/2 uses the OO interface
709with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables 1093with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables
710shrink). Higher is better: 1094shrink). Higher is better:
711 1095
712 Storable | 15779.925 | 14169.946 |
713 -----------+------------+------------+
714 module | encode | decode | 1096 module | encode | decode |
715 -----------|------------|------------| 1097 -----------|------------|------------|
716 JSON | 4990.842 | 4088.813 | 1098 JSON 1.x | 4990.842 | 4088.813 |
717 JSON::DWIW | 51653.990 | 71575.154 | 1099 JSON::DWIW | 51653.990 | 71575.154 |
718 JSON::PC | 65948.176 | 74631.744 | 1100 JSON::PC | 65948.176 | 74631.744 |
719 JSON::PP | 8931.652 | 3817.168 | 1101 JSON::PP | 8931.652 | 3817.168 |
720 JSON::Syck | 24877.248 | 27776.848 | 1102 JSON::Syck | 24877.248 | 27776.848 |
721 JSON::XS | 388361.481 | 227951.304 | 1103 JSON::XS | 388361.481 | 227951.304 |
… …
723 JSON::XS/3 | 338250.323 | 218453.333 | 1105 JSON::XS/3 | 338250.323 | 218453.333 |
724 Storable | 16500.016 | 135300.129 | 1106 Storable | 16500.016 | 135300.129 |
725 -----------+------------+------------+ 1107 -----------+------------+------------+
726 1108
727That is, JSON::XS is about five times faster than JSON::DWIW on encoding, 1109That is, JSON::XS is about five times faster than JSON::DWIW on encoding,
728about three times faster on decoding, and over fourty times faster 1110about three times faster on decoding, and over forty times faster
729than JSON, even with pretty-printing and key sorting. It also compares 1111than JSON, even with pretty-printing and key sorting. It also compares
730favourably to Storable for small amounts of data. 1112favourably to Storable for small amounts of data.
731 1113
732Using a longer test string (roughly 18KB, generated from Yahoo! Locals 1114Using a longer test string (roughly 18KB, generated from Yahoo! Locals
733search API (http://nanoref.com/yahooapis/mgPdGg): 1115search API (http://nanoref.com/yahooapis/mgPdGg):
734 1116
735 module | encode | decode | 1117 module | encode | decode |
736 -----------|------------|------------| 1118 -----------|------------|------------|
737 JSON | 55.260 | 34.971 | 1119 JSON 1.x | 55.260 | 34.971 |
738 JSON::DWIW | 825.228 | 1082.513 | 1120 JSON::DWIW | 825.228 | 1082.513 |
739 JSON::PC | 3571.444 | 2394.829 | 1121 JSON::PC | 3571.444 | 2394.829 |
740 JSON::PP | 210.987 | 32.574 | 1122 JSON::PP | 210.987 | 32.574 |
741 JSON::Syck | 552.551 | 787.544 | 1123 JSON::Syck | 552.551 | 787.544 |
742 JSON::XS | 5780.463 | 4854.519 | 1124 JSON::XS | 5780.463 | 4854.519 |
… …
746 -----------+------------+------------+ 1128 -----------+------------+------------+
747 1129
748Again, JSON::XS leads by far (except for Storable which non-surprisingly 1130Again, JSON::XS leads by far (except for Storable which non-surprisingly
749decodes faster). 1131decodes faster).
750 1132
751On large strings containing lots of high unicode characters, some modules 1133On large strings containing lots of high Unicode characters, some modules
752(such as JSON::PC) seem to decode faster than JSON::XS, but the result 1134(such as JSON::PC) seem to decode faster than JSON::XS, but the result
753will be broken due to missing (or wrong) unicode handling. Others refuse 1135will be broken due to missing (or wrong) Unicode handling. Others refuse
754to decode or encode properly, so it was impossible to prepare a fair 1136to decode or encode properly, so it was impossible to prepare a fair
755comparison table for that case. 1137comparison table for that case.
756 1138
757 1139
758=head1 SECURITY CONSIDERATIONS 1140=head1 SECURITY CONSIDERATIONS
… …
764any buffer overflows. Obviously, this module should ensure that and I am 1146any buffer overflows. Obviously, this module should ensure that and I am
765trying hard on making that true, but you never know. 1147trying hard on making that true, but you never know.
766 1148
767Second, you need to avoid resource-starving attacks. That means you should 1149Second, you need to avoid resource-starving attacks. That means you should
768limit the size of JSON texts you accept, or make sure then when your 1150limit the size of JSON texts you accept, or make sure then when your
769resources run out, thats just fine (e.g. by using a separate process that 1151resources run out, that's just fine (e.g. by using a separate process that
770can crash safely). The size of a JSON text in octets or characters is 1152can crash safely). The size of a JSON text in octets or characters is
771usually a good indication of the size of the resources required to decode 1153usually a good indication of the size of the resources required to decode
772it into a Perl structure. While JSON::XS can check the size of the JSON 1154it into a Perl structure. While JSON::XS can check the size of the JSON
773text, it might be too late when you already have it in memory, so you 1155text, it might be too late when you already have it in memory, so you
774might want to check the size before you accept the string. 1156might want to check the size before you accept the string.
775 1157
776Third, JSON::XS recurses using the C stack when decoding objects and 1158Third, JSON::XS recurses using the C stack when decoding objects and
777arrays. The C stack is a limited resource: for instance, on my amd64 1159arrays. The C stack is a limited resource: for instance, on my amd64
778machine with 8MB of stack size I can decode around 180k nested arrays but 1160machine with 8MB of stack size I can decode around 180k nested arrays but
779only 14k nested JSON objects (due to perl itself recursing deeply on croak 1161only 14k nested JSON objects (due to perl itself recursing deeply on croak
780to free the temporary). If that is exceeded, the program crashes. to be 1162to free the temporary). If that is exceeded, the program crashes. To be
781conservative, the default nesting limit is set to 512. If your process 1163conservative, the default nesting limit is set to 512. If your process
782has a smaller stack, you should adjust this setting accordingly with the 1164has a smaller stack, you should adjust this setting accordingly with the
783C<max_depth> method. 1165C<max_depth> method.
784 1166
785And last but least, something else could bomb you that I forgot to think 1167And last but least, something else could bomb you that I forgot to think
786of. In that case, you get to keep the pieces. I am always open for hints, 1168of. In that case, you get to keep the pieces. I am always open for hints,
787though... 1169though...
788 1170
789If you are using JSON::XS to return packets to consumption 1171If you are using JSON::XS to return packets to consumption
790by javascript scripts in a browser you should have a look at 1172by JavaScript scripts in a browser you should have a look at
791L<http://jpsykes.com/47/practical-csrf-and-json-security> to see wether 1173L<http://jpsykes.com/47/practical-csrf-and-json-security> to see whether
792you are vulnerable to some common attack vectors (which really are browser 1174you are vulnerable to some common attack vectors (which really are browser
793design bugs, but it is still you who will have to deal with it, as major 1175design bugs, but it is still you who will have to deal with it, as major
794browser developers care only for features, not about doing security 1176browser developers care only for features, not about getting security
795right). 1177right).
1178
1179
1180=head1 THREADS
1181
1182This module is I<not> guaranteed to be thread safe and there are no
1183plans to change this until Perl gets thread support (as opposed to the
1184horribly slow so-called "threads" which are simply slow and bloated
1185process simulations - use fork, its I<much> faster, cheaper, better).
1186
1187(It might actually work, but you have been warned).
796 1188
797 1189
798=head1 BUGS 1190=head1 BUGS
799 1191
800While the goal of this module is to be correct, that unfortunately does 1192While the goal of this module is to be correct, that unfortunately does
801not mean its bug-free, only that I think its design is bug-free. It is 1193not mean its bug-free, only that I think its design is bug-free. It is
802still relatively early in its development. If you keep reporting bugs they 1194still relatively early in its development. If you keep reporting bugs they
803will be fixed swiftly, though. 1195will be fixed swiftly, though.
1196
1197Please refrain from using rt.cpan.org or any other bug reporting
1198service. I put the contact address into my modules for a reason.
804 1199
805=cut 1200=cut
806 1201
807our $true = do { bless \(my $dummy = 1), "JSON::XS::Boolean" }; 1202our $true = do { bless \(my $dummy = 1), "JSON::XS::Boolean" };
808our $false = do { bless \(my $dummy = 0), "JSON::XS::Boolean" }; 1203our $false = do { bless \(my $dummy = 0), "JSON::XS::Boolean" };

Diff Legend

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