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.25 by root, Thu Mar 29 02:45:49 2007 UTC vs.
Revision 1.77 by root, Tue Dec 4 10:37:42 2007 UTC

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

Diff Legend

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