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

Diff Legend

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