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.44 by root, Mon Jun 25 04:08:17 2007 UTC vs.
Revision 1.70 by root, Tue Nov 13 22:59:08 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
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 = to_json $perl_hash_or_arrayref;
13 $perl_hash_or_arrayref = from_json $utf8_encoded_json_text; 16 $perl_hash_or_arrayref = from_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);
… …
41 40
42=head2 FEATURES 41=head2 FEATURES
43 42
44=over 4 43=over 4
45 44
46=item * correct unicode handling 45=item * correct Unicode handling
47 46
48This module knows how to handle Unicode, and even documents how and when 47This module knows how to handle Unicode, and even documents how and when
49it does so. 48it does so.
50 49
51=item * round-trip integrity 50=item * round-trip integrity
… …
71This module has both a simple functional interface as well as an OO 70This module has both a simple functional interface as well as an OO
72interface. 71interface.
73 72
74=item * reasonably versatile output formats 73=item * reasonably versatile output formats
75 74
76You can choose between the most compact guarenteed single-line format 75You can choose between the most compact guaranteed single-line format
77possible (nice for simple line-based protocols), a pure-ascii format 76possible (nice for simple line-based protocols), a pure-ascii format
78(for when your transport is not 8-bit clean, still supports the whole 77(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 78Unicode 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. 79stuff). Or you can combine those features in whatever way you like.
81 80
82=back 81=back
83 82
84=cut 83=cut
85 84
86package JSON::XS; 85package JSON::XS;
87 86
88use strict; 87use strict;
89 88
90our $VERSION = '1.4'; 89our $VERSION = '1.53';
91our @ISA = qw(Exporter); 90our @ISA = qw(Exporter);
92 91
93our @EXPORT = qw(to_json from_json objToJson jsonToObj); 92our @EXPORT = qw(to_json from_json);
94 93
95use Exporter; 94use Exporter;
96use XSLoader; 95use XSLoader;
97 96
98=head1 FUNCTIONAL INTERFACE 97=head1 FUNCTIONAL INTERFACE
99 98
100The following convinience methods are provided by this module. They are 99The following convenience methods are provided by this module. They are
101exported by default: 100exported by default:
102 101
103=over 4 102=over 4
104 103
105=item $json_text = to_json $perl_scalar 104=item $json_text = to_json $perl_scalar
106 105
107Converts the given Perl data structure (a simple scalar or a reference to 106Converts the given Perl data structure to a UTF-8 encoded, binary string
108a hash or array) to a UTF-8 encoded, binary string (that is, the string contains 107(that is, the string contains octets only). Croaks on error.
109octets only). Croaks on error.
110 108
111This function call is functionally identical to: 109This function call is functionally identical to:
112 110
113 $json_text = JSON::XS->new->utf8->encode ($perl_scalar) 111 $json_text = JSON::XS->new->utf8->encode ($perl_scalar)
114 112
115except being faster. 113except being faster.
116 114
117=item $perl_scalar = from_json $json_text 115=item $perl_scalar = from_json $json_text
118 116
119The opposite of C<to_json>: expects an UTF-8 (binary) string and tries to 117The opposite of C<to_json>: expects an UTF-8 (binary) string and tries
120parse that as an UTF-8 encoded JSON text, returning the resulting simple 118to parse that as an UTF-8 encoded JSON text, returning the resulting
121scalar or reference. Croaks on error. 119reference. Croaks on error.
122 120
123This function call is functionally identical to: 121This function call is functionally identical to:
124 122
125 $perl_scalar = JSON::XS->new->utf8->decode ($json_text) 123 $perl_scalar = JSON::XS->new->utf8->decode ($json_text)
126 124
… …
136Perl. 134Perl.
137 135
138=back 136=back
139 137
140 138
139=head1 A FEW NOTES ON UNICODE AND PERL
140
141Since this often leads to confusion, here are a few very clear words on
142how Unicode works in Perl, modulo bugs.
143
144=over 4
145
146=item 1. Perl strings can store characters with ordinal values > 255.
147
148This enables you to store Unicode characters as single characters in a
149Perl string - very natural.
150
151=item 2. Perl does I<not> associate an encoding with your strings.
152
153Unless you force it to, e.g. when matching it against a regex, or printing
154the scalar to a file, in which case Perl either interprets your string as
155locale-encoded text, octets/binary, or as Unicode, depending on various
156settings. In no case is an encoding stored together with your data, it is
157I<use> that decides encoding, not any magical metadata.
158
159=item 3. The internal utf-8 flag has no meaning with regards to the
160encoding of your string.
161
162Just ignore that flag unless you debug a Perl bug, a module written in
163XS or want to dive into the internals of perl. Otherwise it will only
164confuse you, as, despite the name, it says nothing about how your string
165is encoded. You can have Unicode strings with that flag set, with that
166flag clear, and you can have binary data with that flag set and that flag
167clear. Other possibilities exist, too.
168
169If you didn't know about that flag, just the better, pretend it doesn't
170exist.
171
172=item 4. A "Unicode String" is simply a string where each character can be
173validly interpreted as a Unicode codepoint.
174
175If you have UTF-8 encoded data, it is no longer a Unicode string, but a
176Unicode string encoded in UTF-8, giving you a binary string.
177
178=item 5. A string containing "high" (> 255) character values is I<not> a UTF-8 string.
179
180It's a fact. Learn to live with it.
181
182=back
183
184I hope this helps :)
185
186
141=head1 OBJECT-ORIENTED INTERFACE 187=head1 OBJECT-ORIENTED INTERFACE
142 188
143The object oriented interface lets you configure your own encoding or 189The object oriented interface lets you configure your own encoding or
144decoding style, within the limits of supported formats. 190decoding style, within the limits of supported formats.
145 191
… …
158 204
159=item $json = $json->ascii ([$enable]) 205=item $json = $json->ascii ([$enable])
160 206
161If C<$enable> is true (or missing), then the C<encode> method will not 207If C<$enable> is true (or missing), then the C<encode> method will not
162generate characters outside the code range C<0..127> (which is ASCII). Any 208generate characters outside the code range C<0..127> (which is ASCII). Any
163unicode characters outside that range will be escaped using either a 209Unicode characters outside that range will be escaped using either a
164single \uXXXX (BMP characters) or a double \uHHHH\uLLLLL escape sequence, 210single \uXXXX (BMP characters) or a double \uHHHH\uLLLLL escape sequence,
165as per RFC4627. The resulting encoded JSON text can be treated as a native 211as per RFC4627. The resulting encoded JSON text can be treated as a native
166unicode string, an ascii-encoded, latin1-encoded or UTF-8 encoded string, 212Unicode string, an ascii-encoded, latin1-encoded or UTF-8 encoded string,
167or any other superset of ASCII. 213or any other superset of ASCII.
168 214
169If C<$enable> is false, then the C<encode> method will not escape Unicode 215If C<$enable> is false, then the C<encode> method will not escape Unicode
170characters unless required by the JSON syntax or other flags. This results 216characters unless required by the JSON syntax or other flags. This results
171in a faster and more compact format. 217in a faster and more compact format.
… …
180=item $json = $json->latin1 ([$enable]) 226=item $json = $json->latin1 ([$enable])
181 227
182If C<$enable> is true (or missing), then the C<encode> method will encode 228If C<$enable> is true (or missing), then the C<encode> method will encode
183the resulting JSON text as latin1 (or iso-8859-1), escaping any characters 229the resulting JSON text as latin1 (or iso-8859-1), escaping any characters
184outside the code range C<0..255>. The resulting string can be treated as a 230outside the code range C<0..255>. The resulting string can be treated as a
185latin1-encoded JSON text or a native unicode string. The C<decode> method 231latin1-encoded JSON text or a native Unicode string. The C<decode> method
186will not be affected in any way by this flag, as C<decode> by default 232will not be affected in any way by this flag, as C<decode> by default
187expects unicode, which is a strict superset of latin1. 233expects Unicode, which is a strict superset of latin1.
188 234
189If C<$enable> is false, then the C<encode> method will not escape Unicode 235If C<$enable> is false, then the C<encode> method will not escape Unicode
190characters unless required by the JSON syntax or other flags. 236characters unless required by the JSON syntax or other flags.
191 237
192The main use for this flag is efficiently encoding binary data as JSON 238The main use for this flag is efficiently encoding binary data as JSON
193text, as most octets will not be escaped, resulting in a smaller encoded 239text, as most octets will not be escaped, resulting in a smaller encoded
194size. The disadvantage is that the resulting JSON text is encoded 240size. The disadvantage is that the resulting JSON text is encoded
195in latin1 (and must correctly be treated as such when storing and 241in latin1 (and must correctly be treated as such when storing and
196transfering), a rare encoding for JSON. It is therefore most useful when 242transferring), a rare encoding for JSON. It is therefore most useful when
197you want to store data structures known to contain binary data efficiently 243you want to store data structures known to contain binary data efficiently
198in files or databases, not when talking to other JSON encoders/decoders. 244in files or databases, not when talking to other JSON encoders/decoders.
199 245
200 JSON::XS->new->latin1->encode (["\x{89}\x{abc}"] 246 JSON::XS->new->latin1->encode (["\x{89}\x{abc}"]
201 => ["\x{89}\\u0abc"] # (perl syntax, U+abc escaped, U+89 not) 247 => ["\x{89}\\u0abc"] # (perl syntax, U+abc escaped, U+89 not)
… …
209range C<0..255>, they are thus useful for bytewise/binary I/O. In future 255range C<0..255>, they are thus useful for bytewise/binary I/O. In future
210versions, enabling this option might enable autodetection of the UTF-16 256versions, enabling this option might enable autodetection of the UTF-16
211and UTF-32 encoding families, as described in RFC4627. 257and UTF-32 encoding families, as described in RFC4627.
212 258
213If C<$enable> is false, then the C<encode> method will return the JSON 259If C<$enable> is false, then the C<encode> method will return the JSON
214string as a (non-encoded) unicode string, while C<decode> expects thus a 260string as a (non-encoded) Unicode string, while C<decode> expects thus a
215unicode string. Any decoding or encoding (e.g. to UTF-8 or UTF-16) needs 261Unicode string. Any decoding or encoding (e.g. to UTF-8 or UTF-16) needs
216to be done yourself, e.g. using the Encode module. 262to be done yourself, e.g. using the Encode module.
217 263
218Example, output UTF-16BE-encoded JSON: 264Example, output UTF-16BE-encoded JSON:
219 265
220 use Encode; 266 use Encode;
… …
244 290
245=item $json = $json->indent ([$enable]) 291=item $json = $json->indent ([$enable])
246 292
247If C<$enable> is true (or missing), then the C<encode> method will use a multiline 293If C<$enable> is true (or missing), then the C<encode> method will use a multiline
248format as output, putting every array member or object/hash key-value pair 294format as output, putting every array member or object/hash key-value pair
249into its own line, identing them properly. 295into its own line, indenting them properly.
250 296
251If C<$enable> is false, no newlines or indenting will be produced, and the 297If C<$enable> is false, no newlines or indenting will be produced, and the
252resulting JSON text is guarenteed not to contain any C<newlines>. 298resulting JSON text is guaranteed not to contain any C<newlines>.
253 299
254This setting has no effect when decoding JSON texts. 300This setting has no effect when decoding JSON texts.
255 301
256=item $json = $json->space_before ([$enable]) 302=item $json = $json->space_before ([$enable])
257 303
… …
282 328
283Example, space_before and indent disabled, space_after enabled: 329Example, space_before and indent disabled, space_after enabled:
284 330
285 {"key": "value"} 331 {"key": "value"}
286 332
333=item $json = $json->relaxed ([$enable])
334
335If C<$enable> is true (or missing), then C<decode> will accept some
336extensions to normal JSON syntax (see below). C<encode> will not be
337affected in anyway. I<Be aware that this option makes you accept invalid
338JSON texts as if they were valid!>. I suggest only to use this option to
339parse application-specific files written by humans (configuration files,
340resource files etc.)
341
342If C<$enable> is false (the default), then C<decode> will only accept
343valid JSON texts.
344
345Currently accepted extensions are:
346
347=over 4
348
349=item * list items can have an end-comma
350
351JSON I<separates> array elements and key-value pairs with commas. This
352can be annoying if you write JSON texts manually and want to be able to
353quickly append elements, so this extension accepts comma at the end of
354such items not just between them:
355
356 [
357 1,
358 2, <- this comma not normally allowed
359 ]
360 {
361 "k1": "v1",
362 "k2": "v2", <- this comma not normally allowed
363 }
364
365=item * shell-style '#'-comments
366
367Whenever JSON allows whitespace, shell-style comments are additionally
368allowed. They are terminated by the first carriage-return or line-feed
369character, after which more white-space and comments are allowed.
370
371 [
372 1, # this comment not allowed in JSON
373 # neither this one...
374 ]
375
376=back
377
287=item $json = $json->canonical ([$enable]) 378=item $json = $json->canonical ([$enable])
288 379
289If C<$enable> is true (or missing), then the C<encode> method will output JSON objects 380If C<$enable> is true (or missing), then the C<encode> method will output JSON objects
290by sorting their keys. This is adding a comparatively high overhead. 381by sorting their keys. This is adding a comparatively high overhead.
291 382
… …
293pairs in the order Perl stores them (which will likely change between runs 384pairs in the order Perl stores them (which will likely change between runs
294of the same script). 385of the same script).
295 386
296This option is useful if you want the same data structure to be encoded as 387This option is useful if you want the same data structure to be encoded as
297the same JSON text (given the same overall settings). If it is disabled, 388the same JSON text (given the same overall settings). If it is disabled,
298the same hash migh be encoded differently even if contains the same data, 389the same hash might be encoded differently even if contains the same data,
299as key-value pairs have no inherent ordering in Perl. 390as key-value pairs have no inherent ordering in Perl.
300 391
301This setting has no effect when decoding JSON texts. 392This setting has no effect when decoding JSON texts.
302 393
303=item $json = $json->allow_nonref ([$enable]) 394=item $json = $json->allow_nonref ([$enable])
… …
320 411
321=item $json = $json->allow_blessed ([$enable]) 412=item $json = $json->allow_blessed ([$enable])
322 413
323If C<$enable> is true (or missing), then the C<encode> method will not 414If C<$enable> is true (or missing), then the C<encode> method will not
324barf when it encounters a blessed reference. Instead, the value of the 415barf when it encounters a blessed reference. Instead, the value of the
325B<convert_blessed> option will decide wether C<null> (C<convert_blessed> 416B<convert_blessed> option will decide whether C<null> (C<convert_blessed>
326disabled or no C<to_json> method found) or a representation of the 417disabled or no C<to_json> method found) or a representation of the
327object (C<convert_blessed> enabled and C<to_json> method found) is being 418object (C<convert_blessed> enabled and C<to_json> method found) is being
328encoded. Has no effect on C<decode>. 419encoded. Has no effect on C<decode>.
329 420
330If C<$enable> is false (the default), then C<encode> will throw an 421If C<$enable> is false (the default), then C<encode> will throw an
… …
341 432
342The C<TO_JSON> method may safely call die if it wants. If C<TO_JSON> 433The C<TO_JSON> method may safely call die if it wants. If C<TO_JSON>
343returns other blessed objects, those will be handled in the same 434returns other blessed objects, those will be handled in the same
344way. C<TO_JSON> must take care of not causing an endless recursion cycle 435way. C<TO_JSON> must take care of not causing an endless recursion cycle
345(== crash) in this case. The name of C<TO_JSON> was chosen because other 436(== crash) in this case. The name of C<TO_JSON> was chosen because other
346methods called by the Perl core (== not the user of the object) are 437methods called by the Perl core (== not by the user of the object) are
347usually in upper case letters and to avoid collisions with the C<to_json> 438usually in upper case letters and to avoid collisions with the C<to_json>
348function. 439function.
349 440
441This setting does not yet influence C<decode> in any way, but in the
442future, global hooks might get installed that influence C<decode> and are
443enabled by this setting.
444
350If C<$enable> is false, then the C<allow_blessed> setting will decide what 445If C<$enable> is false, then the C<allow_blessed> setting will decide what
351to do when a blessed object is found. 446to do when a blessed object is found.
447
448=item $json = $json->filter_json_object ([$coderef->($hashref)])
449
450When C<$coderef> is specified, it will be called from C<decode> each
451time it decodes a JSON object. The only argument is a reference to the
452newly-created hash. If the code references returns a single scalar (which
453need not be a reference), this value (i.e. a copy of that scalar to avoid
454aliasing) is inserted into the deserialised data structure. If it returns
455an empty list (NOTE: I<not> C<undef>, which is a valid scalar), the
456original deserialised hash will be inserted. This setting can slow down
457decoding considerably.
458
459When C<$coderef> is omitted or undefined, any existing callback will
460be removed and C<decode> will not change the deserialised hash in any
461way.
462
463Example, convert all JSON objects into the integer 5:
464
465 my $js = JSON::XS->new->filter_json_object (sub { 5 });
466 # returns [5]
467 $js->decode ('[{}]')
468 # throw an exception because allow_nonref is not enabled
469 # so a lone 5 is not allowed.
470 $js->decode ('{"a":1, "b":2}');
471
472=item $json = $json->filter_json_single_key_object ($key [=> $coderef->($value)])
473
474Works remotely similar to C<filter_json_object>, but is only called for
475JSON objects having a single key named C<$key>.
476
477This C<$coderef> is called before the one specified via
478C<filter_json_object>, if any. It gets passed the single value in the JSON
479object. If it returns a single value, it will be inserted into the data
480structure. If it returns nothing (not even C<undef> but the empty list),
481the callback from C<filter_json_object> will be called next, as if no
482single-key callback were specified.
483
484If C<$coderef> is omitted or undefined, the corresponding callback will be
485disabled. There can only ever be one callback for a given key.
486
487As this callback gets called less often then the C<filter_json_object>
488one, decoding speed will not usually suffer as much. Therefore, single-key
489objects make excellent targets to serialise Perl objects into, especially
490as single-key JSON objects are as close to the type-tagged value concept
491as JSON gets (it's basically an ID/VALUE tuple). Of course, JSON does not
492support this in any way, so you need to make sure your data never looks
493like a serialised Perl hash.
494
495Typical names for the single object key are C<__class_whatever__>, or
496C<$__dollars_are_rarely_used__$> or C<}ugly_brace_placement>, or even
497things like C<__class_md5sum(classname)__>, to reduce the risk of clashing
498with real hashes.
499
500Example, decode JSON objects of the form C<< { "__widget__" => <id> } >>
501into the corresponding C<< $WIDGET{<id>} >> object:
502
503 # return whatever is in $WIDGET{5}:
504 JSON::XS
505 ->new
506 ->filter_json_single_key_object (__widget__ => sub {
507 $WIDGET{ $_[0] }
508 })
509 ->decode ('{"__widget__": 5')
510
511 # this can be used with a TO_JSON method in some "widget" class
512 # for serialisation to json:
513 sub WidgetBase::TO_JSON {
514 my ($self) = @_;
515
516 unless ($self->{id}) {
517 $self->{id} = ..get..some..id..;
518 $WIDGET{$self->{id}} = $self;
519 }
520
521 { __widget__ => $self->{id} }
522 }
352 523
353=item $json = $json->shrink ([$enable]) 524=item $json = $json->shrink ([$enable])
354 525
355Perl usually over-allocates memory a bit when allocating space for 526Perl usually over-allocates memory a bit when allocating space for
356strings. This flag optionally resizes strings generated by either 527strings. This flag optionally resizes strings generated by either
… …
389given character in a string. 560given character in a string.
390 561
391Setting the maximum depth to one disallows any nesting, so that ensures 562Setting the maximum depth to one disallows any nesting, so that ensures
392that the object is only a single hash/object or array. 563that the object is only a single hash/object or array.
393 564
394The argument to C<max_depth> will be rounded up to the next nearest power 565The argument to C<max_depth> will be rounded up to the next highest power
395of two. 566of two. If no argument is given, the highest possible setting will be
567used, which is rarely useful.
568
569See SECURITY CONSIDERATIONS, below, for more info on why this is useful.
570
571=item $json = $json->max_size ([$maximum_string_size])
572
573Set the maximum length a JSON text may have (in bytes) where decoding is
574being attempted. The default is C<0>, meaning no limit. When C<decode>
575is called on a string longer then this number of characters it will not
576attempt to decode the string but throw an exception. This setting has no
577effect on C<encode> (yet).
578
579The argument to C<max_size> will be rounded up to the next B<highest>
580power of two (so may be more than requested). If no argument is given, the
581limit check will be deactivated (same as when C<0> is specified).
396 582
397See SECURITY CONSIDERATIONS, below, for more info on why this is useful. 583See SECURITY CONSIDERATIONS, below, for more info on why this is useful.
398 584
399=item $json_text = $json->encode ($perl_scalar) 585=item $json_text = $json->encode ($perl_scalar)
400 586
… …
437vice versa. These mappings are designed to "do the right thing" in most 623vice versa. These mappings are designed to "do the right thing" in most
438circumstances automatically, preserving round-tripping characteristics 624circumstances automatically, preserving round-tripping characteristics
439(what you put in comes out as something equivalent). 625(what you put in comes out as something equivalent).
440 626
441For the more enlightened: note that in the following descriptions, 627For the more enlightened: note that in the following descriptions,
442lowercase I<perl> refers to the Perl interpreter, while uppcercase I<Perl> 628lowercase I<perl> refers to the Perl interpreter, while uppercase I<Perl>
443refers to the abstract Perl language itself. 629refers to the abstract Perl language itself.
444 630
445 631
446=head2 JSON -> PERL 632=head2 JSON -> PERL
447 633
448=over 4 634=over 4
449 635
450=item object 636=item object
451 637
452A JSON object becomes a reference to a hash in Perl. No ordering of object 638A JSON object becomes a reference to a hash in Perl. No ordering of object
453keys is preserved (JSON does not preserver object key ordering itself). 639keys is preserved (JSON does not preserve object key ordering itself).
454 640
455=item array 641=item array
456 642
457A JSON array becomes a reference to an array in Perl. 643A JSON array becomes a reference to an array in Perl.
458 644
… …
462are represented by the same codepoints in the Perl string, so no manual 648are represented by the same codepoints in the Perl string, so no manual
463decoding is necessary. 649decoding is necessary.
464 650
465=item number 651=item number
466 652
467A JSON number becomes either an integer or numeric (floating point) 653A JSON number becomes either an integer, numeric (floating point) or
468scalar in perl, depending on its range and any fractional parts. On the 654string scalar in perl, depending on its range and any fractional parts. On
469Perl level, there is no difference between those as Perl handles all the 655the Perl level, there is no difference between those as Perl handles all
470conversion details, but an integer may take slightly less memory and might 656the conversion details, but an integer may take slightly less memory and
471represent more values exactly than (floating point) numbers. 657might represent more values exactly than (floating point) numbers.
658
659If the number consists of digits only, JSON::XS will try to represent
660it as an integer value. If that fails, it will try to represent it as
661a numeric (floating point) value if that is possible without loss of
662precision. Otherwise it will preserve the number as a string value.
663
664Numbers containing a fractional or exponential part will always be
665represented as numeric (floating point) values, possibly at a loss of
666precision.
667
668This might create round-tripping problems as numbers might become strings,
669but as Perl is typeless there is no other way to do it.
472 670
473=item true, false 671=item true, false
474 672
475These JSON atoms become C<JSON::XS::true> and C<JSON::XS::false>, 673These JSON atoms become C<JSON::XS::true> and C<JSON::XS::false>,
476respectively. They are overloaded to act almost exactly like the numbers 674respectively. They are overloaded to act almost exactly like the numbers
477C<1> and C<0>. You can check wether a scalar is a JSON boolean by using 675C<1> and C<0>. You can check whether a scalar is a JSON boolean by using
478the C<JSON::XS::is_bool> function. 676the C<JSON::XS::is_bool> function.
479 677
480=item null 678=item null
481 679
482A JSON null atom becomes C<undef> in Perl. 680A JSON null atom becomes C<undef> in Perl.
… …
518 to_json [\0,JSON::XS::true] # yields [false,true] 716 to_json [\0,JSON::XS::true] # yields [false,true]
519 717
520=item JSON::XS::true, JSON::XS::false 718=item JSON::XS::true, JSON::XS::false
521 719
522These special values become JSON true and JSON false values, 720These special values become JSON true and JSON false values,
523respectively. You cna alos use C<\1> and C<\0> directly if you want. 721respectively. You can also use C<\1> and C<\0> directly if you want.
524 722
525=item blessed objects 723=item blessed objects
526 724
527Blessed objects are not allowed. JSON::XS currently tries to encode their 725Blessed objects are not allowed. JSON::XS currently tries to encode their
528underlying representation (hash- or arrayref), but this behaviour might 726underlying representation (hash- or arrayref), but this behaviour might
… …
545 to_json [$value] # yields ["5"] 743 to_json [$value] # yields ["5"]
546 744
547 # undef becomes null 745 # undef becomes null
548 to_json [undef] # yields [null] 746 to_json [undef] # yields [null]
549 747
550You can force the type to be a string by stringifying it: 748You can force the type to be a JSON string by stringifying it:
551 749
552 my $x = 3.1; # some variable containing a number 750 my $x = 3.1; # some variable containing a number
553 "$x"; # stringified 751 "$x"; # stringified
554 $x .= ""; # another, more awkward way to stringify 752 $x .= ""; # another, more awkward way to stringify
555 print $x; # perl does it for you, too, quite often 753 print $x; # perl does it for you, too, quite often
556 754
557You can force the type to be a number by numifying it: 755You can force the type to be a JSON number by numifying it:
558 756
559 my $x = "3"; # some variable containing a string 757 my $x = "3"; # some variable containing a string
560 $x += 0; # numify it, ensuring it will be dumped as a number 758 $x += 0; # numify it, ensuring it will be dumped as a number
561 $x *= 1; # same thing, the choise is yours. 759 $x *= 1; # same thing, the choice is yours.
562 760
563You can not currently output JSON booleans or force the type in other, 761You can not currently force the type in other, less obscure, ways. Tell me
564less obscure, ways. Tell me if you need this capability. 762if you need this capability.
565 763
566=back 764=back
567 765
568 766
569=head1 COMPARISON 767=head1 COMPARISON
… …
578 776
579=item JSON 1.07 777=item JSON 1.07
580 778
581Slow (but very portable, as it is written in pure Perl). 779Slow (but very portable, as it is written in pure Perl).
582 780
583Undocumented/buggy Unicode handling (how JSON handles unicode values is 781Undocumented/buggy Unicode handling (how JSON handles Unicode values is
584undocumented. One can get far by feeding it unicode strings and doing 782undocumented. One can get far by feeding it Unicode strings and doing
585en-/decoding oneself, but unicode escapes are not working properly). 783en-/decoding oneself, but Unicode escapes are not working properly).
586 784
587No roundtripping (strings get clobbered if they look like numbers, e.g. 785No round-tripping (strings get clobbered if they look like numbers, e.g.
588the string C<2.0> will encode to C<2.0> instead of C<"2.0">, and that will 786the string C<2.0> will encode to C<2.0> instead of C<"2.0">, and that will
589decode into the number 2. 787decode into the number 2.
590 788
591=item JSON::PC 0.01 789=item JSON::PC 0.01
592 790
593Very fast. 791Very fast.
594 792
595Undocumented/buggy Unicode handling. 793Undocumented/buggy Unicode handling.
596 794
597No roundtripping. 795No round-tripping.
598 796
599Has problems handling many Perl values (e.g. regex results and other magic 797Has problems handling many Perl values (e.g. regex results and other magic
600values will make it croak). 798values will make it croak).
601 799
602Does not even generate valid JSON (C<{1,2}> gets converted to C<{1:2}> 800Does not even generate valid JSON (C<{1,2}> gets converted to C<{1:2}>
… …
612Very inflexible (no human-readable format supported, format pretty much 810Very inflexible (no human-readable format supported, format pretty much
613undocumented. I need at least a format for easy reading by humans and a 811undocumented. I need at least a format for easy reading by humans and a
614single-line compact format for use in a protocol, and preferably a way to 812single-line compact format for use in a protocol, and preferably a way to
615generate ASCII-only JSON texts). 813generate ASCII-only JSON texts).
616 814
617Completely broken (and confusingly documented) Unicode handling (unicode 815Completely broken (and confusingly documented) Unicode handling (Unicode
618escapes are not working properly, you need to set ImplicitUnicode to 816escapes are not working properly, you need to set ImplicitUnicode to
619I<different> values on en- and decoding to get symmetric behaviour). 817I<different> values on en- and decoding to get symmetric behaviour).
620 818
621No roundtripping (simple cases work, but this depends on wether the scalar 819No round-tripping (simple cases work, but this depends on whether the scalar
622value was used in a numeric context or not). 820value was used in a numeric context or not).
623 821
624Dumping hashes may skip hash values depending on iterator state. 822Dumping hashes may skip hash values depending on iterator state.
625 823
626Unmaintained (maintainer unresponsive for many months, bugs are not 824Unmaintained (maintainer unresponsive for many months, bugs are not
627getting fixed). 825getting fixed).
628 826
629Does not check input for validity (i.e. will accept non-JSON input and 827Does not check input for validity (i.e. will accept non-JSON input and
630return "something" instead of raising an exception. This is a security 828return "something" instead of raising an exception. This is a security
631issue: imagine two banks transfering money between each other using 829issue: imagine two banks transferring money between each other using
632JSON. One bank might parse a given non-JSON request and deduct money, 830JSON. One bank might parse a given non-JSON request and deduct money,
633while the other might reject the transaction with a syntax error. While a 831while the other might reject the transaction with a syntax error. While a
634good protocol will at least recover, that is extra unnecessary work and 832good protocol will at least recover, that is extra unnecessary work and
635the transaction will still not succeed). 833the transaction will still not succeed).
636 834
637=item JSON::DWIW 0.04 835=item JSON::DWIW 0.04
638 836
639Very fast. Very natural. Very nice. 837Very fast. Very natural. Very nice.
640 838
641Undocumented unicode handling (but the best of the pack. Unicode escapes 839Undocumented Unicode handling (but the best of the pack. Unicode escapes
642still don't get parsed properly). 840still don't get parsed properly).
643 841
644Very inflexible. 842Very inflexible.
645 843
646No roundtripping. 844No round-tripping.
647 845
648Does not generate valid JSON texts (key strings are often unquoted, empty keys 846Does not generate valid JSON texts (key strings are often unquoted, empty keys
649result in nothing being output) 847result in nothing being output)
650 848
651Does not check input for validity. 849Does not check input for validity.
… …
666 my $yaml = $to_yaml->encode ($ref) . "\n"; 864 my $yaml = $to_yaml->encode ($ref) . "\n";
667 865
668This will usually generate JSON texts that also parse as valid 866This will usually generate JSON texts that also parse as valid
669YAML. Please note that YAML has hardcoded limits on (simple) object key 867YAML. Please note that YAML has hardcoded limits on (simple) object key
670lengths that JSON doesn't have, so you should make sure that your hash 868lengths that JSON doesn't have, so you should make sure that your hash
671keys are noticably shorter than the 1024 characters YAML allows. 869keys are noticeably shorter than the 1024 characters YAML allows.
672 870
673There might be other incompatibilities that I am not aware of. In general 871There might be other incompatibilities that I am not aware of. In general
674you should not try to generate YAML with a JSON generator or vice versa, 872you should not try to generate YAML with a JSON generator or vice versa,
675or try to parse JSON with a YAML parser or vice versa: chances are high 873or try to parse JSON with a YAML parser or vice versa: chances are high
676that you will run into severe interoperability problems. 874that you will run into severe interoperability problems.
… …
692It shows the number of encodes/decodes per second (JSON::XS uses 890It shows the number of encodes/decodes per second (JSON::XS uses
693the functional interface, while JSON::XS/2 uses the OO interface 891the functional interface, while JSON::XS/2 uses the OO interface
694with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables 892with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables
695shrink). Higher is better: 893shrink). Higher is better:
696 894
895 Storable | 15779.925 | 14169.946 |
896 -----------+------------+------------+
697 module | encode | decode | 897 module | encode | decode |
698 -----------|------------|------------| 898 -----------|------------|------------|
699 JSON | 7645.468 | 4208.613 | 899 JSON | 4990.842 | 4088.813 |
700 JSON::DWIW | 40721.398 | 77101.176 | 900 JSON::DWIW | 51653.990 | 71575.154 |
701 JSON::PC | 65948.176 | 78251.940 | 901 JSON::PC | 65948.176 | 74631.744 |
702 JSON::Syck | 22844.793 | 26479.192 | 902 JSON::PP | 8931.652 | 3817.168 |
903 JSON::Syck | 24877.248 | 27776.848 |
703 JSON::XS | 388361.481 | 199728.762 | 904 JSON::XS | 388361.481 | 227951.304 |
704 JSON::XS/2 | 218453.333 | 192399.266 | 905 JSON::XS/2 | 227951.304 | 218453.333 |
705 JSON::XS/3 | 338250.323 | 192399.266 | 906 JSON::XS/3 | 338250.323 | 218453.333 |
706 Storable | 15779.925 | 14169.946 | 907 Storable | 16500.016 | 135300.129 |
707 -----------+------------+------------+ 908 -----------+------------+------------+
708 909
709That is, JSON::XS is about five times faster than JSON::DWIW on encoding, 910That is, JSON::XS is about five times faster than JSON::DWIW on encoding,
710about three times faster on decoding, and over fourty times faster 911about three times faster on decoding, and over forty times faster
711than JSON, even with pretty-printing and key sorting. It also compares 912than JSON, even with pretty-printing and key sorting. It also compares
712favourably to Storable for small amounts of data. 913favourably to Storable for small amounts of data.
713 914
714Using a longer test string (roughly 18KB, generated from Yahoo! Locals 915Using a longer test string (roughly 18KB, generated from Yahoo! Locals
715search API (http://nanoref.com/yahooapis/mgPdGg): 916search API (http://nanoref.com/yahooapis/mgPdGg):
716 917
717 module | encode | decode | 918 module | encode | decode |
718 -----------|------------|------------| 919 -----------|------------|------------|
719 JSON | 254.685 | 37.665 | 920 JSON | 55.260 | 34.971 |
720 JSON::DWIW | 843.343 | 1049.731 | 921 JSON::DWIW | 825.228 | 1082.513 |
721 JSON::PC | 3602.116 | 2307.352 | 922 JSON::PC | 3571.444 | 2394.829 |
923 JSON::PP | 210.987 | 32.574 |
722 JSON::Syck | 505.107 | 787.899 | 924 JSON::Syck | 552.551 | 787.544 |
723 JSON::XS | 5747.196 | 3690.220 | 925 JSON::XS | 5780.463 | 4854.519 |
724 JSON::XS/2 | 3968.121 | 3676.634 | 926 JSON::XS/2 | 3869.998 | 4798.975 |
725 JSON::XS/3 | 6105.246 | 3662.508 | 927 JSON::XS/3 | 5862.880 | 4798.975 |
726 Storable | 4417.337 | 5285.161 | 928 Storable | 4445.002 | 5235.027 |
727 -----------+------------+------------+ 929 -----------+------------+------------+
728 930
729Again, JSON::XS leads by far (except for Storable which non-surprisingly 931Again, JSON::XS leads by far (except for Storable which non-surprisingly
730decodes faster). 932decodes faster).
731 933
732On large strings containing lots of high unicode characters, some modules 934On large strings containing lots of high Unicode characters, some modules
733(such as JSON::PC) seem to decode faster than JSON::XS, but the result 935(such as JSON::PC) seem to decode faster than JSON::XS, but the result
734will be broken due to missing (or wrong) unicode handling. Others refuse 936will be broken due to missing (or wrong) Unicode handling. Others refuse
735to decode or encode properly, so it was impossible to prepare a fair 937to decode or encode properly, so it was impossible to prepare a fair
736comparison table for that case. 938comparison table for that case.
737 939
738 940
739=head1 SECURITY CONSIDERATIONS 941=head1 SECURITY CONSIDERATIONS
… …
745any buffer overflows. Obviously, this module should ensure that and I am 947any buffer overflows. Obviously, this module should ensure that and I am
746trying hard on making that true, but you never know. 948trying hard on making that true, but you never know.
747 949
748Second, you need to avoid resource-starving attacks. That means you should 950Second, you need to avoid resource-starving attacks. That means you should
749limit the size of JSON texts you accept, or make sure then when your 951limit the size of JSON texts you accept, or make sure then when your
750resources run out, thats just fine (e.g. by using a separate process that 952resources run out, that's just fine (e.g. by using a separate process that
751can crash safely). The size of a JSON text in octets or characters is 953can crash safely). The size of a JSON text in octets or characters is
752usually a good indication of the size of the resources required to decode 954usually a good indication of the size of the resources required to decode
753it into a Perl structure. 955it into a Perl structure. While JSON::XS can check the size of the JSON
956text, it might be too late when you already have it in memory, so you
957might want to check the size before you accept the string.
754 958
755Third, JSON::XS recurses using the C stack when decoding objects and 959Third, JSON::XS recurses using the C stack when decoding objects and
756arrays. The C stack is a limited resource: for instance, on my amd64 960arrays. The C stack is a limited resource: for instance, on my amd64
757machine with 8MB of stack size I can decode around 180k nested arrays but 961machine with 8MB of stack size I can decode around 180k nested arrays but
758only 14k nested JSON objects (due to perl itself recursing deeply on croak 962only 14k nested JSON objects (due to perl itself recursing deeply on croak
… …
764And last but least, something else could bomb you that I forgot to think 968And last but least, something else could bomb you that I forgot to think
765of. In that case, you get to keep the pieces. I am always open for hints, 969of. In that case, you get to keep the pieces. I am always open for hints,
766though... 970though...
767 971
768If you are using JSON::XS to return packets to consumption 972If you are using JSON::XS to return packets to consumption
769by javascript scripts in a browser you should have a look at 973by JavaScript scripts in a browser you should have a look at
770L<http://jpsykes.com/47/practical-csrf-and-json-security> to see wether 974L<http://jpsykes.com/47/practical-csrf-and-json-security> to see whether
771you are vulnerable to some common attack vectors (which really are browser 975you are vulnerable to some common attack vectors (which really are browser
772design bugs, but it is still you who will have to deal with it, as major 976design bugs, but it is still you who will have to deal with it, as major
773browser developers care only for features, not about doing security 977browser developers care only for features, not about doing security
774right). 978right).
775 979
776 980
981=head1 THREADS
982
983This module is I<not> guaranteed to be thread safe and there are no
984plans to change this until Perl gets thread support (as opposed to the
985horribly slow so-called "threads" which are simply slow and bloated
986process simulations - use fork, its I<much> faster, cheaper, better).
987
988(It might actually work, but you have been warned).
989
990
777=head1 BUGS 991=head1 BUGS
778 992
779While the goal of this module is to be correct, that unfortunately does 993While the goal of this module is to be correct, that unfortunately does
780not mean its bug-free, only that I think its design is bug-free. It is 994not mean its bug-free, only that I think its design is bug-free. It is
781still relatively early in its development. If you keep reporting bugs they 995still relatively early in its development. If you keep reporting bugs they
782will be fixed swiftly, though. 996will be fixed swiftly, though.
997
998Please refrain from using rt.cpan.org or any other bug reporting
999service. I put the contact address into my modules for a reason.
783 1000
784=cut 1001=cut
785 1002
786our $true = do { bless \(my $dummy = 1), "JSON::XS::Boolean" }; 1003our $true = do { bless \(my $dummy = 1), "JSON::XS::Boolean" };
787our $false = do { bless \(my $dummy = 0), "JSON::XS::Boolean" }; 1004our $false = do { bless \(my $dummy = 0), "JSON::XS::Boolean" };

Diff Legend

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