Filename	/usr/lib/x86_64-linux-gnu/perl5/5.20/JSON/XS.pm
Statements	Executed 15 statements in 2.05ms

Subroutines

Calls	P	F	Exclusive Time	Inclusive Time	Subroutine
1	1	1	981µs	1.21ms	DynaLoader::::BEGIN@92 DynaLoader::BEGIN@92
1	1	1	176µs	196µs	JSON::XS::::BEGIN@104 JSON::XS::BEGIN@104
1	1	1	17µs	60µs	JSON::XS::Boolean::::BEGIN@1497JSON::XS::Boolean::BEGIN@1497
1	1	1	12µs	34µs	JSON::XS::::BEGIN@121 JSON::XS::BEGIN@121
1	1	1	7µs	7µs	JSON::XS::::BEGIN@122 JSON::XS::BEGIN@122
0	0	0	0s	0s	JSON::XS::Boolean::::__ANON__[:1497]JSON::XS::Boolean::__ANON__[:1497]
0	0	0	0s	0s	JSON::XS::Boolean::::__ANON__[:1498]JSON::XS::Boolean::__ANON__[:1498]
0	0	0	0s	0s	JSON::XS::Boolean::::__ANON__[:1499]JSON::XS::Boolean::__ANON__[:1499]
0	0	0	0s	0s	JSON::XS::::false JSON::XS::false
0	0	0	0s	0s	JSON::XS::::from_json JSON::XS::from_json
0	0	0	0s	0s	JSON::XS::::is_bool JSON::XS::is_bool
0	0	0	0s	0s	JSON::XS::::to_json JSON::XS::to_json
0	0	0	0s	0s	JSON::XS::::true JSON::XS::true

Call graph for these subroutines as a Graphviz dot language file.

Line	State ments	Time on line	Calls	Time in subs	Code
0			1	1.21ms	Profile data that couldn't be associated with a specific line: # spent 1.21ms making 1 call to DynaLoader::BEGIN@92
1	1	30µs			=head1 NAME
2
3					JSON::XS - JSON serialising/deserialising, done correctly and fast
4
5					=encoding utf-8
6
7					JSON::XS - 正しくて高速な JSON シリアライザ/デシリアライザ
8					(http://fleur.hio.jp/perldoc/mix/lib/JSON/XS.html)
9
10					=head1 SYNOPSIS
11
12					use JSON::XS;
13
14					# exported functions, they croak on error
15					# and expect/generate UTF-8
16
17					$utf8_encoded_json_text = encode_json $perl_hash_or_arrayref;
18					$perl_hash_or_arrayref = decode_json $utf8_encoded_json_text;
19
20					# OO-interface
21
22					$coder = JSON::XS->new->ascii->pretty->allow_nonref;
23					$pretty_printed_unencoded = $coder->encode ($perl_scalar);
24					$perl_scalar = $coder->decode ($unicode_json_text);
25
26					# Note that JSON version 2.0 and above will automatically use JSON::XS
27					# if available, at virtually no speed overhead either, so you should
28					# be able to just:
29
30					use JSON;
31
32					# and do the same things, except that you have a pure-perl fallback now.
33
34					=head1 DESCRIPTION
35
36					This module converts Perl data structures to JSON and vice versa. Its
37					primary goal is to be I<correct> and its secondary goal is to be
38					I<fast>. To reach the latter goal it was written in C.
39
40					Beginning with version 2.0 of the JSON module, when both JSON and
41					JSON::XS are installed, then JSON will fall back on JSON::XS (this can be
42					overridden) with no overhead due to emulation (by inheriting constructor
43					and methods). If JSON::XS is not available, it will fall back to the
44					compatible JSON::PP module as backend, so using JSON instead of JSON::XS
45					gives you a portable JSON API that can be fast when you need and doesn't
46					require a C compiler when that is a problem.
47
48					As this is the n-th-something JSON module on CPAN, what was the reason
49					to write yet another JSON module? While it seems there are many JSON
50					modules, none of them correctly handle all corner cases, and in most cases
51					their maintainers are unresponsive, gone missing, or not listening to bug
52					reports for other reasons.
53
54					See MAPPING, below, on how JSON::XS maps perl values to JSON values and
55					vice versa.
56
57					=head2 FEATURES
58
59					=over 4
60
61					=item * correct Unicode handling
62
63					This module knows how to handle Unicode, documents how and when it does
64					so, and even documents what "correct" means.
65
66					=item * round-trip integrity
67
68					When you serialise a perl data structure using only data types supported
69					by JSON and Perl, the deserialised data structure is identical on the Perl
70					level. (e.g. the string "2.0" doesn't suddenly become "2" just because
71					it looks like a number). There I<are> minor exceptions to this, read the
72					MAPPING section below to learn about those.
73
74					=item * strict checking of JSON correctness
75
76					There is no guessing, no generating of illegal JSON texts by default,
77					and only JSON is accepted as input by default (the latter is a security
78					feature).
79
80					=item * fast
81
82					Compared to other JSON modules and other serialisers such as Storable,
83					this module usually compares favourably in terms of speed, too.
84
85					=item * simple to use
86
87					This module has both a simple functional interface as well as an object
88					oriented interface interface.
89
90					=item * reasonably versatile output formats
91
92					# spent 1.21ms (981µs+229µs) within DynaLoader::BEGIN@92 which was called: # once (981µs+229µs) by XSLoader::load at line 0 You can choose between the most compact guaranteed-single-line format
93					possible (nice for simple line-based protocols), a pure-ASCII format
94					(for when your transport is not 8-bit clean, still supports the whole
95					Unicode range), or a pretty-printed format (for when you want to read that
96					stuff). Or you can combine those features in whatever way you like.
97
98					=back
99
100					=cut
101
102					package JSON::XS;
103
104	2	319µs	2	217µs	# spent 196µs (176+20) within JSON::XS::BEGIN@104 which was called: # once (176µs+20µs) by JSON::BEGIN@2 at line 104 use common::sense; # spent 196µs making 1 call to JSON::XS::BEGIN@104 # spent 20µs making 1 call to common::sense::import
105
106	1	400ns			our $VERSION = 2.34;
107	1	8µs			our @ISA = qw(Exporter);
108
109	1	700ns			our @EXPORT = qw(encode_json decode_json to_json from_json);
110
111					sub to_json($) {
112					require Carp;
113					Carp::croak ("JSON::XS::to_json has been renamed to encode_json, either downgrade to pre-2.0 versions of JSON::XS or rename the call");
114					}
115
116					sub from_json($) {
117					require Carp;
118					Carp::croak ("JSON::XS::from_json has been renamed to decode_json, either downgrade to pre-2.0 versions of JSON::XS or rename the call");
119					}
120
121	2	59µs	2	55µs	# spent 34µs (12+22) within JSON::XS::BEGIN@121 which was called: # once (12µs+22µs) by JSON::BEGIN@2 at line 121 use Exporter; # spent 34µs making 1 call to JSON::XS::BEGIN@121 # spent 22µs making 1 call to Exporter::import
122	2	1.13ms	1	7µs	# spent 7µs within JSON::XS::BEGIN@122 which was called: # once (7µs+0s) by JSON::BEGIN@2 at line 122 use XSLoader; # spent 7µs making 1 call to JSON::XS::BEGIN@122
123
124					=head1 FUNCTIONAL INTERFACE
125
126					The following convenience methods are provided by this module. They are
127					exported by default:
128
129					=over 4
130
131					=item $json_text = encode_json $perl_scalar
132
133					Converts the given Perl data structure to a UTF-8 encoded, binary string
134					(that is, the string contains octets only). Croaks on error.
135
136					This function call is functionally identical to:
137
138					$json_text = JSON::XS->new->utf8->encode ($perl_scalar)
139
140					Except being faster.
141
142					=item $perl_scalar = decode_json $json_text
143
144					The opposite of C<encode_json>: expects an UTF-8 (binary) string and tries
145					to parse that as an UTF-8 encoded JSON text, returning the resulting
146					reference. Croaks on error.
147
148					This function call is functionally identical to:
149
150					$perl_scalar = JSON::XS->new->utf8->decode ($json_text)
151
152					Except being faster.
153
154					=item $is_boolean = JSON::XS::is_bool $scalar
155
156					Returns true if the passed scalar represents either JSON::XS::true or
157					JSON::XS::false, two constants that act like C<1> and C<0>, respectively
158					and are used to represent JSON C<true> and C<false> values in Perl.
159
160					See MAPPING, below, for more information on how JSON values are mapped to
161					Perl.
162
163					=back
164
165
166					=head1 A FEW NOTES ON UNICODE AND PERL
167
168					Since this often leads to confusion, here are a few very clear words on
169					how Unicode works in Perl, modulo bugs.
170
171					=over 4
172
173					=item 1. Perl strings can store characters with ordinal values > 255.
174
175					This enables you to store Unicode characters as single characters in a
176					Perl string - very natural.
177
178					=item 2. Perl does I<not> associate an encoding with your strings.
179
180					... until you force it to, e.g. when matching it against a regex, or
181					printing the scalar to a file, in which case Perl either interprets your
182					string as locale-encoded text, octets/binary, or as Unicode, depending
183					on various settings. In no case is an encoding stored together with your
184					data, it is I<use> that decides encoding, not any magical meta data.
185
186					=item 3. The internal utf-8 flag has no meaning with regards to the
187					encoding of your string.
188
189					Just ignore that flag unless you debug a Perl bug, a module written in
190					XS or want to dive into the internals of perl. Otherwise it will only
191					confuse you, as, despite the name, it says nothing about how your string
192					is encoded. You can have Unicode strings with that flag set, with that
193					flag clear, and you can have binary data with that flag set and that flag
194					clear. Other possibilities exist, too.
195
196					If you didn't know about that flag, just the better, pretend it doesn't
197					exist.
198
199					=item 4. A "Unicode String" is simply a string where each character can be
200					validly interpreted as a Unicode code point.
201
202					If you have UTF-8 encoded data, it is no longer a Unicode string, but a
203					Unicode string encoded in UTF-8, giving you a binary string.
204
205					=item 5. A string containing "high" (> 255) character values is I<not> a UTF-8 string.
206
207					It's a fact. Learn to live with it.
208
209					=back
210
211					I hope this helps :)
212
213
214					=head1 OBJECT-ORIENTED INTERFACE
215
216					The object oriented interface lets you configure your own encoding or
217					decoding style, within the limits of supported formats.
218
219					=over 4
220
221					=item $json = new JSON::XS
222
223					Creates a new JSON::XS object that can be used to de/encode JSON
224					strings. All boolean flags described below are by default I<disabled>.
225
226					The mutators for flags all return the JSON object again and thus calls can
227					be chained:
228
229					my $json = JSON::XS->new->utf8->space_after->encode ({a => [1,2]})
230					=> {"a": [1, 2]}
231
232					=item $json = $json->ascii ([$enable])
233
234					=item $enabled = $json->get_ascii
235
236					If C<$enable> is true (or missing), then the C<encode> method will not
237					generate characters outside the code range C<0..127> (which is ASCII). Any
238					Unicode characters outside that range will be escaped using either a
239					single \uXXXX (BMP characters) or a double \uHHHH\uLLLLL escape sequence,
240					as per RFC4627. The resulting encoded JSON text can be treated as a native
241					Unicode string, an ascii-encoded, latin1-encoded or UTF-8 encoded string,
242					or any other superset of ASCII.
243
244					If C<$enable> is false, then the C<encode> method will not escape Unicode
245					characters unless required by the JSON syntax or other flags. This results
246					in a faster and more compact format.
247
248					See also the section I<ENCODING/CODESET FLAG NOTES> later in this
249					document.
250
251					The main use for this flag is to produce JSON texts that can be
252					transmitted over a 7-bit channel, as the encoded JSON texts will not
253					contain any 8 bit characters.
254
255					JSON::XS->new->ascii (1)->encode ([chr 0x10401])
256					=> ["\ud801\udc01"]
257
258					=item $json = $json->latin1 ([$enable])
259
260					=item $enabled = $json->get_latin1
261
262					If C<$enable> is true (or missing), then the C<encode> method will encode
263					the resulting JSON text as latin1 (or iso-8859-1), escaping any characters
264					outside the code range C<0..255>. The resulting string can be treated as a
265					latin1-encoded JSON text or a native Unicode string. The C<decode> method
266					will not be affected in any way by this flag, as C<decode> by default
267					expects Unicode, which is a strict superset of latin1.
268
269					If C<$enable> is false, then the C<encode> method will not escape Unicode
270					characters unless required by the JSON syntax or other flags.
271
272					See also the section I<ENCODING/CODESET FLAG NOTES> later in this
273					document.
274
275					The main use for this flag is efficiently encoding binary data as JSON
276					text, as most octets will not be escaped, resulting in a smaller encoded
277					size. The disadvantage is that the resulting JSON text is encoded
278					in latin1 (and must correctly be treated as such when storing and
279					transferring), a rare encoding for JSON. It is therefore most useful when
280					you want to store data structures known to contain binary data efficiently
281					in files or databases, not when talking to other JSON encoders/decoders.
282
283					JSON::XS->new->latin1->encode (["\x{89}\x{abc}"]
284					=> ["\x{89}\\u0abc"] # (perl syntax, U+abc escaped, U+89 not)
285
286					=item $json = $json->utf8 ([$enable])
287
288					=item $enabled = $json->get_utf8
289
290					If C<$enable> is true (or missing), then the C<encode> method will encode
291					the JSON result into UTF-8, as required by many protocols, while the
292					C<decode> method expects to be handled an UTF-8-encoded string. Please
293					note that UTF-8-encoded strings do not contain any characters outside the
294					range C<0..255>, they are thus useful for bytewise/binary I/O. In future
295					versions, enabling this option might enable autodetection of the UTF-16
296					and UTF-32 encoding families, as described in RFC4627.
297
298					If C<$enable> is false, then the C<encode> method will return the JSON
299					string as a (non-encoded) Unicode string, while C<decode> expects thus a
300					Unicode string. Any decoding or encoding (e.g. to UTF-8 or UTF-16) needs
301					to be done yourself, e.g. using the Encode module.
302
303					See also the section I<ENCODING/CODESET FLAG NOTES> later in this
304					document.
305
306					Example, output UTF-16BE-encoded JSON:
307
308					use Encode;
309					$jsontext = encode "UTF-16BE", JSON::XS->new->encode ($object);
310
311					Example, decode UTF-32LE-encoded JSON:
312
313					use Encode;
314					$object = JSON::XS->new->decode (decode "UTF-32LE", $jsontext);
315
316					=item $json = $json->pretty ([$enable])
317
318					This enables (or disables) all of the C<indent>, C<space_before> and
319					C<space_after> (and in the future possibly more) flags in one call to
320					generate the most readable (or most compact) form possible.
321
322					Example, pretty-print some simple structure:
323
324					my $json = JSON::XS->new->pretty(1)->encode ({a => [1,2]})
325					=>
326					{
327					"a" : [
328					1,
329					2
330					]
331					}
332
333					=item $json = $json->indent ([$enable])
334
335					=item $enabled = $json->get_indent
336
337					If C<$enable> is true (or missing), then the C<encode> method will use a multiline
338					format as output, putting every array member or object/hash key-value pair
339					into its own line, indenting them properly.
340
341					If C<$enable> is false, no newlines or indenting will be produced, and the
342					resulting JSON text is guaranteed not to contain any C<newlines>.
343
344					This setting has no effect when decoding JSON texts.
345
346					=item $json = $json->space_before ([$enable])
347
348					=item $enabled = $json->get_space_before
349
350					If C<$enable> is true (or missing), then the C<encode> method will add an extra
351					optional space before the C<:> separating keys from values in JSON objects.
352
353					If C<$enable> is false, then the C<encode> method will not add any extra
354					space at those places.
355
356					This setting has no effect when decoding JSON texts. You will also
357					most likely combine this setting with C<space_after>.
358
359					Example, space_before enabled, space_after and indent disabled:
360
361					{"key" :"value"}
362
363					=item $json = $json->space_after ([$enable])
364
365					=item $enabled = $json->get_space_after
366
367					If C<$enable> is true (or missing), then the C<encode> method will add an extra
368					optional space after the C<:> separating keys from values in JSON objects
369					and extra whitespace after the C<,> separating key-value pairs and array
370					members.
371
372					If C<$enable> is false, then the C<encode> method will not add any extra
373					space at those places.
374
375					This setting has no effect when decoding JSON texts.
376
377					Example, space_before and indent disabled, space_after enabled:
378
379					{"key": "value"}
380
381					=item $json = $json->relaxed ([$enable])
382
383					=item $enabled = $json->get_relaxed
384
385					If C<$enable> is true (or missing), then C<decode> will accept some
386					extensions to normal JSON syntax (see below). C<encode> will not be
387					affected in anyway. I<Be aware that this option makes you accept invalid
388					JSON texts as if they were valid!>. I suggest only to use this option to
389					parse application-specific files written by humans (configuration files,
390					resource files etc.)
391
392					If C<$enable> is false (the default), then C<decode> will only accept
393					valid JSON texts.
394
395					Currently accepted extensions are:
396
397					=over 4
398
399					=item * list items can have an end-comma
400
401					JSON I<separates> array elements and key-value pairs with commas. This
402					can be annoying if you write JSON texts manually and want to be able to
403					quickly append elements, so this extension accepts comma at the end of
404					such items not just between them:
405
406					[
407					1,
408					2, <- this comma not normally allowed
409					]
410					{
411					"k1": "v1",
412					"k2": "v2", <- this comma not normally allowed
413					}
414
415					=item * shell-style '#'-comments
416
417					Whenever JSON allows whitespace, shell-style comments are additionally
418					allowed. They are terminated by the first carriage-return or line-feed
419					character, after which more white-space and comments are allowed.
420
421					[
422					1, # this comment not allowed in JSON
423					# neither this one...
424					]
425
426					=back
427
428					=item $json = $json->canonical ([$enable])
429
430					=item $enabled = $json->get_canonical
431
432					If C<$enable> is true (or missing), then the C<encode> method will output JSON objects
433					by sorting their keys. This is adding a comparatively high overhead.
434
435					If C<$enable> is false, then the C<encode> method will output key-value
436					pairs in the order Perl stores them (which will likely change between runs
437					of the same script, and can change even within the same run from 5.18
438					onwards).
439
440					This option is useful if you want the same data structure to be encoded as
441					the same JSON text (given the same overall settings). If it is disabled,
442					the same hash might be encoded differently even if contains the same data,
443					as key-value pairs have no inherent ordering in Perl.
444
445					This setting has no effect when decoding JSON texts.
446
447					This setting has currently no effect on tied hashes.
448
449					=item $json = $json->allow_nonref ([$enable])
450
451					=item $enabled = $json->get_allow_nonref
452
453					If C<$enable> is true (or missing), then the C<encode> method can convert a
454					non-reference into its corresponding string, number or null JSON value,
455					which is an extension to RFC4627. Likewise, C<decode> will accept those JSON
456					values instead of croaking.
457
458					If C<$enable> is false, then the C<encode> method will croak if it isn't
459					passed an arrayref or hashref, as JSON texts must either be an object
460					or array. Likewise, C<decode> will croak if given something that is not a
461					JSON object or array.
462
463					Example, encode a Perl scalar as JSON value with enabled C<allow_nonref>,
464					resulting in an invalid JSON text:
465
466					JSON::XS->new->allow_nonref->encode ("Hello, World!")
467					=> "Hello, World!"
468
469					=item $json = $json->allow_unknown ([$enable])
470
471					=item $enabled = $json->get_allow_unknown
472
473					If C<$enable> is true (or missing), then C<encode> will I<not> throw an
474					exception when it encounters values it cannot represent in JSON (for
475					example, filehandles) but instead will encode a JSON C<null> value. Note
476					that blessed objects are not included here and are handled separately by
477					c<allow_nonref>.
478
479					If C<$enable> is false (the default), then C<encode> will throw an
480					exception when it encounters anything it cannot encode as JSON.
481
482					This option does not affect C<decode> in any way, and it is recommended to
483					leave it off unless you know your communications partner.
484
485					=item $json = $json->allow_blessed ([$enable])
486
487					=item $enabled = $json->get_allow_blessed
488
489					If C<$enable> is true (or missing), then the C<encode> method will not
490					barf when it encounters a blessed reference. Instead, the value of the
491					B<convert_blessed> option will decide whether C<null> (C<convert_blessed>
492					disabled or no C<TO_JSON> method found) or a representation of the
493					object (C<convert_blessed> enabled and C<TO_JSON> method found) is being
494					encoded. Has no effect on C<decode>.
495
496					If C<$enable> is false (the default), then C<encode> will throw an
497					exception when it encounters a blessed object.
498
499					=item $json = $json->convert_blessed ([$enable])
500
501					=item $enabled = $json->get_convert_blessed
502
503					If C<$enable> is true (or missing), then C<encode>, upon encountering a
504					blessed object, will check for the availability of the C<TO_JSON> method
505					on the object's class. If found, it will be called in scalar context
506					and the resulting scalar will be encoded instead of the object. If no
507					C<TO_JSON> method is found, the value of C<allow_blessed> will decide what
508					to do.
509
510					The C<TO_JSON> method may safely call die if it wants. If C<TO_JSON>
511					returns other blessed objects, those will be handled in the same
512					way. C<TO_JSON> must take care of not causing an endless recursion cycle
513					(== crash) in this case. The name of C<TO_JSON> was chosen because other
514					methods called by the Perl core (== not by the user of the object) are
515					usually in upper case letters and to avoid collisions with any C<to_json>
516					function or method.
517
518					This setting does not yet influence C<decode> in any way, but in the
519					future, global hooks might get installed that influence C<decode> and are
520					enabled by this setting.
521
522					If C<$enable> is false, then the C<allow_blessed> setting will decide what
523					to do when a blessed object is found.
524
525					=item $json = $json->filter_json_object ([$coderef->($hashref)])
526
527					When C<$coderef> is specified, it will be called from C<decode> each
528					time it decodes a JSON object. The only argument is a reference to the
529					newly-created hash. If the code references returns a single scalar (which
530					need not be a reference), this value (i.e. a copy of that scalar to avoid
531					aliasing) is inserted into the deserialised data structure. If it returns
532					an empty list (NOTE: I<not> C<undef>, which is a valid scalar), the
533					original deserialised hash will be inserted. This setting can slow down
534					decoding considerably.
535
536					When C<$coderef> is omitted or undefined, any existing callback will
537					be removed and C<decode> will not change the deserialised hash in any
538					way.
539
540					Example, convert all JSON objects into the integer 5:
541
542					my $js = JSON::XS->new->filter_json_object (sub { 5 });
543					# returns [5]
544					$js->decode ('[{}]')
545					# throw an exception because allow_nonref is not enabled
546					# so a lone 5 is not allowed.
547					$js->decode ('{"a":1, "b":2}');
548
549					=item $json = $json->filter_json_single_key_object ($key [=> $coderef->($value)])
550
551					Works remotely similar to C<filter_json_object>, but is only called for
552					JSON objects having a single key named C<$key>.
553
554					This C<$coderef> is called before the one specified via
555					C<filter_json_object>, if any. It gets passed the single value in the JSON
556					object. If it returns a single value, it will be inserted into the data
557					structure. If it returns nothing (not even C<undef> but the empty list),
558					the callback from C<filter_json_object> will be called next, as if no
559					single-key callback were specified.
560
561					If C<$coderef> is omitted or undefined, the corresponding callback will be
562					disabled. There can only ever be one callback for a given key.
563
564					As this callback gets called less often then the C<filter_json_object>
565					one, decoding speed will not usually suffer as much. Therefore, single-key
566					objects make excellent targets to serialise Perl objects into, especially
567					as single-key JSON objects are as close to the type-tagged value concept
568					as JSON gets (it's basically an ID/VALUE tuple). Of course, JSON does not
569					support this in any way, so you need to make sure your data never looks
570					like a serialised Perl hash.
571
572					Typical names for the single object key are C<__class_whatever__>, or
573					C<$__dollars_are_rarely_used__$> or C<}ugly_brace_placement>, or even
574					things like C<__class_md5sum(classname)__>, to reduce the risk of clashing
575					with real hashes.
576
577					Example, decode JSON objects of the form C<< { "__widget__" => <id> } >>
578					into the corresponding C<< $WIDGET{<id>} >> object:
579
580					# return whatever is in $WIDGET{5}:
581					JSON::XS
582					->new
583					->filter_json_single_key_object (__widget__ => sub {
584					$WIDGET{ $_[0] }
585					})
586					->decode ('{"__widget__": 5')
587
588					# this can be used with a TO_JSON method in some "widget" class
589					# for serialisation to json:
590					sub WidgetBase::TO_JSON {
591					my ($self) = @_;
592
593					unless ($self->{id}) {
594					$self->{id} = ..get..some..id..;
595					$WIDGET{$self->{id}} = $self;
596					}
597
598					{ __widget__ => $self->{id} }
599					}
600
601					=item $json = $json->shrink ([$enable])
602
603					=item $enabled = $json->get_shrink
604
605					Perl usually over-allocates memory a bit when allocating space for
606					strings. This flag optionally resizes strings generated by either
607					C<encode> or C<decode> to their minimum size possible. This can save
608					memory when your JSON texts are either very very long or you have many
609					short strings. It will also try to downgrade any strings to octet-form
610					if possible: perl stores strings internally either in an encoding called
611					UTF-X or in octet-form. The latter cannot store everything but uses less
612					space in general (and some buggy Perl or C code might even rely on that
613					internal representation being used).
614
615					The actual definition of what shrink does might change in future versions,
616					but it will always try to save space at the expense of time.
617
618					If C<$enable> is true (or missing), the string returned by C<encode> will
619					be shrunk-to-fit, while all strings generated by C<decode> will also be
620					shrunk-to-fit.
621
622					If C<$enable> is false, then the normal perl allocation algorithms are used.
623					If you work with your data, then this is likely to be faster.
624
625					In the future, this setting might control other things, such as converting
626					strings that look like integers or floats into integers or floats
627					internally (there is no difference on the Perl level), saving space.
628
629					=item $json = $json->max_depth ([$maximum_nesting_depth])
630
631					=item $max_depth = $json->get_max_depth
632
633					Sets the maximum nesting level (default C<512>) accepted while encoding
634					or decoding. If a higher nesting level is detected in JSON text or a Perl
635					data structure, then the encoder and decoder will stop and croak at that
636					point.
637
638					Nesting level is defined by number of hash- or arrayrefs that the encoder
639					needs to traverse to reach a given point or the number of C<{> or C<[>
640					characters without their matching closing parenthesis crossed to reach a
641					given character in a string.
642
643					Setting the maximum depth to one disallows any nesting, so that ensures
644					that the object is only a single hash/object or array.
645
646					If no argument is given, the highest possible setting will be used, which
647					is rarely useful.
648
649					Note that nesting is implemented by recursion in C. The default value has
650					been chosen to be as large as typical operating systems allow without
651					crashing.
652
653					See SECURITY CONSIDERATIONS, below, for more info on why this is useful.
654
655					=item $json = $json->max_size ([$maximum_string_size])
656
657					=item $max_size = $json->get_max_size
658
659					Set the maximum length a JSON text may have (in bytes) where decoding is
660					being attempted. The default is C<0>, meaning no limit. When C<decode>
661					is called on a string that is longer then this many bytes, it will not
662					attempt to decode the string but throw an exception. This setting has no
663					effect on C<encode> (yet).
664
665					If no argument is given, the limit check will be deactivated (same as when
666					C<0> is specified).
667
668					See SECURITY CONSIDERATIONS, below, for more info on why this is useful.
669
670					=item $json_text = $json->encode ($perl_scalar)
671
672					Converts the given Perl data structure (a simple scalar or a reference
673					to a hash or array) to its JSON representation. Simple scalars will be
674					converted into JSON string or number sequences, while references to arrays
675					become JSON arrays and references to hashes become JSON objects. Undefined
676					Perl values (e.g. C<undef>) become JSON C<null> values. Neither C<true>
677					nor C<false> values will be generated.
678
679					=item $perl_scalar = $json->decode ($json_text)
680
681					The opposite of C<encode>: expects a JSON text and tries to parse it,
682					returning the resulting simple scalar or reference. Croaks on error.
683
684					JSON numbers and strings become simple Perl scalars. JSON arrays become
685					Perl arrayrefs and JSON objects become Perl hashrefs.
686					C<true> becomes JSON::XS::true (equals 1 numerically and as a string),
687					C<false> becomes JSON::XS::false (equals 0) and C<null> becomes C<undef>.
688
689					=item ($perl_scalar, $characters) = $json->decode_prefix ($json_text)
690
691					This works like the C<decode> method, but instead of raising an exception
692					when there is trailing garbage after the first JSON object, it will
693					silently stop parsing there and return the number of characters consumed
694					so far.
695
696					This is useful if your JSON texts are not delimited by an outer protocol
697					(which is not the brightest thing to do in the first place) and you need
698					to know where the JSON text ends.
699
700					JSON::XS->new->decode_prefix ("[1] the tail")
701					=> ([], 3)
702
703					=back
704
705
706					=head1 INCREMENTAL PARSING
707
708					In some cases, there is the need for incremental parsing of JSON
709					texts. While this module always has to keep both JSON text and resulting
710					Perl data structure in memory at one time, it does allow you to parse a
711					JSON stream incrementally. It does so by accumulating text until it has
712					a full JSON object, which it then can decode. This process is similar to
713					using C<decode_prefix> to see if a full JSON object is available, but
714					is much more efficient (and can be implemented with a minimum of method
715					calls).
716
717					JSON::XS will only attempt to parse the JSON text once it is sure it
718					has enough text to get a decisive result, using a very simple but
719					truly incremental parser. This means that it sometimes won't stop as
720					early as the full parser, for example, it doesn't detect mismatched
721					parentheses. The only thing it guarantees is that it starts decoding as
722					soon as a syntactically valid JSON text has been seen. This means you need
723					to set resource limits (e.g. C<max_size>) to ensure the parser will stop
724					parsing in the presence if syntax errors.
725
726					The following methods implement this incremental parser.
727
728					=over 4
729
730					=item [void, scalar or list context] = $json->incr_parse ([$string])
731
732					This is the central parsing function. It can both append new text and
733					extract objects from the stream accumulated so far (both of these
734					functions are optional).
735
736					If C<$string> is given, then this string is appended to the already
737					existing JSON fragment stored in the C<$json> object.
738
739					After that, if the function is called in void context, it will simply
740					return without doing anything further. This can be used to add more text
741					in as many chunks as you want.
742
743					If the method is called in scalar context, then it will try to extract
744					exactly I<one> JSON object. If that is successful, it will return this
745					object, otherwise it will return C<undef>. If there is a parse error,
746					this method will croak just as C<decode> would do (one can then use
747					C<incr_skip> to skip the errornous part). This is the most common way of
748					using the method.
749
750					And finally, in list context, it will try to extract as many objects
751					from the stream as it can find and return them, or the empty list
752					otherwise. For this to work, there must be no separators between the JSON
753					objects or arrays, instead they must be concatenated back-to-back. If
754					an error occurs, an exception will be raised as in the scalar context
755					case. Note that in this case, any previously-parsed JSON texts will be
756					lost.
757
758					Example: Parse some JSON arrays/objects in a given string and return
759					them.
760
761					my @objs = JSON::XS->new->incr_parse ("[5][7][1,2]");
762
763					=item $lvalue_string = $json->incr_text
764
765					This method returns the currently stored JSON fragment as an lvalue, that
766					is, you can manipulate it. This I<only> works when a preceding call to
767					C<incr_parse> in I<scalar context> successfully returned an object. Under
768					all other circumstances you must not call this function (I mean it.
769					although in simple tests it might actually work, it I<will> fail under
770					real world conditions). As a special exception, you can also call this
771					method before having parsed anything.
772
773					This function is useful in two cases: a) finding the trailing text after a
774					JSON object or b) parsing multiple JSON objects separated by non-JSON text
775					(such as commas).
776
777					=item $json->incr_skip
778
779					This will reset the state of the incremental parser and will remove
780					the parsed text from the input buffer so far. This is useful after
781					C<incr_parse> died, in which case the input buffer and incremental parser
782					state is left unchanged, to skip the text parsed so far and to reset the
783					parse state.
784
785					The difference to C<incr_reset> is that only text until the parse error
786					occured is removed.
787
788					=item $json->incr_reset
789
790					This completely resets the incremental parser, that is, after this call,
791					it will be as if the parser had never parsed anything.
792
793					This is useful if you want to repeatedly parse JSON objects and want to
794					ignore any trailing data, which means you have to reset the parser after
795					each successful decode.
796
797					=back
798
799					=head2 LIMITATIONS
800
801					All options that affect decoding are supported, except
802					C<allow_nonref>. The reason for this is that it cannot be made to
803					work sensibly: JSON objects and arrays are self-delimited, i.e. you can concatenate
804					them back to back and still decode them perfectly. This does not hold true
805					for JSON numbers, however.
806
807					For example, is the string C<1> a single JSON number, or is it simply the
808					start of C<12>? Or is C<12> a single JSON number, or the concatenation
809					of C<1> and C<2>? In neither case you can tell, and this is why JSON::XS
810					takes the conservative route and disallows this case.
811
812					=head2 EXAMPLES
813
814					Some examples will make all this clearer. First, a simple example that
815					works similarly to C<decode_prefix>: We want to decode the JSON object at
816					the start of a string and identify the portion after the JSON object:
817
818					my $text = "[1,2,3] hello";
819
820					my $json = new JSON::XS;
821
822					my $obj = $json->incr_parse ($text)
823					or die "expected JSON object or array at beginning of string";
824
825					my $tail = $json->incr_text;
826					# $tail now contains " hello"
827
828					Easy, isn't it?
829
830					Now for a more complicated example: Imagine a hypothetical protocol where
831					you read some requests from a TCP stream, and each request is a JSON
832					array, without any separation between them (in fact, it is often useful to
833					use newlines as "separators", as these get interpreted as whitespace at
834					the start of the JSON text, which makes it possible to test said protocol
835					with C<telnet>...).
836
837					Here is how you'd do it (it is trivial to write this in an event-based
838					manner):
839
840					my $json = new JSON::XS;
841
842					# read some data from the socket
843					while (sysread $socket, my $buf, 4096) {
844
845					# split and decode as many requests as possible
846					for my $request ($json->incr_parse ($buf)) {
847					# act on the $request
848					}
849					}
850
851					Another complicated example: Assume you have a string with JSON objects
852					or arrays, all separated by (optional) comma characters (e.g. C<[1],[2],
853					[3]>). To parse them, we have to skip the commas between the JSON texts,
854					and here is where the lvalue-ness of C<incr_text> comes in useful:
855
856					my $text = "[1],[2], [3]";
857					my $json = new JSON::XS;
858
859					# void context, so no parsing done
860					$json->incr_parse ($text);
861
862					# now extract as many objects as possible. note the
863					# use of scalar context so incr_text can be called.
864					while (my $obj = $json->incr_parse) {
865					# do something with $obj
866
867					# now skip the optional comma
868					$json->incr_text =~ s/^ \s* , //x;
869					}
870
871					Now lets go for a very complex example: Assume that you have a gigantic
872					JSON array-of-objects, many gigabytes in size, and you want to parse it,
873					but you cannot load it into memory fully (this has actually happened in
874					the real world :).
875
876					Well, you lost, you have to implement your own JSON parser. But JSON::XS
877					can still help you: You implement a (very simple) array parser and let
878					JSON decode the array elements, which are all full JSON objects on their
879					own (this wouldn't work if the array elements could be JSON numbers, for
880					example):
881
882					my $json = new JSON::XS;
883
884					# open the monster
885					open my $fh, "<bigfile.json"
886					or die "bigfile: $!";
887
888					# first parse the initial "["
889					for (;;) {
890					sysread $fh, my $buf, 65536
891					or die "read error: $!";
892					$json->incr_parse ($buf); # void context, so no parsing
893
894					# Exit the loop once we found and removed(!) the initial "[".
895					# In essence, we are (ab-)using the $json object as a simple scalar
896					# we append data to.
897					last if $json->incr_text =~ s/^ \s* \[ //x;
898					}
899
900					# now we have the skipped the initial "[", so continue
901					# parsing all the elements.
902					for (;;) {
903					# in this loop we read data until we got a single JSON object
904					for (;;) {
905					if (my $obj = $json->incr_parse) {
906					# do something with $obj
907					last;
908					}
909
910					# add more data
911					sysread $fh, my $buf, 65536
912					or die "read error: $!";
913					$json->incr_parse ($buf); # void context, so no parsing
914					}
915
916					# in this loop we read data until we either found and parsed the
917					# separating "," between elements, or the final "]"
918					for (;;) {
919					# first skip whitespace
920					$json->incr_text =~ s/^\s*//;
921
922					# if we find "]", we are done
923					if ($json->incr_text =~ s/^\]//) {
924					print "finished.\n";
925					exit;
926					}
927
928					# if we find ",", we can continue with the next element
929					if ($json->incr_text =~ s/^,//) {
930					last;
931					}
932
933					# if we find anything else, we have a parse error!
934					if (length $json->incr_text) {
935					die "parse error near ", $json->incr_text;
936					}
937
938					# else add more data
939					sysread $fh, my $buf, 65536
940					or die "read error: $!";
941					$json->incr_parse ($buf); # void context, so no parsing
942					}
943
944					This is a complex example, but most of the complexity comes from the fact
945					that we are trying to be correct (bear with me if I am wrong, I never ran
946					the above example :).
947
- -
950					=head1 MAPPING
951
952					This section describes how JSON::XS maps Perl values to JSON values and
953					vice versa. These mappings are designed to "do the right thing" in most
954					circumstances automatically, preserving round-tripping characteristics
955					(what you put in comes out as something equivalent).
956
957					For the more enlightened: note that in the following descriptions,
958					lowercase I<perl> refers to the Perl interpreter, while uppercase I<Perl>
959					refers to the abstract Perl language itself.
960
961
962					=head2 JSON -> PERL
963
964					=over 4
965
966					=item object
967
968					A JSON object becomes a reference to a hash in Perl. No ordering of object
969					keys is preserved (JSON does not preserve object key ordering itself).
970
971					=item array
972
973					A JSON array becomes a reference to an array in Perl.
974
975					=item string
976
977					A JSON string becomes a string scalar in Perl - Unicode codepoints in JSON
978					are represented by the same codepoints in the Perl string, so no manual
979					decoding is necessary.
980
981					=item number
982
983					A JSON number becomes either an integer, numeric (floating point) or
984					string scalar in perl, depending on its range and any fractional parts. On
985					the Perl level, there is no difference between those as Perl handles all
986					the conversion details, but an integer may take slightly less memory and
987					might represent more values exactly than floating point numbers.
988
989					If the number consists of digits only, JSON::XS will try to represent
990					it as an integer value. If that fails, it will try to represent it as
991					a numeric (floating point) value if that is possible without loss of
992					precision. Otherwise it will preserve the number as a string value (in
993					which case you lose roundtripping ability, as the JSON number will be
994					re-encoded toa JSON string).
995
996					Numbers containing a fractional or exponential part will always be
997					represented as numeric (floating point) values, possibly at a loss of
998					precision (in which case you might lose perfect roundtripping ability, but
999					the JSON number will still be re-encoded as a JSON number).
1000
1001					Note that precision is not accuracy - binary floating point values cannot
1002					represent most decimal fractions exactly, and when converting from and to
1003					floating point, JSON::XS only guarantees precision up to but not including
1004					the leats significant bit.
1005
1006					=item true, false
1007
1008					These JSON atoms become C<JSON::XS::true> and C<JSON::XS::false>,
1009					respectively. They are overloaded to act almost exactly like the numbers
1010					C<1> and C<0>. You can check whether a scalar is a JSON boolean by using
1011					the C<JSON::XS::is_bool> function.
1012
1013					=item null
1014
1015					A JSON null atom becomes C<undef> in Perl.
1016
1017					=back
1018
1019
1020					=head2 PERL -> JSON
1021
1022					The mapping from Perl to JSON is slightly more difficult, as Perl is a
1023					truly typeless language, so we can only guess which JSON type is meant by
1024					a Perl value.
1025
1026					=over 4
1027
1028					=item hash references
1029
1030					Perl hash references become JSON objects. As there is no inherent ordering
1031					in hash keys (or JSON objects), they will usually be encoded in a
1032					pseudo-random order that can change between runs of the same program but
1033					stays generally the same within a single run of a program. JSON::XS can
1034					optionally sort the hash keys (determined by the I<canonical> flag), so
1035					the same datastructure will serialise to the same JSON text (given same
1036					settings and version of JSON::XS), but this incurs a runtime overhead
1037					and is only rarely useful, e.g. when you want to compare some JSON text
1038					against another for equality.
1039
1040					=item array references
1041
1042					Perl array references become JSON arrays.
1043
1044					=item other references
1045
1046					Other unblessed references are generally not allowed and will cause an
1047					exception to be thrown, except for references to the integers C<0> and
1048					C<1>, which get turned into C<false> and C<true> atoms in JSON. You can
1049					also use C<JSON::XS::false> and C<JSON::XS::true> to improve readability.
1050
1051					encode_json [\0, JSON::XS::true] # yields [false,true]
1052
1053					=item JSON::XS::true, JSON::XS::false
1054
1055					These special values become JSON true and JSON false values,
1056					respectively. You can also use C<\1> and C<\0> directly if you want.
1057
1058					=item blessed objects
1059
1060					Blessed objects are not directly representable in JSON. See the
1061					C<allow_blessed> and C<convert_blessed> methods on various options on
1062					how to deal with this: basically, you can choose between throwing an
1063					exception, encoding the reference as if it weren't blessed, or provide
1064					your own serialiser method.
1065
1066					=item simple scalars
1067
1068					Simple Perl scalars (any scalar that is not a reference) are the most
1069					difficult objects to encode: JSON::XS will encode undefined scalars as
1070					JSON C<null> values, scalars that have last been used in a string context
1071					before encoding as JSON strings, and anything else as number value:
1072
1073					# dump as number
1074					encode_json [2] # yields [2]
1075					encode_json [-3.0e17] # yields [-3e+17]
1076					my $value = 5; encode_json [$value] # yields [5]
1077
1078					# used as string, so dump as string
1079					print $value;
1080					encode_json [$value] # yields ["5"]
1081
1082					# undef becomes null
1083					encode_json [undef] # yields [null]
1084
1085					You can force the type to be a JSON string by stringifying it:
1086
1087					my $x = 3.1; # some variable containing a number
1088					"$x"; # stringified
1089					$x .= ""; # another, more awkward way to stringify
1090					print $x; # perl does it for you, too, quite often
1091
1092					You can force the type to be a JSON number by numifying it:
1093
1094					my $x = "3"; # some variable containing a string
1095					$x += 0; # numify it, ensuring it will be dumped as a number
1096					$x *= 1; # same thing, the choice is yours.
1097
1098					You can not currently force the type in other, less obscure, ways. Tell me
1099					if you need this capability (but don't forget to explain why it's needed
1100					:).
1101
1102					Note that numerical precision has the same meaning as under Perl (so
1103					binary to decimal conversion follows the same rules as in Perl, which
1104					can differ to other languages). Also, your perl interpreter might expose
1105					extensions to the floating point numbers of your platform, such as
1106					infinities or NaN's - these cannot be represented in JSON, and it is an
1107					error to pass those in.
1108
1109					=back
1110
1111
1112					=head1 ENCODING/CODESET FLAG NOTES
1113
1114					The interested reader might have seen a number of flags that signify
1115					encodings or codesets - C<utf8>, C<latin1> and C<ascii>. There seems to be
1116					some confusion on what these do, so here is a short comparison:
1117
1118					C<utf8> controls whether the JSON text created by C<encode> (and expected
1119					by C<decode>) is UTF-8 encoded or not, while C<latin1> and C<ascii> only
1120					control whether C<encode> escapes character values outside their respective
1121					codeset range. Neither of these flags conflict with each other, although
1122					some combinations make less sense than others.
1123
1124					Care has been taken to make all flags symmetrical with respect to
1125					C<encode> and C<decode>, that is, texts encoded with any combination of
1126					these flag values will be correctly decoded when the same flags are used
1127					- in general, if you use different flag settings while encoding vs. when
1128					decoding you likely have a bug somewhere.
1129
1130					Below comes a verbose discussion of these flags. Note that a "codeset" is
1131					simply an abstract set of character-codepoint pairs, while an encoding
1132					takes those codepoint numbers and I<encodes> them, in our case into
1133					octets. Unicode is (among other things) a codeset, UTF-8 is an encoding,
1134					and ISO-8859-1 (= latin 1) and ASCII are both codesets I<and> encodings at
1135					the same time, which can be confusing.
1136
1137					=over 4
1138
1139					=item C<utf8> flag disabled
1140
1141					When C<utf8> is disabled (the default), then C<encode>/C<decode> generate
1142					and expect Unicode strings, that is, characters with high ordinal Unicode
1143					values (> 255) will be encoded as such characters, and likewise such
1144					characters are decoded as-is, no canges to them will be done, except
1145					"(re-)interpreting" them as Unicode codepoints or Unicode characters,
1146					respectively (to Perl, these are the same thing in strings unless you do
1147					funny/weird/dumb stuff).
1148
1149					This is useful when you want to do the encoding yourself (e.g. when you
1150					want to have UTF-16 encoded JSON texts) or when some other layer does
1151					the encoding for you (for example, when printing to a terminal using a
1152					filehandle that transparently encodes to UTF-8 you certainly do NOT want
1153					to UTF-8 encode your data first and have Perl encode it another time).
1154
1155					=item C<utf8> flag enabled
1156
1157					If the C<utf8>-flag is enabled, C<encode>/C<decode> will encode all
1158					characters using the corresponding UTF-8 multi-byte sequence, and will
1159					expect your input strings to be encoded as UTF-8, that is, no "character"
1160					of the input string must have any value > 255, as UTF-8 does not allow
1161					that.
1162
1163					The C<utf8> flag therefore switches between two modes: disabled means you
1164					will get a Unicode string in Perl, enabled means you get an UTF-8 encoded
1165					octet/binary string in Perl.
1166
1167					=item C<latin1> or C<ascii> flags enabled
1168
1169					With C<latin1> (or C<ascii>) enabled, C<encode> will escape characters
1170					with ordinal values > 255 (> 127 with C<ascii>) and encode the remaining
1171					characters as specified by the C<utf8> flag.
1172
1173					If C<utf8> is disabled, then the result is also correctly encoded in those
1174					character sets (as both are proper subsets of Unicode, meaning that a
1175					Unicode string with all character values < 256 is the same thing as a
1176					ISO-8859-1 string, and a Unicode string with all character values < 128 is
1177					the same thing as an ASCII string in Perl).
1178
1179					If C<utf8> is enabled, you still get a correct UTF-8-encoded string,
1180					regardless of these flags, just some more characters will be escaped using
1181					C<\uXXXX> then before.
1182
1183					Note that ISO-8859-1-I<encoded> strings are not compatible with UTF-8
1184					encoding, while ASCII-encoded strings are. That is because the ISO-8859-1
1185					encoding is NOT a subset of UTF-8 (despite the ISO-8859-1 I<codeset> being
1186					a subset of Unicode), while ASCII is.
1187
1188					Surprisingly, C<decode> will ignore these flags and so treat all input
1189					values as governed by the C<utf8> flag. If it is disabled, this allows you
1190					to decode ISO-8859-1- and ASCII-encoded strings, as both strict subsets of
1191					Unicode. If it is enabled, you can correctly decode UTF-8 encoded strings.
1192
1193					So neither C<latin1> nor C<ascii> are incompatible with the C<utf8> flag -
1194					they only govern when the JSON output engine escapes a character or not.
1195
1196					The main use for C<latin1> is to relatively efficiently store binary data
1197					as JSON, at the expense of breaking compatibility with most JSON decoders.
1198
1199					The main use for C<ascii> is to force the output to not contain characters
1200					with values > 127, which means you can interpret the resulting string
1201					as UTF-8, ISO-8859-1, ASCII, KOI8-R or most about any character set and
1202					8-bit-encoding, and still get the same data structure back. This is useful
1203					when your channel for JSON transfer is not 8-bit clean or the encoding
1204					might be mangled in between (e.g. in mail), and works because ASCII is a
1205					proper subset of most 8-bit and multibyte encodings in use in the world.
1206
1207					=back
1208
1209
1210					=head2 JSON and ECMAscript
1211
1212					JSON syntax is based on how literals are represented in javascript (the
1213					not-standardised predecessor of ECMAscript) which is presumably why it is
1214					called "JavaScript Object Notation".
1215
1216					However, JSON is not a subset (and also not a superset of course) of
1217					ECMAscript (the standard) or javascript (whatever browsers actually
1218					implement).
1219
1220					If you want to use javascript's C<eval> function to "parse" JSON, you
1221					might run into parse errors for valid JSON texts, or the resulting data
1222					structure might not be queryable:
1223
1224					One of the problems is that U+2028 and U+2029 are valid characters inside
1225					JSON strings, but are not allowed in ECMAscript string literals, so the
1226					following Perl fragment will not output something that can be guaranteed
1227					to be parsable by javascript's C<eval>:
1228
1229					use JSON::XS;
1230
1231					print encode_json [chr 0x2028];
1232
1233					The right fix for this is to use a proper JSON parser in your javascript
1234					programs, and not rely on C<eval> (see for example Douglas Crockford's
1235					F<json2.js> parser).
1236
1237					If this is not an option, you can, as a stop-gap measure, simply encode to
1238					ASCII-only JSON:
1239
1240					use JSON::XS;
1241
1242					print JSON::XS->new->ascii->encode ([chr 0x2028]);
1243
1244					Note that this will enlarge the resulting JSON text quite a bit if you
1245					have many non-ASCII characters. You might be tempted to run some regexes
1246					to only escape U+2028 and U+2029, e.g.:
1247
1248					# DO NOT USE THIS!
1249					my $json = JSON::XS->new->utf8->encode ([chr 0x2028]);
1250					$json =~ s/\xe2\x80\xa8/\\u2028/g; # escape U+2028
1251					$json =~ s/\xe2\x80\xa9/\\u2029/g; # escape U+2029
1252					print $json;
1253
1254					Note that I<this is a bad idea>: the above only works for U+2028 and
1255					U+2029 and thus only for fully ECMAscript-compliant parsers. Many existing
1256					javascript implementations, however, have issues with other characters as
1257					well - using C<eval> naively simply I<will> cause problems.
1258
1259					Another problem is that some javascript implementations reserve
1260					some property names for their own purposes (which probably makes
1261					them non-ECMAscript-compliant). For example, Iceweasel reserves the
1262					C<__proto__> property name for its own purposes.
1263
1264					If that is a problem, you could parse try to filter the resulting JSON
1265					output for these property strings, e.g.:
1266
1267					$json =~ s/"__proto__"\s*:/"__proto__renamed":/g;
1268
1269					This works because C<__proto__> is not valid outside of strings, so every
1270					occurence of C<"__proto__"\s*:> must be a string used as property name.
1271
1272					If you know of other incompatibilities, please let me know.
1273
1274
1275					=head2 JSON and YAML
1276
1277					You often hear that JSON is a subset of YAML. This is, however, a mass
1278					hysteria(*) and very far from the truth (as of the time of this writing),
1279					so let me state it clearly: I<in general, there is no way to configure
1280					JSON::XS to output a data structure as valid YAML> that works in all
1281					cases.
1282
1283					If you really must use JSON::XS to generate YAML, you should use this
1284					algorithm (subject to change in future versions):
1285
1286					my $to_yaml = JSON::XS->new->utf8->space_after (1);
1287					my $yaml = $to_yaml->encode ($ref) . "\n";
1288
1289					This will I<usually> generate JSON texts that also parse as valid
1290					YAML. Please note that YAML has hardcoded limits on (simple) object key
1291					lengths that JSON doesn't have and also has different and incompatible
1292					unicode character escape syntax, so you should make sure that your hash
1293					keys are noticeably shorter than the 1024 "stream characters" YAML allows
1294					and that you do not have characters with codepoint values outside the
1295					Unicode BMP (basic multilingual page). YAML also does not allow C<\/>
1296					sequences in strings (which JSON::XS does not I<currently> generate, but
1297					other JSON generators might).
1298
1299					There might be other incompatibilities that I am not aware of (or the YAML
1300					specification has been changed yet again - it does so quite often). In
1301					general you should not try to generate YAML with a JSON generator or vice
1302					versa, or try to parse JSON with a YAML parser or vice versa: chances are
1303					high that you will run into severe interoperability problems when you
1304					least expect it.
1305
1306					=over 4
1307
1308					=item (*)
1309
1310					I have been pressured multiple times by Brian Ingerson (one of the
1311					authors of the YAML specification) to remove this paragraph, despite him
1312					acknowledging that the actual incompatibilities exist. As I was personally
1313					bitten by this "JSON is YAML" lie, I refused and said I will continue to
1314					educate people about these issues, so others do not run into the same
1315					problem again and again. After this, Brian called me a (quote)I<complete
1316					and worthless idiot>(unquote).
1317
1318					In my opinion, instead of pressuring and insulting people who actually
1319					clarify issues with YAML and the wrong statements of some of its
1320					proponents, I would kindly suggest reading the JSON spec (which is not
1321					that difficult or long) and finally make YAML compatible to it, and
1322					educating users about the changes, instead of spreading lies about the
1323					real compatibility for many I<years> and trying to silence people who
1324					point out that it isn't true.
1325
1326					Addendum/2009: the YAML 1.2 spec is still incompatible with JSON, even
1327					though the incompatibilities have been documented (and are known to Brian)
1328					for many years and the spec makes explicit claims that YAML is a superset
1329					of JSON. It would be so easy to fix, but apparently, bullying people and
1330					corrupting userdata is so much easier.
1331
1332					=back
1333
1334
1335					=head2 SPEED
1336
1337					It seems that JSON::XS is surprisingly fast, as shown in the following
1338					tables. They have been generated with the help of the C<eg/bench> program
1339					in the JSON::XS distribution, to make it easy to compare on your own
1340					system.
1341
1342					First comes a comparison between various modules using
1343					a very short single-line JSON string (also available at
1344					L<http://dist.schmorp.de/misc/json/short.json>).
1345
1346					{"method": "handleMessage", "params": ["user1",
1347					"we were just talking"], "id": null, "array":[1,11,234,-5,1e5,1e7,
1348					1, 0]}
1349
1350					It shows the number of encodes/decodes per second (JSON::XS uses
1351					the functional interface, while JSON::XS/2 uses the OO interface
1352					with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables
1353					shrink. JSON::DWIW/DS uses the deserialise function, while JSON::DWIW::FJ
1354					uses the from_json method). Higher is better:
1355
1356					module | encode | decode |
1357					--------------|------------|------------|
1358					JSON::DWIW/DS | 86302.551 | 102300.098 |
1359					JSON::DWIW/FJ | 86302.551 | 75983.768 |
1360					JSON::PP | 15827.562 | 6638.658 |
1361					JSON::Syck | 63358.066 | 47662.545 |
1362					JSON::XS | 511500.488 | 511500.488 |
1363					JSON::XS/2 | 291271.111 | 388361.481 |
1364					JSON::XS/3 | 361577.931 | 361577.931 |
1365					Storable | 66788.280 | 265462.278 |
1366					--------------+------------+------------+
1367
1368					That is, JSON::XS is almost six times faster than JSON::DWIW on encoding,
1369					about five times faster on decoding, and over thirty to seventy times
1370					faster than JSON's pure perl implementation. It also compares favourably
1371					to Storable for small amounts of data.
1372
1373					Using a longer test string (roughly 18KB, generated from Yahoo! Locals
1374					search API (L<http://dist.schmorp.de/misc/json/long.json>).
1375
1376					module | encode | decode |
1377					--------------|------------|------------|
1378					JSON::DWIW/DS | 1647.927 | 2673.916 |
1379					JSON::DWIW/FJ | 1630.249 | 2596.128 |
1380					JSON::PP | 400.640 | 62.311 |
1381					JSON::Syck | 1481.040 | 1524.869 |
1382					JSON::XS | 20661.596 | 9541.183 |
1383					JSON::XS/2 | 10683.403 | 9416.938 |
1384					JSON::XS/3 | 20661.596 | 9400.054 |
1385					Storable | 19765.806 | 10000.725 |
1386					--------------+------------+------------+
1387
1388					Again, JSON::XS leads by far (except for Storable which non-surprisingly
1389					decodes a bit faster).
1390
1391					On large strings containing lots of high Unicode characters, some modules
1392					(such as JSON::PC) seem to decode faster than JSON::XS, but the result
1393					will be broken due to missing (or wrong) Unicode handling. Others refuse
1394					to decode or encode properly, so it was impossible to prepare a fair
1395					comparison table for that case.
1396
1397
1398					=head1 SECURITY CONSIDERATIONS
1399
1400					When you are using JSON in a protocol, talking to untrusted potentially
1401					hostile creatures requires relatively few measures.
1402
1403					First of all, your JSON decoder should be secure, that is, should not have
1404					any buffer overflows. Obviously, this module should ensure that and I am
1405					trying hard on making that true, but you never know.
1406
1407					Second, you need to avoid resource-starving attacks. That means you should
1408					limit the size of JSON texts you accept, or make sure then when your
1409					resources run out, that's just fine (e.g. by using a separate process that
1410					can crash safely). The size of a JSON text in octets or characters is
1411					usually a good indication of the size of the resources required to decode
1412					it into a Perl structure. While JSON::XS can check the size of the JSON
1413					text, it might be too late when you already have it in memory, so you
1414					might want to check the size before you accept the string.
1415
1416					Third, JSON::XS recurses using the C stack when decoding objects and
1417					arrays. The C stack is a limited resource: for instance, on my amd64
1418					machine with 8MB of stack size I can decode around 180k nested arrays but
1419					only 14k nested JSON objects (due to perl itself recursing deeply on croak
1420					to free the temporary). If that is exceeded, the program crashes. To be
1421					conservative, the default nesting limit is set to 512. If your process
1422					has a smaller stack, you should adjust this setting accordingly with the
1423					C<max_depth> method.
1424
1425					Something else could bomb you, too, that I forgot to think of. In that
1426					case, you get to keep the pieces. I am always open for hints, though...
1427
1428					Also keep in mind that JSON::XS might leak contents of your Perl data
1429					structures in its error messages, so when you serialise sensitive
1430					information you might want to make sure that exceptions thrown by JSON::XS
1431					will not end up in front of untrusted eyes.
1432
1433					If you are using JSON::XS to return packets to consumption
1434					by JavaScript scripts in a browser you should have a look at
1435					L<http://blog.archive.jpsykes.com/47/practical-csrf-and-json-security/> to
1436					see whether you are vulnerable to some common attack vectors (which really
1437					are browser design bugs, but it is still you who will have to deal with
1438					it, as major browser developers care only for features, not about getting
1439					security right).
1440
1441
1442					=head1 THREADS
1443
1444					This module is I<not> guaranteed to be thread safe and there are no
1445					plans to change this until Perl gets thread support (as opposed to the
1446					horribly slow so-called "threads" which are simply slow and bloated
1447					process simulations - use fork, it's I<much> faster, cheaper, better).
1448
1449					(It might actually work, but you have been warned).
1450
1451
1452					=head1 THE PERILS OF SETLOCALE
1453
1454					Sometimes people avoid the Perl locale support and directly call the
1455					system's setlocale function with C<LC_ALL>.
1456
1457					This breaks both perl and modules such as JSON::XS, as stringification of
1458					numbers no longer works correcly (e.g. C<$x = 0.1; print "$x"+1> might
1459					print C<1>, and JSON::XS might output illegal JSON as JSON::XS relies on
1460					perl to stringify numbers).
1461
1462					The solution is simple: don't call C<setlocale>, or use it for only those
1463					categories you need, such as C<LC_MESSAGES> or C<LC_CTYPE>.
1464
1465					If you need C<LC_NUMERIC>, you should enable it only around the code that
1466					actually needs it (avoiding stringification of numbers), and restore it
1467					afterwards.
1468
1469
1470					=head1 BUGS
1471
1472					While the goal of this module is to be correct, that unfortunately does
1473					not mean it's bug-free, only that I think its design is bug-free. If you
1474					keep reporting bugs they will be fixed swiftly, though.
1475
1476					Please refrain from using rt.cpan.org or any other bug reporting
1477					service. I put the contact address into my modules for a reason.
1478
1479					=cut
1480
1481	1	2µs			our $true = do { bless \(my $dummy = 1), "JSON::XS::Boolean" };
1482	1	500ns			our $false = do { bless \(my $dummy = 0), "JSON::XS::Boolean" };
1483
1484					sub true() { $true }
1485					sub false() { $false }
1486
1487					sub is_bool($) {
1488					UNIVERSAL::isa $_[0], "JSON::XS::Boolean"
1489					# or UNIVERSAL::isa $_[0], "JSON::Literal"
1490					}
1491
1492	1	406µs	1	1.64ms	XSLoader::load "JSON::XS", $VERSION; # spent 1.64ms making 1 call to XSLoader::load
1493
1494					package JSON::XS::Boolean;
1495
1496					use overload
1497					# spent 60µs (17+43) within JSON::XS::Boolean::BEGIN@1497 which was called: # once (17µs+43µs) by JSON::BEGIN@2 at line 1500 "0+" => sub { ${$_[0]} },
1498					"++" => sub { $_[0] = ${$_[0]} + 1 },
1499					"--" => sub { $_[0] = ${$_[0]} - 1 },
1500	2	89µs	2	102µs	fallback => 1; # spent 60µs making 1 call to JSON::XS::Boolean::BEGIN@1497 # spent 43µs making 1 call to overload::import
1501
1502	1	7µs			1;
1503
1504					=head1 SEE ALSO
1505
1506					The F<json_xs> command line utility for quick experiments.
1507
1508					=head1 AUTHOR
1509
1510					Marc Lehmann <schmorp@schmorp.de>
1511					http://home.schmorp.de/
1512
1513					=cut
1514