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.60 by root, Mon Aug 27 02:03:23 2007 UTC vs.
Revision 1.77 by root, Tue Dec 4 10:37:42 2007 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
16 19
17 $coder = JSON::XS->new->ascii->pretty->allow_nonref; 20 $coder = JSON::XS->new->ascii->pretty->allow_nonref;
18 $pretty_printed_unencoded = $coder->encode ($perl_scalar); 21 $pretty_printed_unencoded = $coder->encode ($perl_scalar);
19 $perl_scalar = $coder->decode ($unicode_json_text); 22 $perl_scalar = $coder->decode ($unicode_json_text);
20 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
21=head1 DESCRIPTION 32=head1 DESCRIPTION
22 33
23This module converts Perl data structures to JSON and vice versa. Its 34This 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 35primary 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. 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.
26 45
27As 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
28to 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
29modules, 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
30their maintainers are unresponsive, gone missing, or not listening to bug 49their maintainers are unresponsive, gone missing, or not listening to bug
37 56
38=head2 FEATURES 57=head2 FEATURES
39 58
40=over 4 59=over 4
41 60
42=item * correct unicode handling 61=item * correct Unicode handling
43 62
44This 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
45it does so. 64it does so.
46 65
47=item * round-trip integrity 66=item * round-trip integrity
67This 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
68interface. 87interface.
69 88
70=item * reasonably versatile output formats 89=item * reasonably versatile output formats
71 90
72You can choose between the most compact guarenteed single-line format 91You can choose between the most compact guaranteed single-line format
73possible (nice for simple line-based protocols), a pure-ascii format 92possible (nice for simple line-based protocols), a pure-ascii format
74(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
75unicode 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
76stuff). Or you can combine those features in whatever way you like. 95stuff). Or you can combine those features in whatever way you like.
77 96
78=back 97=back
79 98
80=cut 99=cut
81 100
82package JSON::XS; 101package JSON::XS;
83 102
84use strict; 103use strict;
85 104
86our $VERSION = '1.5'; 105our $VERSION = '2.0';
87our @ISA = qw(Exporter); 106our @ISA = qw(Exporter);
88 107
89our @EXPORT = qw(to_json from_json); 108our @EXPORT = qw(to_json from_json);
90 109
91use Exporter; 110use Exporter;
92use XSLoader; 111use XSLoader;
93 112
94=head1 FUNCTIONAL INTERFACE 113=head1 FUNCTIONAL INTERFACE
95 114
96The following convinience methods are provided by this module. They are 115The following convenience methods are provided by this module. They are
97exported by default: 116exported by default:
98 117
99=over 4 118=over 4
100 119
101=item $json_text = to_json $perl_scalar 120=item $json_text = to_json $perl_scalar
102 121
103Converts the given Perl data structure (a simple scalar or a reference to 122Converts 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 123(that is, the string contains octets only). Croaks on error.
105octets only). Croaks on error.
106 124
107This function call is functionally identical to: 125This function call is functionally identical to:
108 126
109 $json_text = JSON::XS->new->utf8->encode ($perl_scalar) 127 $json_text = JSON::XS->new->utf8->encode ($perl_scalar)
110 128
111except being faster. 129except being faster.
112 130
113=item $perl_scalar = from_json $json_text 131=item $perl_scalar = from_json $json_text
114 132
115The opposite of C<to_json>: expects an UTF-8 (binary) string and tries to 133The opposite of C<to_json>: expects an UTF-8 (binary) string and tries
116parse that as an UTF-8 encoded JSON text, returning the resulting simple 134to parse that as an UTF-8 encoded JSON text, returning the resulting
117scalar or reference. Croaks on error. 135reference. Croaks on error.
118 136
119This function call is functionally identical to: 137This function call is functionally identical to:
120 138
121 $perl_scalar = JSON::XS->new->utf8->decode ($json_text) 139 $perl_scalar = JSON::XS->new->utf8->decode ($json_text)
122 140
132Perl. 150Perl.
133 151
134=back 152=back
135 153
136 154
155=head1 A FEW NOTES ON UNICODE AND PERL
156
157Since this often leads to confusion, here are a few very clear words on
158how Unicode works in Perl, modulo bugs.
159
160=over 4
161
162=item 1. Perl strings can store characters with ordinal values > 255.
163
164This enables you to store Unicode characters as single characters in a
165Perl string - very natural.
166
167=item 2. Perl does I<not> associate an encoding with your strings.
168
169Unless you force it to, e.g. when matching it against a regex, or printing
170the scalar to a file, in which case Perl either interprets your string as
171locale-encoded text, octets/binary, or as Unicode, depending on various
172settings. In no case is an encoding stored together with your data, it is
173I<use> that decides encoding, not any magical metadata.
174
175=item 3. The internal utf-8 flag has no meaning with regards to the
176encoding of your string.
177
178Just ignore that flag unless you debug a Perl bug, a module written in
179XS or want to dive into the internals of perl. Otherwise it will only
180confuse you, as, despite the name, it says nothing about how your string
181is encoded. You can have Unicode strings with that flag set, with that
182flag clear, and you can have binary data with that flag set and that flag
183clear. Other possibilities exist, too.
184
185If you didn't know about that flag, just the better, pretend it doesn't
186exist.
187
188=item 4. A "Unicode String" is simply a string where each character can be
189validly interpreted as a Unicode codepoint.
190
191If you have UTF-8 encoded data, it is no longer a Unicode string, but a
192Unicode string encoded in UTF-8, giving you a binary string.
193
194=item 5. A string containing "high" (> 255) character values is I<not> a UTF-8 string.
195
196It's a fact. Learn to live with it.
197
198=back
199
200I hope this helps :)
201
202
137=head1 OBJECT-ORIENTED INTERFACE 203=head1 OBJECT-ORIENTED INTERFACE
138 204
139The object oriented interface lets you configure your own encoding or 205The object oriented interface lets you configure your own encoding or
140decoding style, within the limits of supported formats. 206decoding style, within the limits of supported formats.
141 207
152 my $json = JSON::XS->new->utf8->space_after->encode ({a => [1,2]}) 218 my $json = JSON::XS->new->utf8->space_after->encode ({a => [1,2]})
153 => {"a": [1, 2]} 219 => {"a": [1, 2]}
154 220
155=item $json = $json->ascii ([$enable]) 221=item $json = $json->ascii ([$enable])
156 222
223=item $enabled = $json->get_ascii
224
157If C<$enable> is true (or missing), then the C<encode> method will not 225If 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 226generate characters outside the code range C<0..127> (which is ASCII). Any
159unicode characters outside that range will be escaped using either a 227Unicode characters outside that range will be escaped using either a
160single \uXXXX (BMP characters) or a double \uHHHH\uLLLLL escape sequence, 228single \uXXXX (BMP characters) or a double \uHHHH\uLLLLL escape sequence,
161as per RFC4627. The resulting encoded JSON text can be treated as a native 229as 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, 230Unicode string, an ascii-encoded, latin1-encoded or UTF-8 encoded string,
163or any other superset of ASCII. 231or any other superset of ASCII.
164 232
165If C<$enable> is false, then the C<encode> method will not escape Unicode 233If 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 234characters unless required by the JSON syntax or other flags. This results
167in a faster and more compact format. 235in a faster and more compact format.
173 JSON::XS->new->ascii (1)->encode ([chr 0x10401]) 241 JSON::XS->new->ascii (1)->encode ([chr 0x10401])
174 => ["\ud801\udc01"] 242 => ["\ud801\udc01"]
175 243
176=item $json = $json->latin1 ([$enable]) 244=item $json = $json->latin1 ([$enable])
177 245
246=item $enabled = $json->get_latin1
247
178If C<$enable> is true (or missing), then the C<encode> method will encode 248If 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 249the 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 250outside 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 251latin1-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 252will not be affected in any way by this flag, as C<decode> by default
183expects unicode, which is a strict superset of latin1. 253expects Unicode, which is a strict superset of latin1.
184 254
185If C<$enable> is false, then the C<encode> method will not escape Unicode 255If C<$enable> is false, then the C<encode> method will not escape Unicode
186characters unless required by the JSON syntax or other flags. 256characters unless required by the JSON syntax or other flags.
187 257
188The main use for this flag is efficiently encoding binary data as JSON 258The 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 259text, as most octets will not be escaped, resulting in a smaller encoded
190size. The disadvantage is that the resulting JSON text is encoded 260size. The disadvantage is that the resulting JSON text is encoded
191in latin1 (and must correctly be treated as such when storing and 261in latin1 (and must correctly be treated as such when storing and
192transfering), a rare encoding for JSON. It is therefore most useful when 262transferring), a rare encoding for JSON. It is therefore most useful when
193you want to store data structures known to contain binary data efficiently 263you want to store data structures known to contain binary data efficiently
194in files or databases, not when talking to other JSON encoders/decoders. 264in files or databases, not when talking to other JSON encoders/decoders.
195 265
196 JSON::XS->new->latin1->encode (["\x{89}\x{abc}"] 266 JSON::XS->new->latin1->encode (["\x{89}\x{abc}"]
197 => ["\x{89}\\u0abc"] # (perl syntax, U+abc escaped, U+89 not) 267 => ["\x{89}\\u0abc"] # (perl syntax, U+abc escaped, U+89 not)
198 268
199=item $json = $json->utf8 ([$enable]) 269=item $json = $json->utf8 ([$enable])
270
271=item $enabled = $json->get_utf8
200 272
201If C<$enable> is true (or missing), then the C<encode> method will encode 273If C<$enable> is true (or missing), then the C<encode> method will encode
202the JSON result into UTF-8, as required by many protocols, while the 274the 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 275C<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 276note 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 277range 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 278versions, enabling this option might enable autodetection of the UTF-16
207and UTF-32 encoding families, as described in RFC4627. 279and UTF-32 encoding families, as described in RFC4627.
208 280
209If C<$enable> is false, then the C<encode> method will return the JSON 281If C<$enable> is false, then the C<encode> method will return the JSON
210string as a (non-encoded) unicode string, while C<decode> expects thus a 282string as a (non-encoded) Unicode string, while C<decode> expects thus a
211unicode string. Any decoding or encoding (e.g. to UTF-8 or UTF-16) needs 283Unicode string. Any decoding or encoding (e.g. to UTF-8 or UTF-16) needs
212to be done yourself, e.g. using the Encode module. 284to be done yourself, e.g. using the Encode module.
213 285
214Example, output UTF-16BE-encoded JSON: 286Example, output UTF-16BE-encoded JSON:
215 287
216 use Encode; 288 use Encode;
238 ] 310 ]
239 } 311 }
240 312
241=item $json = $json->indent ([$enable]) 313=item $json = $json->indent ([$enable])
242 314
315=item $enabled = $json->get_indent
316
243If C<$enable> is true (or missing), then the C<encode> method will use a multiline 317If 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 318format as output, putting every array member or object/hash key-value pair
245into its own line, identing them properly. 319into its own line, indenting them properly.
246 320
247If C<$enable> is false, no newlines or indenting will be produced, and the 321If C<$enable> is false, no newlines or indenting will be produced, and the
248resulting JSON text is guarenteed not to contain any C<newlines>. 322resulting JSON text is guaranteed not to contain any C<newlines>.
249 323
250This setting has no effect when decoding JSON texts. 324This setting has no effect when decoding JSON texts.
251 325
252=item $json = $json->space_before ([$enable]) 326=item $json = $json->space_before ([$enable])
327
328=item $enabled = $json->get_space_before
253 329
254If C<$enable> is true (or missing), then the C<encode> method will add an extra 330If 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. 331optional space before the C<:> separating keys from values in JSON objects.
256 332
257If C<$enable> is false, then the C<encode> method will not add any extra 333If C<$enable> is false, then the C<encode> method will not add any extra
263Example, space_before enabled, space_after and indent disabled: 339Example, space_before enabled, space_after and indent disabled:
264 340
265 {"key" :"value"} 341 {"key" :"value"}
266 342
267=item $json = $json->space_after ([$enable]) 343=item $json = $json->space_after ([$enable])
344
345=item $enabled = $json->get_space_after
268 346
269If C<$enable> is true (or missing), then the C<encode> method will add an extra 347If 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 348optional space after the C<:> separating keys from values in JSON objects
271and extra whitespace after the C<,> separating key-value pairs and array 349and extra whitespace after the C<,> separating key-value pairs and array
272members. 350members.
279Example, space_before and indent disabled, space_after enabled: 357Example, space_before and indent disabled, space_after enabled:
280 358
281 {"key": "value"} 359 {"key": "value"}
282 360
283=item $json = $json->relaxed ([$enable]) 361=item $json = $json->relaxed ([$enable])
362
363=item $enabled = $json->get_relaxed
284 364
285If C<$enable> is true (or missing), then C<decode> will accept some 365If C<$enable> is true (or missing), then C<decode> will accept some
286extensions to normal JSON syntax (see below). C<encode> will not be 366extensions to normal JSON syntax (see below). C<encode> will not be
287affected in anyway. I<Be aware that this option makes you accept invalid 367affected in anyway. I<Be aware that this option makes you accept invalid
288JSON texts as if they were valid!>. I suggest only to use this option to 368JSON texts as if they were valid!>. I suggest only to use this option to
325 405
326=back 406=back
327 407
328=item $json = $json->canonical ([$enable]) 408=item $json = $json->canonical ([$enable])
329 409
410=item $enabled = $json->get_canonical
411
330If C<$enable> is true (or missing), then the C<encode> method will output JSON objects 412If C<$enable> is true (or missing), then the C<encode> method will output JSON objects
331by sorting their keys. This is adding a comparatively high overhead. 413by sorting their keys. This is adding a comparatively high overhead.
332 414
333If C<$enable> is false, then the C<encode> method will output key-value 415If C<$enable> is false, then the C<encode> method will output key-value
334pairs in the order Perl stores them (which will likely change between runs 416pairs in the order Perl stores them (which will likely change between runs
335of the same script). 417of the same script).
336 418
337This option is useful if you want the same data structure to be encoded as 419This option is useful if you want the same data structure to be encoded as
338the same JSON text (given the same overall settings). If it is disabled, 420the same JSON text (given the same overall settings). If it is disabled,
339the same hash migh be encoded differently even if contains the same data, 421the same hash might be encoded differently even if contains the same data,
340as key-value pairs have no inherent ordering in Perl. 422as key-value pairs have no inherent ordering in Perl.
341 423
342This setting has no effect when decoding JSON texts. 424This setting has no effect when decoding JSON texts.
343 425
344=item $json = $json->allow_nonref ([$enable]) 426=item $json = $json->allow_nonref ([$enable])
427
428=item $enabled = $json->get_allow_nonref
345 429
346If C<$enable> is true (or missing), then the C<encode> method can convert a 430If C<$enable> is true (or missing), then the C<encode> method can convert a
347non-reference into its corresponding string, number or null JSON value, 431non-reference into its corresponding string, number or null JSON value,
348which is an extension to RFC4627. Likewise, C<decode> will accept those JSON 432which is an extension to RFC4627. Likewise, C<decode> will accept those JSON
349values instead of croaking. 433values instead of croaking.
359 JSON::XS->new->allow_nonref->encode ("Hello, World!") 443 JSON::XS->new->allow_nonref->encode ("Hello, World!")
360 => "Hello, World!" 444 => "Hello, World!"
361 445
362=item $json = $json->allow_blessed ([$enable]) 446=item $json = $json->allow_blessed ([$enable])
363 447
448=item $enabled = $json->get_allow_blessed
449
364If C<$enable> is true (or missing), then the C<encode> method will not 450If C<$enable> is true (or missing), then the C<encode> method will not
365barf when it encounters a blessed reference. Instead, the value of the 451barf when it encounters a blessed reference. Instead, the value of the
366B<convert_blessed> option will decide wether C<null> (C<convert_blessed> 452B<convert_blessed> option will decide whether C<null> (C<convert_blessed>
367disabled or no C<to_json> method found) or a representation of the 453disabled or no C<TO_JSON> method found) or a representation of the
368object (C<convert_blessed> enabled and C<to_json> method found) is being 454object (C<convert_blessed> enabled and C<TO_JSON> method found) is being
369encoded. Has no effect on C<decode>. 455encoded. Has no effect on C<decode>.
370 456
371If C<$enable> is false (the default), then C<encode> will throw an 457If C<$enable> is false (the default), then C<encode> will throw an
372exception when it encounters a blessed object. 458exception when it encounters a blessed object.
373 459
374=item $json = $json->convert_blessed ([$enable]) 460=item $json = $json->convert_blessed ([$enable])
461
462=item $enabled = $json->get_convert_blessed
375 463
376If C<$enable> is true (or missing), then C<encode>, upon encountering a 464If C<$enable> is true (or missing), then C<encode>, upon encountering a
377blessed object, will check for the availability of the C<TO_JSON> method 465blessed object, will check for the availability of the C<TO_JSON> method
378on the object's class. If found, it will be called in scalar context 466on the object's class. If found, it will be called in scalar context
379and the resulting scalar will be encoded instead of the object. If no 467and the resulting scalar will be encoded instead of the object. If no
436 524
437As this callback gets called less often then the C<filter_json_object> 525As this callback gets called less often then the C<filter_json_object>
438one, decoding speed will not usually suffer as much. Therefore, single-key 526one, decoding speed will not usually suffer as much. Therefore, single-key
439objects make excellent targets to serialise Perl objects into, especially 527objects make excellent targets to serialise Perl objects into, especially
440as single-key JSON objects are as close to the type-tagged value concept 528as single-key JSON objects are as close to the type-tagged value concept
441as JSON gets (its basically an ID/VALUE tuple). Of course, JSON does not 529as JSON gets (it's basically an ID/VALUE tuple). Of course, JSON does not
442support this in any way, so you need to make sure your data never looks 530support this in any way, so you need to make sure your data never looks
443like a serialised Perl hash. 531like a serialised Perl hash.
444 532
445Typical names for the single object key are C<__class_whatever__>, or 533Typical names for the single object key are C<__class_whatever__>, or
446C<$__dollars_are_rarely_used__$> or C<}ugly_brace_placement>, or even 534C<$__dollars_are_rarely_used__$> or C<}ugly_brace_placement>, or even
470 558
471 { __widget__ => $self->{id} } 559 { __widget__ => $self->{id} }
472 } 560 }
473 561
474=item $json = $json->shrink ([$enable]) 562=item $json = $json->shrink ([$enable])
563
564=item $enabled = $json->get_shrink
475 565
476Perl usually over-allocates memory a bit when allocating space for 566Perl usually over-allocates memory a bit when allocating space for
477strings. This flag optionally resizes strings generated by either 567strings. This flag optionally resizes strings generated by either
478C<encode> or C<decode> to their minimum size possible. This can save 568C<encode> or C<decode> to their minimum size possible. This can save
479memory when your JSON texts are either very very long or you have many 569memory when your JSON texts are either very very long or you have many
497strings that look like integers or floats into integers or floats 587strings that look like integers or floats into integers or floats
498internally (there is no difference on the Perl level), saving space. 588internally (there is no difference on the Perl level), saving space.
499 589
500=item $json = $json->max_depth ([$maximum_nesting_depth]) 590=item $json = $json->max_depth ([$maximum_nesting_depth])
501 591
592=item $max_depth = $json->get_max_depth
593
502Sets the maximum nesting level (default C<512>) accepted while encoding 594Sets the maximum nesting level (default C<512>) accepted while encoding
503or decoding. If the JSON text or Perl data structure has an equal or 595or decoding. If the JSON text or Perl data structure has an equal or
504higher nesting level then this limit, then the encoder and decoder will 596higher nesting level then this limit, then the encoder and decoder will
505stop and croak at that point. 597stop and croak at that point.
506 598
517used, which is rarely useful. 609used, which is rarely useful.
518 610
519See SECURITY CONSIDERATIONS, below, for more info on why this is useful. 611See SECURITY CONSIDERATIONS, below, for more info on why this is useful.
520 612
521=item $json = $json->max_size ([$maximum_string_size]) 613=item $json = $json->max_size ([$maximum_string_size])
614
615=item $max_size = $json->get_max_size
522 616
523Set the maximum length a JSON text may have (in bytes) where decoding is 617Set the maximum length a JSON text may have (in bytes) where decoding is
524being attempted. The default is C<0>, meaning no limit. When C<decode> 618being attempted. The default is C<0>, meaning no limit. When C<decode>
525is called on a string longer then this number of characters it will not 619is called on a string longer then this number of characters it will not
526attempt to decode the string but throw an exception. This setting has no 620attempt to decode the string but throw an exception. This setting has no
573vice versa. These mappings are designed to "do the right thing" in most 667vice versa. These mappings are designed to "do the right thing" in most
574circumstances automatically, preserving round-tripping characteristics 668circumstances automatically, preserving round-tripping characteristics
575(what you put in comes out as something equivalent). 669(what you put in comes out as something equivalent).
576 670
577For the more enlightened: note that in the following descriptions, 671For the more enlightened: note that in the following descriptions,
578lowercase I<perl> refers to the Perl interpreter, while uppcercase I<Perl> 672lowercase I<perl> refers to the Perl interpreter, while uppercase I<Perl>
579refers to the abstract Perl language itself. 673refers to the abstract Perl language itself.
580 674
581 675
582=head2 JSON -> PERL 676=head2 JSON -> PERL
583 677
584=over 4 678=over 4
585 679
586=item object 680=item object
587 681
588A JSON object becomes a reference to a hash in Perl. No ordering of object 682A JSON object becomes a reference to a hash in Perl. No ordering of object
589keys is preserved (JSON does not preserver object key ordering itself). 683keys is preserved (JSON does not preserve object key ordering itself).
590 684
591=item array 685=item array
592 686
593A JSON array becomes a reference to an array in Perl. 687A JSON array becomes a reference to an array in Perl.
594 688
620 714
621=item true, false 715=item true, false
622 716
623These JSON atoms become C<JSON::XS::true> and C<JSON::XS::false>, 717These JSON atoms become C<JSON::XS::true> and C<JSON::XS::false>,
624respectively. They are overloaded to act almost exactly like the numbers 718respectively. They are overloaded to act almost exactly like the numbers
625C<1> and C<0>. You can check wether a scalar is a JSON boolean by using 719C<1> and C<0>. You can check whether a scalar is a JSON boolean by using
626the C<JSON::XS::is_bool> function. 720the C<JSON::XS::is_bool> function.
627 721
628=item null 722=item null
629 723
630A JSON null atom becomes C<undef> in Perl. 724A JSON null atom becomes C<undef> in Perl.
666 to_json [\0,JSON::XS::true] # yields [false,true] 760 to_json [\0,JSON::XS::true] # yields [false,true]
667 761
668=item JSON::XS::true, JSON::XS::false 762=item JSON::XS::true, JSON::XS::false
669 763
670These special values become JSON true and JSON false values, 764These special values become JSON true and JSON false values,
671respectively. You cna alos use C<\1> and C<\0> directly if you want. 765respectively. You can also use C<\1> and C<\0> directly if you want.
672 766
673=item blessed objects 767=item blessed objects
674 768
675Blessed objects are not allowed. JSON::XS currently tries to encode their 769Blessed objects are not allowed. JSON::XS currently tries to encode their
676underlying representation (hash- or arrayref), but this behaviour might 770underlying representation (hash- or arrayref), but this behaviour might
693 to_json [$value] # yields ["5"] 787 to_json [$value] # yields ["5"]
694 788
695 # undef becomes null 789 # undef becomes null
696 to_json [undef] # yields [null] 790 to_json [undef] # yields [null]
697 791
698You can force the type to be a string by stringifying it: 792You can force the type to be a JSON string by stringifying it:
699 793
700 my $x = 3.1; # some variable containing a number 794 my $x = 3.1; # some variable containing a number
701 "$x"; # stringified 795 "$x"; # stringified
702 $x .= ""; # another, more awkward way to stringify 796 $x .= ""; # another, more awkward way to stringify
703 print $x; # perl does it for you, too, quite often 797 print $x; # perl does it for you, too, quite often
704 798
705You can force the type to be a number by numifying it: 799You can force the type to be a JSON number by numifying it:
706 800
707 my $x = "3"; # some variable containing a string 801 my $x = "3"; # some variable containing a string
708 $x += 0; # numify it, ensuring it will be dumped as a number 802 $x += 0; # numify it, ensuring it will be dumped as a number
709 $x *= 1; # same thing, the choise is yours. 803 $x *= 1; # same thing, the choice is yours.
710 804
711You can not currently output JSON booleans or force the type in other, 805You can not currently force the type in other, less obscure, ways. Tell me
712less obscure, ways. Tell me if you need this capability. 806if you need this capability.
713 807
714=back 808=back
715 809
716 810
717=head1 COMPARISON 811=head1 COMPARISON
726 820
727=item JSON 1.07 821=item JSON 1.07
728 822
729Slow (but very portable, as it is written in pure Perl). 823Slow (but very portable, as it is written in pure Perl).
730 824
731Undocumented/buggy Unicode handling (how JSON handles unicode values is 825Undocumented/buggy Unicode handling (how JSON handles Unicode values is
732undocumented. One can get far by feeding it unicode strings and doing 826undocumented. One can get far by feeding it Unicode strings and doing
733en-/decoding oneself, but unicode escapes are not working properly). 827en-/decoding oneself, but Unicode escapes are not working properly).
734 828
735No roundtripping (strings get clobbered if they look like numbers, e.g. 829No round-tripping (strings get clobbered if they look like numbers, e.g.
736the string C<2.0> will encode to C<2.0> instead of C<"2.0">, and that will 830the string C<2.0> will encode to C<2.0> instead of C<"2.0">, and that will
737decode into the number 2. 831decode into the number 2.
738 832
739=item JSON::PC 0.01 833=item JSON::PC 0.01
740 834
741Very fast. 835Very fast.
742 836
743Undocumented/buggy Unicode handling. 837Undocumented/buggy Unicode handling.
744 838
745No roundtripping. 839No round-tripping.
746 840
747Has problems handling many Perl values (e.g. regex results and other magic 841Has problems handling many Perl values (e.g. regex results and other magic
748values will make it croak). 842values will make it croak).
749 843
750Does not even generate valid JSON (C<{1,2}> gets converted to C<{1:2}> 844Does not even generate valid JSON (C<{1,2}> gets converted to C<{1:2}>
760Very inflexible (no human-readable format supported, format pretty much 854Very inflexible (no human-readable format supported, format pretty much
761undocumented. I need at least a format for easy reading by humans and a 855undocumented. I need at least a format for easy reading by humans and a
762single-line compact format for use in a protocol, and preferably a way to 856single-line compact format for use in a protocol, and preferably a way to
763generate ASCII-only JSON texts). 857generate ASCII-only JSON texts).
764 858
765Completely broken (and confusingly documented) Unicode handling (unicode 859Completely broken (and confusingly documented) Unicode handling (Unicode
766escapes are not working properly, you need to set ImplicitUnicode to 860escapes are not working properly, you need to set ImplicitUnicode to
767I<different> values on en- and decoding to get symmetric behaviour). 861I<different> values on en- and decoding to get symmetric behaviour).
768 862
769No roundtripping (simple cases work, but this depends on wether the scalar 863No round-tripping (simple cases work, but this depends on whether the scalar
770value was used in a numeric context or not). 864value was used in a numeric context or not).
771 865
772Dumping hashes may skip hash values depending on iterator state. 866Dumping hashes may skip hash values depending on iterator state.
773 867
774Unmaintained (maintainer unresponsive for many months, bugs are not 868Unmaintained (maintainer unresponsive for many months, bugs are not
775getting fixed). 869getting fixed).
776 870
777Does not check input for validity (i.e. will accept non-JSON input and 871Does not check input for validity (i.e. will accept non-JSON input and
778return "something" instead of raising an exception. This is a security 872return "something" instead of raising an exception. This is a security
779issue: imagine two banks transfering money between each other using 873issue: imagine two banks transferring money between each other using
780JSON. One bank might parse a given non-JSON request and deduct money, 874JSON. One bank might parse a given non-JSON request and deduct money,
781while the other might reject the transaction with a syntax error. While a 875while the other might reject the transaction with a syntax error. While a
782good protocol will at least recover, that is extra unnecessary work and 876good protocol will at least recover, that is extra unnecessary work and
783the transaction will still not succeed). 877the transaction will still not succeed).
784 878
785=item JSON::DWIW 0.04 879=item JSON::DWIW 0.04
786 880
787Very fast. Very natural. Very nice. 881Very fast. Very natural. Very nice.
788 882
789Undocumented unicode handling (but the best of the pack. Unicode escapes 883Undocumented Unicode handling (but the best of the pack. Unicode escapes
790still don't get parsed properly). 884still don't get parsed properly).
791 885
792Very inflexible. 886Very inflexible.
793 887
794No roundtripping. 888No round-tripping.
795 889
796Does not generate valid JSON texts (key strings are often unquoted, empty keys 890Does not generate valid JSON texts (key strings are often unquoted, empty keys
797result in nothing being output) 891result in nothing being output)
798 892
799Does not check input for validity. 893Does not check input for validity.
814 my $yaml = $to_yaml->encode ($ref) . "\n"; 908 my $yaml = $to_yaml->encode ($ref) . "\n";
815 909
816This will usually generate JSON texts that also parse as valid 910This will usually generate JSON texts that also parse as valid
817YAML. Please note that YAML has hardcoded limits on (simple) object key 911YAML. Please note that YAML has hardcoded limits on (simple) object key
818lengths that JSON doesn't have, so you should make sure that your hash 912lengths that JSON doesn't have, so you should make sure that your hash
819keys are noticably shorter than the 1024 characters YAML allows. 913keys are noticeably shorter than the 1024 characters YAML allows.
820 914
821There might be other incompatibilities that I am not aware of. In general 915There might be other incompatibilities that I am not aware of. In general
822you should not try to generate YAML with a JSON generator or vice versa, 916you should not try to generate YAML with a JSON generator or vice versa,
823or try to parse JSON with a YAML parser or vice versa: chances are high 917or try to parse JSON with a YAML parser or vice versa: chances are high
824that you will run into severe interoperability problems. 918that you will run into severe interoperability problems.
840It shows the number of encodes/decodes per second (JSON::XS uses 934It shows the number of encodes/decodes per second (JSON::XS uses
841the functional interface, while JSON::XS/2 uses the OO interface 935the functional interface, while JSON::XS/2 uses the OO interface
842with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables 936with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables
843shrink). Higher is better: 937shrink). Higher is better:
844 938
845 Storable | 15779.925 | 14169.946 |
846 -----------+------------+------------+
847 module | encode | decode | 939 module | encode | decode |
848 -----------|------------|------------| 940 -----------|------------|------------|
849 JSON | 4990.842 | 4088.813 | 941 JSON 1.x | 4990.842 | 4088.813 |
850 JSON::DWIW | 51653.990 | 71575.154 | 942 JSON::DWIW | 51653.990 | 71575.154 |
851 JSON::PC | 65948.176 | 74631.744 | 943 JSON::PC | 65948.176 | 74631.744 |
852 JSON::PP | 8931.652 | 3817.168 | 944 JSON::PP | 8931.652 | 3817.168 |
853 JSON::Syck | 24877.248 | 27776.848 | 945 JSON::Syck | 24877.248 | 27776.848 |
854 JSON::XS | 388361.481 | 227951.304 | 946 JSON::XS | 388361.481 | 227951.304 |
856 JSON::XS/3 | 338250.323 | 218453.333 | 948 JSON::XS/3 | 338250.323 | 218453.333 |
857 Storable | 16500.016 | 135300.129 | 949 Storable | 16500.016 | 135300.129 |
858 -----------+------------+------------+ 950 -----------+------------+------------+
859 951
860That is, JSON::XS is about five times faster than JSON::DWIW on encoding, 952That is, JSON::XS is about five times faster than JSON::DWIW on encoding,
861about three times faster on decoding, and over fourty times faster 953about three times faster on decoding, and over forty times faster
862than JSON, even with pretty-printing and key sorting. It also compares 954than JSON, even with pretty-printing and key sorting. It also compares
863favourably to Storable for small amounts of data. 955favourably to Storable for small amounts of data.
864 956
865Using a longer test string (roughly 18KB, generated from Yahoo! Locals 957Using a longer test string (roughly 18KB, generated from Yahoo! Locals
866search API (http://nanoref.com/yahooapis/mgPdGg): 958search API (http://nanoref.com/yahooapis/mgPdGg):
867 959
868 module | encode | decode | 960 module | encode | decode |
869 -----------|------------|------------| 961 -----------|------------|------------|
870 JSON | 55.260 | 34.971 | 962 JSON 1.x | 55.260 | 34.971 |
871 JSON::DWIW | 825.228 | 1082.513 | 963 JSON::DWIW | 825.228 | 1082.513 |
872 JSON::PC | 3571.444 | 2394.829 | 964 JSON::PC | 3571.444 | 2394.829 |
873 JSON::PP | 210.987 | 32.574 | 965 JSON::PP | 210.987 | 32.574 |
874 JSON::Syck | 552.551 | 787.544 | 966 JSON::Syck | 552.551 | 787.544 |
875 JSON::XS | 5780.463 | 4854.519 | 967 JSON::XS | 5780.463 | 4854.519 |
879 -----------+------------+------------+ 971 -----------+------------+------------+
880 972
881Again, JSON::XS leads by far (except for Storable which non-surprisingly 973Again, JSON::XS leads by far (except for Storable which non-surprisingly
882decodes faster). 974decodes faster).
883 975
884On large strings containing lots of high unicode characters, some modules 976On large strings containing lots of high Unicode characters, some modules
885(such as JSON::PC) seem to decode faster than JSON::XS, but the result 977(such as JSON::PC) seem to decode faster than JSON::XS, but the result
886will be broken due to missing (or wrong) unicode handling. Others refuse 978will be broken due to missing (or wrong) Unicode handling. Others refuse
887to decode or encode properly, so it was impossible to prepare a fair 979to decode or encode properly, so it was impossible to prepare a fair
888comparison table for that case. 980comparison table for that case.
889 981
890 982
891=head1 SECURITY CONSIDERATIONS 983=head1 SECURITY CONSIDERATIONS
897any buffer overflows. Obviously, this module should ensure that and I am 989any buffer overflows. Obviously, this module should ensure that and I am
898trying hard on making that true, but you never know. 990trying hard on making that true, but you never know.
899 991
900Second, you need to avoid resource-starving attacks. That means you should 992Second, you need to avoid resource-starving attacks. That means you should
901limit the size of JSON texts you accept, or make sure then when your 993limit the size of JSON texts you accept, or make sure then when your
902resources run out, thats just fine (e.g. by using a separate process that 994resources run out, that's just fine (e.g. by using a separate process that
903can crash safely). The size of a JSON text in octets or characters is 995can crash safely). The size of a JSON text in octets or characters is
904usually a good indication of the size of the resources required to decode 996usually a good indication of the size of the resources required to decode
905it into a Perl structure. While JSON::XS can check the size of the JSON 997it into a Perl structure. While JSON::XS can check the size of the JSON
906text, it might be too late when you already have it in memory, so you 998text, it might be too late when you already have it in memory, so you
907might want to check the size before you accept the string. 999might want to check the size before you accept the string.
918And last but least, something else could bomb you that I forgot to think 1010And last but least, something else could bomb you that I forgot to think
919of. In that case, you get to keep the pieces. I am always open for hints, 1011of. In that case, you get to keep the pieces. I am always open for hints,
920though... 1012though...
921 1013
922If you are using JSON::XS to return packets to consumption 1014If you are using JSON::XS to return packets to consumption
923by javascript scripts in a browser you should have a look at 1015by JavaScript scripts in a browser you should have a look at
924L<http://jpsykes.com/47/practical-csrf-and-json-security> to see wether 1016L<http://jpsykes.com/47/practical-csrf-and-json-security> to see whether
925you are vulnerable to some common attack vectors (which really are browser 1017you are vulnerable to some common attack vectors (which really are browser
926design bugs, but it is still you who will have to deal with it, as major 1018design bugs, but it is still you who will have to deal with it, as major
927browser developers care only for features, not about doing security 1019browser developers care only for features, not about doing security
928right). 1020right).
929 1021
930 1022
1023=head1 THREADS
1024
1025This module is I<not> guaranteed to be thread safe and there are no
1026plans to change this until Perl gets thread support (as opposed to the
1027horribly slow so-called "threads" which are simply slow and bloated
1028process simulations - use fork, its I<much> faster, cheaper, better).
1029
1030(It might actually work, but you have been warned).
1031
1032
931=head1 BUGS 1033=head1 BUGS
932 1034
933While the goal of this module is to be correct, that unfortunately does 1035While the goal of this module is to be correct, that unfortunately does
934not mean its bug-free, only that I think its design is bug-free. It is 1036not mean its bug-free, only that I think its design is bug-free. It is
935still relatively early in its development. If you keep reporting bugs they 1037still relatively early in its development. If you keep reporting bugs they
936will be fixed swiftly, though. 1038will be fixed swiftly, though.
1039
1040Please refrain from using rt.cpan.org or any other bug reporting
1041service. I put the contact address into my modules for a reason.
937 1042
938=cut 1043=cut
939 1044
940our $true = do { bless \(my $dummy = 1), "JSON::XS::Boolean" }; 1045our $true = do { bless \(my $dummy = 1), "JSON::XS::Boolean" };
941our $false = do { bless \(my $dummy = 0), "JSON::XS::Boolean" }; 1046our $false = do { bless \(my $dummy = 0), "JSON::XS::Boolean" };

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines