ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/cvsroot/JSON-XS/XS.pm
Revision: 1.184
Committed: Wed Nov 18 07:37:09 2026 UTC (2 days, 5 hours ago) by root
Branch: MAIN
CVS Tags: rel-4_06, HEAD
Changes since 1.183: +1 -1 lines
Log Message:
4.06

File Contents

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