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.24 by root, Thu Mar 29 01:27:36 2007 UTC vs.
Revision 1.73 by root, Sun Nov 25 19:36:54 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
90BEGIN {
91 our $VERSION = '0.8'; 89our $VERSION = '1.6';
92 our @ISA = qw(Exporter); 90our @ISA = qw(Exporter);
93 91
94 our @EXPORT = qw(to_json from_json objToJson jsonToObj); 92our @EXPORT = qw(to_json from_json);
95 require Exporter;
96 93
97 require XSLoader; 94use Exporter;
98 XSLoader::load JSON::XS::, $VERSION; 95use XSLoader;
99}
100 96
101=head1 FUNCTIONAL INTERFACE 97=head1 FUNCTIONAL INTERFACE
102 98
103The following convinience methods are provided by this module. They are 99The following convenience methods are provided by this module. They are
104exported by default: 100exported by default:
105 101
106=over 4 102=over 4
107 103
108=item $json_text = to_json $perl_scalar 104=item $json_text = to_json $perl_scalar
109 105
110Converts 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
111a 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.
112octets only). Croaks on error.
113 108
114This function call is functionally identical to: 109This function call is functionally identical to:
115 110
116 $json_text = JSON::XS->new->utf8->encode ($perl_scalar) 111 $json_text = JSON::XS->new->utf8->encode ($perl_scalar)
117 112
118except being faster. 113except being faster.
119 114
120=item $perl_scalar = from_json $json_text 115=item $perl_scalar = from_json $json_text
121 116
122The 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
123parse 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
124scalar or reference. Croaks on error. 119reference. Croaks on error.
125 120
126This function call is functionally identical to: 121This function call is functionally identical to:
127 122
128 $perl_scalar = JSON::XS->new->utf8->decode ($json_text) 123 $perl_scalar = JSON::XS->new->utf8->decode ($json_text)
129 124
130except being faster. 125except being faster.
131 126
127=item $is_boolean = JSON::XS::is_bool $scalar
128
129Returns true if the passed scalar represents either JSON::XS::true or
130JSON::XS::false, two constants that act like C<1> and C<0>, respectively
131and are used to represent JSON C<true> and C<false> values in Perl.
132
133See MAPPING, below, for more information on how JSON values are mapped to
134Perl.
135
132=back 136=back
137
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 :)
133 185
134 186
135=head1 OBJECT-ORIENTED INTERFACE 187=head1 OBJECT-ORIENTED INTERFACE
136 188
137The object oriented interface lets you configure your own encoding or 189The object oriented interface lets you configure your own encoding or
… …
150 my $json = JSON::XS->new->utf8->space_after->encode ({a => [1,2]}) 202 my $json = JSON::XS->new->utf8->space_after->encode ({a => [1,2]})
151 => {"a": [1, 2]} 203 => {"a": [1, 2]}
152 204
153=item $json = $json->ascii ([$enable]) 205=item $json = $json->ascii ([$enable])
154 206
207=item $enabled = $json->get_ascii
208
155If C<$enable> is true (or missing), then the C<encode> method will not 209If 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 210generate characters outside the code range C<0..127> (which is ASCII). Any
157unicode characters outside that range will be escaped using either a 211Unicode characters outside that range will be escaped using either a
158single \uXXXX (BMP characters) or a double \uHHHH\uLLLLL escape sequence, 212single \uXXXX (BMP characters) or a double \uHHHH\uLLLLL escape sequence,
159as per RFC4627. 213as per RFC4627. The resulting encoded JSON text can be treated as a native
214Unicode string, an ascii-encoded, latin1-encoded or UTF-8 encoded string,
215or any other superset of ASCII.
160 216
161If C<$enable> is false, then the C<encode> method will not escape Unicode 217If C<$enable> is false, then the C<encode> method will not escape Unicode
162characters unless required by the JSON syntax. This results in a faster 218characters unless required by the JSON syntax or other flags. This results
163and more compact format. 219in a faster and more compact format.
220
221The main use for this flag is to produce JSON texts that can be
222transmitted over a 7-bit channel, as the encoded JSON texts will not
223contain any 8 bit characters.
164 224
165 JSON::XS->new->ascii (1)->encode ([chr 0x10401]) 225 JSON::XS->new->ascii (1)->encode ([chr 0x10401])
166 => ["\ud801\udc01"] 226 => ["\ud801\udc01"]
167 227
228=item $json = $json->latin1 ([$enable])
229
230=item $enabled = $json->get_latin1
231
232If C<$enable> is true (or missing), then the C<encode> method will encode
233the resulting JSON text as latin1 (or iso-8859-1), escaping any characters
234outside the code range C<0..255>. The resulting string can be treated as a
235latin1-encoded JSON text or a native Unicode string. The C<decode> method
236will not be affected in any way by this flag, as C<decode> by default
237expects Unicode, which is a strict superset of latin1.
238
239If C<$enable> is false, then the C<encode> method will not escape Unicode
240characters unless required by the JSON syntax or other flags.
241
242The main use for this flag is efficiently encoding binary data as JSON
243text, as most octets will not be escaped, resulting in a smaller encoded
244size. The disadvantage is that the resulting JSON text is encoded
245in latin1 (and must correctly be treated as such when storing and
246transferring), a rare encoding for JSON. It is therefore most useful when
247you want to store data structures known to contain binary data efficiently
248in files or databases, not when talking to other JSON encoders/decoders.
249
250 JSON::XS->new->latin1->encode (["\x{89}\x{abc}"]
251 => ["\x{89}\\u0abc"] # (perl syntax, U+abc escaped, U+89 not)
252
168=item $json = $json->utf8 ([$enable]) 253=item $json = $json->utf8 ([$enable])
254
255=item $enabled = $json->get_utf8
169 256
170If C<$enable> is true (or missing), then the C<encode> method will encode 257If C<$enable> is true (or missing), then the C<encode> method will encode
171the JSON result into UTF-8, as required by many protocols, while the 258the JSON result into UTF-8, as required by many protocols, while the
172C<decode> method expects to be handled an UTF-8-encoded string. Please 259C<decode> method expects to be handled an UTF-8-encoded string. Please
173note that UTF-8-encoded strings do not contain any characters outside the 260note that UTF-8-encoded strings do not contain any characters outside the
174range C<0..255>, they are thus useful for bytewise/binary I/O. In future 261range C<0..255>, they are thus useful for bytewise/binary I/O. In future
175versions, enabling this option might enable autodetection of the UTF-16 262versions, enabling this option might enable autodetection of the UTF-16
176and UTF-32 encoding families, as described in RFC4627. 263and UTF-32 encoding families, as described in RFC4627.
177 264
178If C<$enable> is false, then the C<encode> method will return the JSON 265If C<$enable> is false, then the C<encode> method will return the JSON
179string as a (non-encoded) unicode string, while C<decode> expects thus a 266string as a (non-encoded) Unicode string, while C<decode> expects thus a
180unicode string. Any decoding or encoding (e.g. to UTF-8 or UTF-16) needs 267Unicode string. Any decoding or encoding (e.g. to UTF-8 or UTF-16) needs
181to be done yourself, e.g. using the Encode module. 268to be done yourself, e.g. using the Encode module.
182 269
183Example, output UTF-16BE-encoded JSON: 270Example, output UTF-16BE-encoded JSON:
184 271
185 use Encode; 272 use Encode;
… …
189 276
190 use Encode; 277 use Encode;
191 $object = JSON::XS->new->decode (decode "UTF-32LE", $jsontext); 278 $object = JSON::XS->new->decode (decode "UTF-32LE", $jsontext);
192 279
193=item $json = $json->pretty ([$enable]) 280=item $json = $json->pretty ([$enable])
281
282=item $enabled = $json->get_pretty
194 283
195This enables (or disables) all of the C<indent>, C<space_before> and 284This enables (or disables) all of the C<indent>, C<space_before> and
196C<space_after> (and in the future possibly more) flags in one call to 285C<space_after> (and in the future possibly more) flags in one call to
197generate the most readable (or most compact) form possible. 286generate the most readable (or most compact) form possible.
198 287
… …
207 ] 296 ]
208 } 297 }
209 298
210=item $json = $json->indent ([$enable]) 299=item $json = $json->indent ([$enable])
211 300
301=item $enabled = $json->get_indent
302
212If C<$enable> is true (or missing), then the C<encode> method will use a multiline 303If C<$enable> is true (or missing), then the C<encode> method will use a multiline
213format as output, putting every array member or object/hash key-value pair 304format as output, putting every array member or object/hash key-value pair
214into its own line, identing them properly. 305into its own line, indenting them properly.
215 306
216If C<$enable> is false, no newlines or indenting will be produced, and the 307If C<$enable> is false, no newlines or indenting will be produced, and the
217resulting JSON text is guarenteed not to contain any C<newlines>. 308resulting JSON text is guaranteed not to contain any C<newlines>.
218 309
219This setting has no effect when decoding JSON texts. 310This setting has no effect when decoding JSON texts.
220 311
221=item $json = $json->space_before ([$enable]) 312=item $json = $json->space_before ([$enable])
313
314=item $enabled = $json->get_space_before
222 315
223If C<$enable> is true (or missing), then the C<encode> method will add an extra 316If C<$enable> is true (or missing), then the C<encode> method will add an extra
224optional space before the C<:> separating keys from values in JSON objects. 317optional space before the C<:> separating keys from values in JSON objects.
225 318
226If C<$enable> is false, then the C<encode> method will not add any extra 319If C<$enable> is false, then the C<encode> method will not add any extra
… …
232Example, space_before enabled, space_after and indent disabled: 325Example, space_before enabled, space_after and indent disabled:
233 326
234 {"key" :"value"} 327 {"key" :"value"}
235 328
236=item $json = $json->space_after ([$enable]) 329=item $json = $json->space_after ([$enable])
330
331=item $enabled = $json->get_space_after
237 332
238If C<$enable> is true (or missing), then the C<encode> method will add an extra 333If C<$enable> is true (or missing), then the C<encode> method will add an extra
239optional space after the C<:> separating keys from values in JSON objects 334optional space after the C<:> separating keys from values in JSON objects
240and extra whitespace after the C<,> separating key-value pairs and array 335and extra whitespace after the C<,> separating key-value pairs and array
241members. 336members.
… …
247 342
248Example, space_before and indent disabled, space_after enabled: 343Example, space_before and indent disabled, space_after enabled:
249 344
250 {"key": "value"} 345 {"key": "value"}
251 346
347=item $json = $json->relaxed ([$enable])
348
349=item $enabled = $json->get_relaxed
350
351If C<$enable> is true (or missing), then C<decode> will accept some
352extensions to normal JSON syntax (see below). C<encode> will not be
353affected in anyway. I<Be aware that this option makes you accept invalid
354JSON texts as if they were valid!>. I suggest only to use this option to
355parse application-specific files written by humans (configuration files,
356resource files etc.)
357
358If C<$enable> is false (the default), then C<decode> will only accept
359valid JSON texts.
360
361Currently accepted extensions are:
362
363=over 4
364
365=item * list items can have an end-comma
366
367JSON I<separates> array elements and key-value pairs with commas. This
368can be annoying if you write JSON texts manually and want to be able to
369quickly append elements, so this extension accepts comma at the end of
370such items not just between them:
371
372 [
373 1,
374 2, <- this comma not normally allowed
375 ]
376 {
377 "k1": "v1",
378 "k2": "v2", <- this comma not normally allowed
379 }
380
381=item * shell-style '#'-comments
382
383Whenever JSON allows whitespace, shell-style comments are additionally
384allowed. They are terminated by the first carriage-return or line-feed
385character, after which more white-space and comments are allowed.
386
387 [
388 1, # this comment not allowed in JSON
389 # neither this one...
390 ]
391
392=back
393
252=item $json = $json->canonical ([$enable]) 394=item $json = $json->canonical ([$enable])
395
396=item $enabled = $json->get_canonical
253 397
254If C<$enable> is true (or missing), then the C<encode> method will output JSON objects 398If C<$enable> is true (or missing), then the C<encode> method will output JSON objects
255by sorting their keys. This is adding a comparatively high overhead. 399by sorting their keys. This is adding a comparatively high overhead.
256 400
257If C<$enable> is false, then the C<encode> method will output key-value 401If C<$enable> is false, then the C<encode> method will output key-value
258pairs in the order Perl stores them (which will likely change between runs 402pairs in the order Perl stores them (which will likely change between runs
259of the same script). 403of the same script).
260 404
261This option is useful if you want the same data structure to be encoded as 405This option is useful if you want the same data structure to be encoded as
262the same JSON text (given the same overall settings). If it is disabled, 406the same JSON text (given the same overall settings). If it is disabled,
263the same hash migh be encoded differently even if contains the same data, 407the same hash might be encoded differently even if contains the same data,
264as key-value pairs have no inherent ordering in Perl. 408as key-value pairs have no inherent ordering in Perl.
265 409
266This setting has no effect when decoding JSON texts. 410This setting has no effect when decoding JSON texts.
267 411
268=item $json = $json->allow_nonref ([$enable]) 412=item $json = $json->allow_nonref ([$enable])
413
414=item $enabled = $json->get_allow_nonref
269 415
270If C<$enable> is true (or missing), then the C<encode> method can convert a 416If C<$enable> is true (or missing), then the C<encode> method can convert a
271non-reference into its corresponding string, number or null JSON value, 417non-reference into its corresponding string, number or null JSON value,
272which is an extension to RFC4627. Likewise, C<decode> will accept those JSON 418which is an extension to RFC4627. Likewise, C<decode> will accept those JSON
273values instead of croaking. 419values instead of croaking.
… …
281resulting in an invalid JSON text: 427resulting in an invalid JSON text:
282 428
283 JSON::XS->new->allow_nonref->encode ("Hello, World!") 429 JSON::XS->new->allow_nonref->encode ("Hello, World!")
284 => "Hello, World!" 430 => "Hello, World!"
285 431
432=item $json = $json->allow_blessed ([$enable])
433
434=item $enabled = $json->get_allow_bless
435
436If C<$enable> is true (or missing), then the C<encode> method will not
437barf when it encounters a blessed reference. Instead, the value of the
438B<convert_blessed> option will decide whether C<null> (C<convert_blessed>
439disabled or no C<to_json> method found) or a representation of the
440object (C<convert_blessed> enabled and C<to_json> method found) is being
441encoded. Has no effect on C<decode>.
442
443If C<$enable> is false (the default), then C<encode> will throw an
444exception when it encounters a blessed object.
445
446=item $json = $json->convert_blessed ([$enable])
447
448=item $enabled = $json->get_convert_blessed
449
450If C<$enable> is true (or missing), then C<encode>, upon encountering a
451blessed object, will check for the availability of the C<TO_JSON> method
452on the object's class. If found, it will be called in scalar context
453and the resulting scalar will be encoded instead of the object. If no
454C<TO_JSON> method is found, the value of C<allow_blessed> will decide what
455to do.
456
457The C<TO_JSON> method may safely call die if it wants. If C<TO_JSON>
458returns other blessed objects, those will be handled in the same
459way. C<TO_JSON> must take care of not causing an endless recursion cycle
460(== crash) in this case. The name of C<TO_JSON> was chosen because other
461methods called by the Perl core (== not by the user of the object) are
462usually in upper case letters and to avoid collisions with the C<to_json>
463function.
464
465This setting does not yet influence C<decode> in any way, but in the
466future, global hooks might get installed that influence C<decode> and are
467enabled by this setting.
468
469If C<$enable> is false, then the C<allow_blessed> setting will decide what
470to do when a blessed object is found.
471
472=item $json = $json->filter_json_object ([$coderef->($hashref)])
473
474When C<$coderef> is specified, it will be called from C<decode> each
475time it decodes a JSON object. The only argument is a reference to the
476newly-created hash. If the code references returns a single scalar (which
477need not be a reference), this value (i.e. a copy of that scalar to avoid
478aliasing) is inserted into the deserialised data structure. If it returns
479an empty list (NOTE: I<not> C<undef>, which is a valid scalar), the
480original deserialised hash will be inserted. This setting can slow down
481decoding considerably.
482
483When C<$coderef> is omitted or undefined, any existing callback will
484be removed and C<decode> will not change the deserialised hash in any
485way.
486
487Example, convert all JSON objects into the integer 5:
488
489 my $js = JSON::XS->new->filter_json_object (sub { 5 });
490 # returns [5]
491 $js->decode ('[{}]')
492 # throw an exception because allow_nonref is not enabled
493 # so a lone 5 is not allowed.
494 $js->decode ('{"a":1, "b":2}');
495
496=item $json = $json->filter_json_single_key_object ($key [=> $coderef->($value)])
497
498Works remotely similar to C<filter_json_object>, but is only called for
499JSON objects having a single key named C<$key>.
500
501This C<$coderef> is called before the one specified via
502C<filter_json_object>, if any. It gets passed the single value in the JSON
503object. If it returns a single value, it will be inserted into the data
504structure. If it returns nothing (not even C<undef> but the empty list),
505the callback from C<filter_json_object> will be called next, as if no
506single-key callback were specified.
507
508If C<$coderef> is omitted or undefined, the corresponding callback will be
509disabled. There can only ever be one callback for a given key.
510
511As this callback gets called less often then the C<filter_json_object>
512one, decoding speed will not usually suffer as much. Therefore, single-key
513objects make excellent targets to serialise Perl objects into, especially
514as single-key JSON objects are as close to the type-tagged value concept
515as JSON gets (it's basically an ID/VALUE tuple). Of course, JSON does not
516support this in any way, so you need to make sure your data never looks
517like a serialised Perl hash.
518
519Typical names for the single object key are C<__class_whatever__>, or
520C<$__dollars_are_rarely_used__$> or C<}ugly_brace_placement>, or even
521things like C<__class_md5sum(classname)__>, to reduce the risk of clashing
522with real hashes.
523
524Example, decode JSON objects of the form C<< { "__widget__" => <id> } >>
525into the corresponding C<< $WIDGET{<id>} >> object:
526
527 # return whatever is in $WIDGET{5}:
528 JSON::XS
529 ->new
530 ->filter_json_single_key_object (__widget__ => sub {
531 $WIDGET{ $_[0] }
532 })
533 ->decode ('{"__widget__": 5')
534
535 # this can be used with a TO_JSON method in some "widget" class
536 # for serialisation to json:
537 sub WidgetBase::TO_JSON {
538 my ($self) = @_;
539
540 unless ($self->{id}) {
541 $self->{id} = ..get..some..id..;
542 $WIDGET{$self->{id}} = $self;
543 }
544
545 { __widget__ => $self->{id} }
546 }
547
286=item $json = $json->shrink ([$enable]) 548=item $json = $json->shrink ([$enable])
549
550=item $enabled = $json->get_shrink
287 551
288Perl usually over-allocates memory a bit when allocating space for 552Perl usually over-allocates memory a bit when allocating space for
289strings. This flag optionally resizes strings generated by either 553strings. This flag optionally resizes strings generated by either
290C<encode> or C<decode> to their minimum size possible. This can save 554C<encode> or C<decode> to their minimum size possible. This can save
291memory when your JSON texts are either very very long or you have many 555memory when your JSON texts are either very very long or you have many
… …
309strings that look like integers or floats into integers or floats 573strings that look like integers or floats into integers or floats
310internally (there is no difference on the Perl level), saving space. 574internally (there is no difference on the Perl level), saving space.
311 575
312=item $json = $json->max_depth ([$maximum_nesting_depth]) 576=item $json = $json->max_depth ([$maximum_nesting_depth])
313 577
578=item $max_depth = $json->get_max_depth
579
314Sets the maximum nesting level (default C<8192>) accepted while encoding 580Sets the maximum nesting level (default C<512>) accepted while encoding
315or decoding. If the JSON text or Perl data structure has an equal or 581or decoding. If the JSON text or Perl data structure has an equal or
316higher nesting level then this limit, then the encoder and decoder will 582higher nesting level then this limit, then the encoder and decoder will
317stop and croak at that point. 583stop and croak at that point.
318 584
319Nesting level is defined by number of hash- or arrayrefs that the encoder 585Nesting level is defined by number of hash- or arrayrefs that the encoder
… …
322given character in a string. 588given character in a string.
323 589
324Setting the maximum depth to one disallows any nesting, so that ensures 590Setting the maximum depth to one disallows any nesting, so that ensures
325that the object is only a single hash/object or array. 591that the object is only a single hash/object or array.
326 592
327The argument to C<max_depth> will be rounded up to the next nearest power 593The argument to C<max_depth> will be rounded up to the next highest power
328of two. 594of two. If no argument is given, the highest possible setting will be
595used, which is rarely useful.
596
597See SECURITY CONSIDERATIONS, below, for more info on why this is useful.
598
599=item $json = $json->max_size ([$maximum_string_size])
600
601=item $max_size = $json->get_max_size
602
603Set the maximum length a JSON text may have (in bytes) where decoding is
604being attempted. The default is C<0>, meaning no limit. When C<decode>
605is called on a string longer then this number of characters it will not
606attempt to decode the string but throw an exception. This setting has no
607effect on C<encode> (yet).
608
609The argument to C<max_size> will be rounded up to the next B<highest>
610power of two (so may be more than requested). If no argument is given, the
611limit check will be deactivated (same as when C<0> is specified).
329 612
330See SECURITY CONSIDERATIONS, below, for more info on why this is useful. 613See SECURITY CONSIDERATIONS, below, for more info on why this is useful.
331 614
332=item $json_text = $json->encode ($perl_scalar) 615=item $json_text = $json->encode ($perl_scalar)
333 616
… …
345 628
346JSON numbers and strings become simple Perl scalars. JSON arrays become 629JSON numbers and strings become simple Perl scalars. JSON arrays become
347Perl arrayrefs and JSON objects become Perl hashrefs. C<true> becomes 630Perl arrayrefs and JSON objects become Perl hashrefs. C<true> becomes
348C<1>, C<false> becomes C<0> and C<null> becomes C<undef>. 631C<1>, C<false> becomes C<0> and C<null> becomes C<undef>.
349 632
633=item ($perl_scalar, $characters) = $json->decode_prefix ($json_text)
634
635This works like the C<decode> method, but instead of raising an exception
636when there is trailing garbage after the first JSON object, it will
637silently stop parsing there and return the number of characters consumed
638so far.
639
640This is useful if your JSON texts are not delimited by an outer protocol
641(which is not the brightest thing to do in the first place) and you need
642to know where the JSON text ends.
643
644 JSON::XS->new->decode_prefix ("[1] the tail")
645 => ([], 3)
646
350=back 647=back
351 648
352 649
353=head1 MAPPING 650=head1 MAPPING
354 651
… …
356vice versa. These mappings are designed to "do the right thing" in most 653vice versa. These mappings are designed to "do the right thing" in most
357circumstances automatically, preserving round-tripping characteristics 654circumstances automatically, preserving round-tripping characteristics
358(what you put in comes out as something equivalent). 655(what you put in comes out as something equivalent).
359 656
360For the more enlightened: note that in the following descriptions, 657For the more enlightened: note that in the following descriptions,
361lowercase I<perl> refers to the Perl interpreter, while uppcercase I<Perl> 658lowercase I<perl> refers to the Perl interpreter, while uppercase I<Perl>
362refers to the abstract Perl language itself. 659refers to the abstract Perl language itself.
363 660
661
364=head2 JSON -> PERL 662=head2 JSON -> PERL
365 663
366=over 4 664=over 4
367 665
368=item object 666=item object
369 667
370A JSON object becomes a reference to a hash in Perl. No ordering of object 668A JSON object becomes a reference to a hash in Perl. No ordering of object
371keys is preserved (JSON does not preserver object key ordering itself). 669keys is preserved (JSON does not preserve object key ordering itself).
372 670
373=item array 671=item array
374 672
375A JSON array becomes a reference to an array in Perl. 673A JSON array becomes a reference to an array in Perl.
376 674
… …
380are represented by the same codepoints in the Perl string, so no manual 678are represented by the same codepoints in the Perl string, so no manual
381decoding is necessary. 679decoding is necessary.
382 680
383=item number 681=item number
384 682
385A JSON number becomes either an integer or numeric (floating point) 683A JSON number becomes either an integer, numeric (floating point) or
386scalar in perl, depending on its range and any fractional parts. On the 684string scalar in perl, depending on its range and any fractional parts. On
387Perl level, there is no difference between those as Perl handles all the 685the Perl level, there is no difference between those as Perl handles all
388conversion details, but an integer may take slightly less memory and might 686the conversion details, but an integer may take slightly less memory and
389represent more values exactly than (floating point) numbers. 687might represent more values exactly than (floating point) numbers.
688
689If the number consists of digits only, JSON::XS will try to represent
690it as an integer value. If that fails, it will try to represent it as
691a numeric (floating point) value if that is possible without loss of
692precision. Otherwise it will preserve the number as a string value.
693
694Numbers containing a fractional or exponential part will always be
695represented as numeric (floating point) values, possibly at a loss of
696precision.
697
698This might create round-tripping problems as numbers might become strings,
699but as Perl is typeless there is no other way to do it.
390 700
391=item true, false 701=item true, false
392 702
393These JSON atoms become C<0>, C<1>, respectively. Information is lost in 703These JSON atoms become C<JSON::XS::true> and C<JSON::XS::false>,
394this process. Future versions might represent those values differently, 704respectively. They are overloaded to act almost exactly like the numbers
395but they will be guarenteed to act like these integers would normally in 705C<1> and C<0>. You can check whether a scalar is a JSON boolean by using
396Perl. 706the C<JSON::XS::is_bool> function.
397 707
398=item null 708=item null
399 709
400A JSON null atom becomes C<undef> in Perl. 710A JSON null atom becomes C<undef> in Perl.
401 711
402=back 712=back
713
403 714
404=head2 PERL -> JSON 715=head2 PERL -> JSON
405 716
406The mapping from Perl to JSON is slightly more difficult, as Perl is a 717The mapping from Perl to JSON is slightly more difficult, as Perl is a
407truly typeless language, so we can only guess which JSON type is meant by 718truly typeless language, so we can only guess which JSON type is meant by
… …
410=over 4 721=over 4
411 722
412=item hash references 723=item hash references
413 724
414Perl hash references become JSON objects. As there is no inherent ordering 725Perl hash references become JSON objects. As there is no inherent ordering
415in hash keys, they will usually be encoded in a pseudo-random order that 726in hash keys (or JSON objects), they will usually be encoded in a
416can change between runs of the same program but stays generally the same 727pseudo-random order that can change between runs of the same program but
417within a single run of a program. JSON::XS can optionally sort the hash 728stays generally the same within a single run of a program. JSON::XS can
418keys (determined by the I<canonical> flag), so the same datastructure 729optionally sort the hash keys (determined by the I<canonical> flag), so
419will serialise to the same JSON text (given same settings and version of 730the same datastructure will serialise to the same JSON text (given same
420JSON::XS), but this incurs a runtime overhead. 731settings and version of JSON::XS), but this incurs a runtime overhead
732and is only rarely useful, e.g. when you want to compare some JSON text
733against another for equality.
421 734
422=item array references 735=item array references
423 736
424Perl array references become JSON arrays. 737Perl array references become JSON arrays.
738
739=item other references
740
741Other unblessed references are generally not allowed and will cause an
742exception to be thrown, except for references to the integers C<0> and
743C<1>, which get turned into C<false> and C<true> atoms in JSON. You can
744also use C<JSON::XS::false> and C<JSON::XS::true> to improve readability.
745
746 to_json [\0,JSON::XS::true] # yields [false,true]
747
748=item JSON::XS::true, JSON::XS::false
749
750These special values become JSON true and JSON false values,
751respectively. You can also use C<\1> and C<\0> directly if you want.
425 752
426=item blessed objects 753=item blessed objects
427 754
428Blessed objects are not allowed. JSON::XS currently tries to encode their 755Blessed objects are not allowed. JSON::XS currently tries to encode their
429underlying representation (hash- or arrayref), but this behaviour might 756underlying representation (hash- or arrayref), but this behaviour might
… …
446 to_json [$value] # yields ["5"] 773 to_json [$value] # yields ["5"]
447 774
448 # undef becomes null 775 # undef becomes null
449 to_json [undef] # yields [null] 776 to_json [undef] # yields [null]
450 777
451You can force the type to be a string by stringifying it: 778You can force the type to be a JSON string by stringifying it:
452 779
453 my $x = 3.1; # some variable containing a number 780 my $x = 3.1; # some variable containing a number
454 "$x"; # stringified 781 "$x"; # stringified
455 $x .= ""; # another, more awkward way to stringify 782 $x .= ""; # another, more awkward way to stringify
456 print $x; # perl does it for you, too, quite often 783 print $x; # perl does it for you, too, quite often
457 784
458You can force the type to be a number by numifying it: 785You can force the type to be a JSON number by numifying it:
459 786
460 my $x = "3"; # some variable containing a string 787 my $x = "3"; # some variable containing a string
461 $x += 0; # numify it, ensuring it will be dumped as a number 788 $x += 0; # numify it, ensuring it will be dumped as a number
462 $x *= 1; # same thing, the choise is yours. 789 $x *= 1; # same thing, the choice is yours.
463 790
464You can not currently output JSON booleans or force the type in other, 791You can not currently force the type in other, less obscure, ways. Tell me
465less obscure, ways. Tell me if you need this capability. 792if you need this capability.
466
467=item circular data structures
468
469Those will be encoded until memory or stackspace runs out.
470 793
471=back 794=back
472 795
473 796
474=head1 COMPARISON 797=head1 COMPARISON
… …
483 806
484=item JSON 1.07 807=item JSON 1.07
485 808
486Slow (but very portable, as it is written in pure Perl). 809Slow (but very portable, as it is written in pure Perl).
487 810
488Undocumented/buggy Unicode handling (how JSON handles unicode values is 811Undocumented/buggy Unicode handling (how JSON handles Unicode values is
489undocumented. One can get far by feeding it unicode strings and doing 812undocumented. One can get far by feeding it Unicode strings and doing
490en-/decoding oneself, but unicode escapes are not working properly). 813en-/decoding oneself, but Unicode escapes are not working properly).
491 814
492No roundtripping (strings get clobbered if they look like numbers, e.g. 815No round-tripping (strings get clobbered if they look like numbers, e.g.
493the string C<2.0> will encode to C<2.0> instead of C<"2.0">, and that will 816the string C<2.0> will encode to C<2.0> instead of C<"2.0">, and that will
494decode into the number 2. 817decode into the number 2.
495 818
496=item JSON::PC 0.01 819=item JSON::PC 0.01
497 820
498Very fast. 821Very fast.
499 822
500Undocumented/buggy Unicode handling. 823Undocumented/buggy Unicode handling.
501 824
502No roundtripping. 825No round-tripping.
503 826
504Has problems handling many Perl values (e.g. regex results and other magic 827Has problems handling many Perl values (e.g. regex results and other magic
505values will make it croak). 828values will make it croak).
506 829
507Does not even generate valid JSON (C<{1,2}> gets converted to C<{1:2}> 830Does not even generate valid JSON (C<{1,2}> gets converted to C<{1:2}>
… …
517Very inflexible (no human-readable format supported, format pretty much 840Very inflexible (no human-readable format supported, format pretty much
518undocumented. I need at least a format for easy reading by humans and a 841undocumented. I need at least a format for easy reading by humans and a
519single-line compact format for use in a protocol, and preferably a way to 842single-line compact format for use in a protocol, and preferably a way to
520generate ASCII-only JSON texts). 843generate ASCII-only JSON texts).
521 844
522Completely broken (and confusingly documented) Unicode handling (unicode 845Completely broken (and confusingly documented) Unicode handling (Unicode
523escapes are not working properly, you need to set ImplicitUnicode to 846escapes are not working properly, you need to set ImplicitUnicode to
524I<different> values on en- and decoding to get symmetric behaviour). 847I<different> values on en- and decoding to get symmetric behaviour).
525 848
526No roundtripping (simple cases work, but this depends on wether the scalar 849No round-tripping (simple cases work, but this depends on whether the scalar
527value was used in a numeric context or not). 850value was used in a numeric context or not).
528 851
529Dumping hashes may skip hash values depending on iterator state. 852Dumping hashes may skip hash values depending on iterator state.
530 853
531Unmaintained (maintainer unresponsive for many months, bugs are not 854Unmaintained (maintainer unresponsive for many months, bugs are not
532getting fixed). 855getting fixed).
533 856
534Does not check input for validity (i.e. will accept non-JSON input and 857Does not check input for validity (i.e. will accept non-JSON input and
535return "something" instead of raising an exception. This is a security 858return "something" instead of raising an exception. This is a security
536issue: imagine two banks transfering money between each other using 859issue: imagine two banks transferring money between each other using
537JSON. One bank might parse a given non-JSON request and deduct money, 860JSON. One bank might parse a given non-JSON request and deduct money,
538while the other might reject the transaction with a syntax error. While a 861while the other might reject the transaction with a syntax error. While a
539good protocol will at least recover, that is extra unnecessary work and 862good protocol will at least recover, that is extra unnecessary work and
540the transaction will still not succeed). 863the transaction will still not succeed).
541 864
542=item JSON::DWIW 0.04 865=item JSON::DWIW 0.04
543 866
544Very fast. Very natural. Very nice. 867Very fast. Very natural. Very nice.
545 868
546Undocumented unicode handling (but the best of the pack. Unicode escapes 869Undocumented Unicode handling (but the best of the pack. Unicode escapes
547still don't get parsed properly). 870still don't get parsed properly).
548 871
549Very inflexible. 872Very inflexible.
550 873
551No roundtripping. 874No round-tripping.
552 875
553Does not generate valid JSON texts (key strings are often unquoted, empty keys 876Does not generate valid JSON texts (key strings are often unquoted, empty keys
554result in nothing being output) 877result in nothing being output)
555 878
556Does not check input for validity. 879Does not check input for validity.
557 880
558=back 881=back
882
883
884=head2 JSON and YAML
885
886You often hear that JSON is a subset (or a close subset) of YAML. This is,
887however, a mass hysteria and very far from the truth. In general, there is
888no way to configure JSON::XS to output a data structure as valid YAML.
889
890If you really must use JSON::XS to generate YAML, you should use this
891algorithm (subject to change in future versions):
892
893 my $to_yaml = JSON::XS->new->utf8->space_after (1);
894 my $yaml = $to_yaml->encode ($ref) . "\n";
895
896This will usually generate JSON texts that also parse as valid
897YAML. Please note that YAML has hardcoded limits on (simple) object key
898lengths that JSON doesn't have, so you should make sure that your hash
899keys are noticeably shorter than the 1024 characters YAML allows.
900
901There might be other incompatibilities that I am not aware of. In general
902you should not try to generate YAML with a JSON generator or vice versa,
903or try to parse JSON with a YAML parser or vice versa: chances are high
904that you will run into severe interoperability problems.
905
559 906
560=head2 SPEED 907=head2 SPEED
561 908
562It seems that JSON::XS is surprisingly fast, as shown in the following 909It seems that JSON::XS is surprisingly fast, as shown in the following
563tables. They have been generated with the help of the C<eg/bench> program 910tables. They have been generated with the help of the C<eg/bench> program
564in the JSON::XS distribution, to make it easy to compare on your own 911in the JSON::XS distribution, to make it easy to compare on your own
565system. 912system.
566 913
567First comes a comparison between various modules using a very short JSON 914First comes a comparison between various modules using a very short
568string: 915single-line JSON string:
569 916
570 {"method": "handleMessage", "params": ["user1", "we were just talking"], "id": null} 917 {"method": "handleMessage", "params": ["user1", "we were just talking"], \
918 "id": null, "array":[1,11,234,-5,1e5,1e7, true, false]}
571 919
572It shows the number of encodes/decodes per second (JSON::XS uses the 920It shows the number of encodes/decodes per second (JSON::XS uses
573functional interface, while JSON::XS/2 uses the OO interface with 921the functional interface, while JSON::XS/2 uses the OO interface
574pretty-printing and hashkey sorting enabled). Higher is better: 922with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables
923shrink). Higher is better:
575 924
576 module | encode | decode | 925 module | encode | decode |
577 -----------|------------|------------| 926 -----------|------------|------------|
578 JSON | 11488.516 | 7823.035 | 927 JSON 1.x | 4990.842 | 4088.813 |
579 JSON::DWIW | 94708.054 | 129094.260 | 928 JSON::DWIW | 51653.990 | 71575.154 |
580 JSON::PC | 63884.157 | 128528.212 | 929 JSON::PC | 65948.176 | 74631.744 |
581 JSON::Syck | 34898.677 | 42096.911 | 930 JSON::PP | 8931.652 | 3817.168 |
582 JSON::XS | 654027.064 | 396423.669 | 931 JSON::Syck | 24877.248 | 27776.848 |
583 JSON::XS/2 | 371564.190 | 371725.613 | 932 JSON::XS | 388361.481 | 227951.304 |
933 JSON::XS/2 | 227951.304 | 218453.333 |
934 JSON::XS/3 | 338250.323 | 218453.333 |
935 Storable | 16500.016 | 135300.129 |
584 -----------+------------+------------+ 936 -----------+------------+------------+
585 937
586That is, JSON::XS is more than six times faster than JSON::DWIW on 938That is, JSON::XS is about five times faster than JSON::DWIW on encoding,
587encoding, more than three times faster on decoding, and about thirty times 939about three times faster on decoding, and over forty times faster
588faster than JSON, even with pretty-printing and key sorting. 940than JSON, even with pretty-printing and key sorting. It also compares
941favourably to Storable for small amounts of data.
589 942
590Using a longer test string (roughly 18KB, generated from Yahoo! Locals 943Using a longer test string (roughly 18KB, generated from Yahoo! Locals
591search API (http://nanoref.com/yahooapis/mgPdGg): 944search API (http://nanoref.com/yahooapis/mgPdGg):
592 945
593 module | encode | decode | 946 module | encode | decode |
594 -----------|------------|------------| 947 -----------|------------|------------|
595 JSON | 273.023 | 44.674 | 948 JSON 1.x | 55.260 | 34.971 |
596 JSON::DWIW | 1089.383 | 1145.704 | 949 JSON::DWIW | 825.228 | 1082.513 |
597 JSON::PC | 3097.419 | 2393.921 | 950 JSON::PC | 3571.444 | 2394.829 |
598 JSON::Syck | 514.060 | 843.053 | 951 JSON::PP | 210.987 | 32.574 |
599 JSON::XS | 6479.668 | 3636.364 | 952 JSON::Syck | 552.551 | 787.544 |
600 JSON::XS/2 | 3774.221 | 3599.124 | 953 JSON::XS | 5780.463 | 4854.519 |
954 JSON::XS/2 | 3869.998 | 4798.975 |
955 JSON::XS/3 | 5862.880 | 4798.975 |
956 Storable | 4445.002 | 5235.027 |
601 -----------+------------+------------+ 957 -----------+------------+------------+
602 958
603Again, JSON::XS leads by far. 959Again, JSON::XS leads by far (except for Storable which non-surprisingly
960decodes faster).
604 961
605On large strings containing lots of high unicode characters, some modules 962On large strings containing lots of high Unicode characters, some modules
606(such as JSON::PC) seem to decode faster than JSON::XS, but the result 963(such as JSON::PC) seem to decode faster than JSON::XS, but the result
607will be broken due to missing (or wrong) unicode handling. Others refuse 964will be broken due to missing (or wrong) Unicode handling. Others refuse
608to decode or encode properly, so it was impossible to prepare a fair 965to decode or encode properly, so it was impossible to prepare a fair
609comparison table for that case. 966comparison table for that case.
610 967
611 968
612=head1 SECURITY CONSIDERATIONS 969=head1 SECURITY CONSIDERATIONS
… …
618any buffer overflows. Obviously, this module should ensure that and I am 975any buffer overflows. Obviously, this module should ensure that and I am
619trying hard on making that true, but you never know. 976trying hard on making that true, but you never know.
620 977
621Second, you need to avoid resource-starving attacks. That means you should 978Second, you need to avoid resource-starving attacks. That means you should
622limit the size of JSON texts you accept, or make sure then when your 979limit the size of JSON texts you accept, or make sure then when your
623resources run out, thats just fine (e.g. by using a separate process that 980resources run out, that's just fine (e.g. by using a separate process that
624can crash safely). The size of a JSON text in octets or characters is 981can crash safely). The size of a JSON text in octets or characters is
625usually a good indication of the size of the resources required to decode 982usually a good indication of the size of the resources required to decode
626it into a Perl structure. 983it into a Perl structure. While JSON::XS can check the size of the JSON
984text, it might be too late when you already have it in memory, so you
985might want to check the size before you accept the string.
627 986
628Third, JSON::XS recurses using the C stack when decoding objects and 987Third, JSON::XS recurses using the C stack when decoding objects and
629arrays. The C stack is a limited resource: for instance, on my amd64 988arrays. The C stack is a limited resource: for instance, on my amd64
630machine with 8MB of stack size I can decode around 180k nested arrays 989machine with 8MB of stack size I can decode around 180k nested arrays but
631but only 14k nested JSON objects. If that is exceeded, the program 990only 14k nested JSON objects (due to perl itself recursing deeply on croak
991to free the temporary). If that is exceeded, the program crashes. to be
632crashes. Thats why the default nesting limit is set to 8192. If your 992conservative, the default nesting limit is set to 512. If your process
633process has a smaller stack, you should adjust this setting accordingly 993has a smaller stack, you should adjust this setting accordingly with the
634with the C<max_depth> method. 994C<max_depth> method.
635 995
636And last but least, something else could bomb you that I forgot to think 996And last but least, something else could bomb you that I forgot to think
637of. In that case, you get to keep the pieces. I am alway sopen for hints, 997of. In that case, you get to keep the pieces. I am always open for hints,
638though... 998though...
999
1000If you are using JSON::XS to return packets to consumption
1001by JavaScript scripts in a browser you should have a look at
1002L<http://jpsykes.com/47/practical-csrf-and-json-security> to see whether
1003you are vulnerable to some common attack vectors (which really are browser
1004design bugs, but it is still you who will have to deal with it, as major
1005browser developers care only for features, not about doing security
1006right).
1007
1008
1009=head1 THREADS
1010
1011This module is I<not> guaranteed to be thread safe and there are no
1012plans to change this until Perl gets thread support (as opposed to the
1013horribly slow so-called "threads" which are simply slow and bloated
1014process simulations - use fork, its I<much> faster, cheaper, better).
1015
1016(It might actually work, but you have been warned).
639 1017
640 1018
641=head1 BUGS 1019=head1 BUGS
642 1020
643While the goal of this module is to be correct, that unfortunately does 1021While the goal of this module is to be correct, that unfortunately does
644not mean its bug-free, only that I think its design is bug-free. It is 1022not mean its bug-free, only that I think its design is bug-free. It is
645still relatively early in its development. If you keep reporting bugs they 1023still relatively early in its development. If you keep reporting bugs they
646will be fixed swiftly, though. 1024will be fixed swiftly, though.
647 1025
1026Please refrain from using rt.cpan.org or any other bug reporting
1027service. I put the contact address into my modules for a reason.
1028
648=cut 1029=cut
1030
1031our $true = do { bless \(my $dummy = 1), "JSON::XS::Boolean" };
1032our $false = do { bless \(my $dummy = 0), "JSON::XS::Boolean" };
1033
1034sub true() { $true }
1035sub false() { $false }
1036
1037sub is_bool($) {
1038 UNIVERSAL::isa $_[0], "JSON::XS::Boolean"
1039# or UNIVERSAL::isa $_[0], "JSON::Literal"
1040}
1041
1042XSLoader::load "JSON::XS", $VERSION;
1043
1044package JSON::XS::Boolean;
1045
1046use overload
1047 "0+" => sub { ${$_[0]} },
1048 "++" => sub { $_[0] = ${$_[0]} + 1 },
1049 "--" => sub { $_[0] = ${$_[0]} - 1 },
1050 fallback => 1;
649 1051
6501; 10521;
651 1053
652=head1 AUTHOR 1054=head1 AUTHOR
653 1055

Diff Legend

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