1XS(3)                 User Contributed Perl Documentation                XS(3)
2
3
4

NAME

6       Cpanel::JSON::XS - cPanel fork of JSON::XS, fast and correct
7       serializing
8

SYNOPSIS

10        use Cpanel::JSON::XS;
11
12        # exported functions, they croak on error
13        # and expect/generate UTF-8
14
15        $utf8_encoded_json_text = encode_json $perl_hash_or_arrayref;
16        $perl_hash_or_arrayref  = decode_json $utf8_encoded_json_text;
17
18        # OO-interface
19
20        $coder = Cpanel::JSON::XS->new->ascii->pretty->allow_nonref;
21        $pretty_printed_unencoded = $coder->encode ($perl_scalar);
22        $perl_scalar = $coder->decode ($unicode_json_text);
23
24        # Note that 5.6 misses most smart utf8 and encoding functionalities
25        # of newer releases.
26
27        # Note that L<JSON::MaybeXS> will automatically use Cpanel::JSON::XS
28        # if available, at virtually no speed overhead either, so you should
29        # be able to just:
30
31        use JSON::MaybeXS;
32
33        # and do the same things, except that you have a pure-perl fallback now.
34
35        Note that this module will be replaced by a new JSON::Safe module soon,
36        with the same API just guaranteed safe defaults.
37

DESCRIPTION

39       This module converts Perl data structures to JSON and vice versa. Its
40       primary goal is to be correct and its secondary goal is to be fast. To
41       reach the latter goal it was written in C.
42
43       As this is the n-th-something JSON module on CPAN, what was the reason
44       to write yet another JSON module? While it seems there are many JSON
45       modules, none of them correctly handle all corner cases, and in most
46       cases their maintainers are unresponsive, gone missing, or not
47       listening to bug reports for other reasons.
48
49       See below for the cPanel fork.
50
51       See MAPPING, below, on how Cpanel::JSON::XS maps perl values to JSON
52       values and vice versa.
53
54   FEATURES
55       ·   correct Unicode handling
56
57           This module knows how to handle Unicode with Perl version higher
58           than 5.8.5, documents how and when it does so, and even documents
59           what "correct" means.
60
61       ·   round-trip integrity
62
63           When you serialize a perl data structure using only data types
64           supported by JSON and Perl, the deserialized data structure is
65           identical on the Perl level. (e.g. the string "2.0" doesn't
66           suddenly become "2" just because it looks like a number). There are
67           minor exceptions to this, read the MAPPING section below to learn
68           about those.
69
70       ·   strict checking of JSON correctness
71
72           There is no guessing, no generating of illegal JSON texts by
73           default, and only JSON is accepted as input by default. the latter
74           is a security feature.
75
76       ·   fast
77
78           Compared to other JSON modules and other serializers such as
79           Storable, this module usually compares favourably in terms of
80           speed, too.
81
82       ·   simple to use
83
84           This module has both a simple functional interface as well as an
85           object oriented interface.
86
87       ·   reasonably versatile output formats
88
89           You can choose between the most compact guaranteed-single-line
90           format possible (nice for simple line-based protocols), a pure-
91           ASCII format (for when your transport is not 8-bit clean, still
92           supports the whole Unicode range), or a pretty-printed format (for
93           when you want to read that stuff). Or you can combine those
94           features in whatever way you like.
95
96   cPanel fork
97       Since the original author MLEHMANN has no public bugtracker, this
98       cPanel fork sits now on github.
99
100       src repo: <https://github.com/rurban/Cpanel-JSON-XS> original:
101       <http://cvs.schmorp.de/JSON-XS/>
102
103       RT:       <https://github.com/rurban/Cpanel-JSON-XS/issues> or
104       <https://rt.cpan.org/Public/Dist/Display.html?Queue=Cpanel-JSON-XS>
105
106       Changes to JSON::XS
107
108       - stricter decode_json() as documented. non-refs are disallowed.
109         added a 2nd optional argument. decode() honors now allow_nonref.
110
111       - fixed encode of numbers for dual-vars. Different string
112         representations are preserved, but numbers with temporary strings
113         which represent the same number are here treated as numbers, not
114         strings. Cpanel::JSON::XS is a bit slower, but preserves numeric
115         types better.
116
117       - numbers ending with .0 stray numbers, are not converted to
118         integers. [#63] dual-vars which are represented as number not
119         integer (42+"bar" != 5.8.9) are now encoded as number (=> 42.0)
120         because internally it's now a NOK type.  However !!1 which is
121         wrongly encoded in 5.8 as "1"/1.0 is still represented as integer.
122
123       - different handling of inf/nan. Default now to null, optionally with
124         stringify_infnan() to "inf"/"nan". [#28, #32]
125
126       - added "binary" extension, non-JSON and non JSON parsable, allows
127         "\xNN" and "\NNN" sequences.
128
129       - 5.6.2 support; sacrificing some utf8 features (assuming bytes
130         all-over), no multi-byte unicode characters with 5.6.
131
132       - interop for true/false overloading. JSON::XS, JSON::PP and Mojo::JSON
133         representations for booleans are accepted and JSON::XS accepts
134         Cpanel::JSON::XS booleans [#13, #37]
135         Fixed overloading of booleans. Cpanel::JSON::XS::true stringifies
136       again
137         to "1", not "true", analog to all other JSON modules.
138
139       - native boolean mapping of yes and no to true and false, as in
140       YAML::XS.
141         In perl "!0" is yes, "!1" is no.
142         The JSON value true maps to 1, false maps to 0. [#39]
143
144       - support arbitrary stringification with encode, with convert_blessed
145         and allow_blessed.
146
147       - ithread support. Cpanel::JSON::XS is thread-safe, JSON::XS not
148
149       - is_bool can be called as method, JSON::XS::is_bool not.
150
151       - performance optimizations for threaded Perls
152
153       - relaxed mode, allowing many popular extensions
154
155       - additional fixes for:
156
157         - [cpan #88061] AIX atof without USE_LONG_DOUBLE
158
159         - #10 unshare_hek crash
160
161         - #7, #29 avoid re-blessing where possible. It fails in JSON::XS for
162          READONLY values, i.e. restricted hashes.
163
164         - #41 overloading of booleans, use the object not the reference.
165
166         - #62 -Dusequadmath conversion and no SEGV.
167
168         - #72 parsing of values followed \0, like 1\0 does fail.
169
170         - #72 parsing of illegal unicode or non-unicode characters.
171
172         - #96 locale-insensitive numeric conversion.
173
174         - #154 numeric conversion fixed since 5.22, using the same strtold as perl5.
175
176         - #167 sort tied hashes with canonical.
177
178       - public maintenance and bugtracker
179
180       - use ppport.h, sanify XS.xs comment styles, harness C coding style
181
182       - common::sense is optional. When available it is not used in the
183         published production module, just during development and testing.
184
185       - extended testsuite, passes all http://seriot.ch/parsing_json.html
186         tests.  In fact it is the only know JSON decoder which does so,
187         while also being the fastest.
188
189       - support many more options and methods from JSON::PP:
190         stringify_infnan, allow_unknown, allow_stringify, allow_barekey,
191         encode_stringify, allow_bignum, allow_singlequote, sort_by
192         (partially), escape_slash, convert_blessed, ...  optional
193         decode_json(, allow_nonref) arg.
194         relaxed implements allow_dupkeys.
195
196       - support all 5 unicode BOM's: UTF-8, UTF-16LE, UTF-16BE, UTF-32LE,
197         UTF-32BE, encoding internally to UTF-8.
198

FUNCTIONAL INTERFACE

200       The following convenience methods are provided by this module. They are
201       exported by default:
202
203       $json_text = encode_json $perl_scalar, [json_type]
204           Converts the given Perl data structure to a UTF-8 encoded, binary
205           string (that is, the string contains octets only). Croaks on error.
206
207           This function call is functionally identical to:
208
209              $json_text = Cpanel::JSON::XS->new->utf8->encode ($perl_scalar, $json_type)
210
211           Except being faster.
212
213           For the type argument see Cpanel::JSON::XS::Type.
214
215       $perl_scalar = decode_json $json_text [, $allow_nonref [, my $json_type
216       ] ]
217           The opposite of "encode_json": expects an UTF-8 (binary) string of
218           an json reference and tries to parse that as an UTF-8 encoded JSON
219           text, returning the resulting reference. Croaks on error.
220
221           This function call is functionally identical to:
222
223              $perl_scalar = Cpanel::JSON::XS->new->utf8->decode ($json_text, $json_type)
224
225           except being faster.
226
227           Note that older decode_json versions in Cpanel::JSON::XS older than
228           3.0116 and JSON::XS did not set allow_nonref but allowed them due
229           to a bug in the decoder.
230
231           If the new 2nd optional $allow_nonref argument is set and not
232           false, the "allow_nonref" option will be set and the function will
233           act is described as in the relaxed RFC 7159 allowing all values
234           such as objects, arrays, strings, numbers, "null", "true", and
235           "false".  See ""OLD" VS. "NEW" JSON (RFC 4627 VS. RFC 7159)" below,
236           why you don't want to do that.
237
238           For the 3rd optional type argument see Cpanel::JSON::XS::Type.
239
240       $is_boolean = Cpanel::JSON::XS::is_bool $scalar
241           Returns true if the passed scalar represents either
242           "JSON::PP::true" or "JSON::PP::false", two constants that act like
243           1 and 0, respectively and are used to represent JSON "true" and
244           "false" values in Perl. (Also recognizes the booleans produced by
245           JSON::XS.)
246
247           See MAPPING, below, for more information on how JSON values are
248           mapped to Perl.
249

DEPRECATED FUNCTIONS

251       from_json
252           from_json has been renamed to decode_json
253
254       to_json
255           to_json has been renamed to encode_json
256

A FEW NOTES ON UNICODE AND PERL

258       Since this often leads to confusion, here are a few very clear words on
259       how Unicode works in Perl, modulo bugs.
260
261       1. Perl strings can store characters with ordinal values > 255.
262           This enables you to store Unicode characters as single characters
263           in a Perl string - very natural.
264
265       2. Perl does not associate an encoding with your strings.
266           ... until you force it to, e.g. when matching it against a regex,
267           or printing the scalar to a file, in which case Perl either
268           interprets your string as locale-encoded text, octets/binary, or as
269           Unicode, depending on various settings. In no case is an encoding
270           stored together with your data, it is use that decides encoding,
271           not any magical meta data.
272
273       3. The internal utf-8 flag has no meaning with regards to the encoding
274       of your string.
275       4. A "Unicode String" is simply a string where each character can be
276       validly interpreted as a Unicode code point.
277           If you have UTF-8 encoded data, it is no longer a Unicode string,
278           but a Unicode string encoded in UTF-8, giving you a binary string.
279
280       5. A string containing "high" (> 255) character values is not a UTF-8
281       string.
282       6. Unicode noncharacters only warn, as in core.
283           The 66 Unicode noncharacters U+FDD0..U+FDEF, and U+*FFFE, U+*FFFF
284           just warn, see <http://www.unicode.org/versions/corrigendum9.html>.
285           But illegal surrogate pairs fail to parse.
286
287       7. Raw non-Unicode characters above U+10FFFF are disallowed.
288           Raw non-Unicode characters outside the valid unicode range fail to
289           parse, because "A string is a sequence of zero or more Unicode
290           characters" RFC 7159 section 1 and "JSON text SHALL be encoded in
291           Unicode RFC 7159 section 8.1. We use now the UTF8_DISALLOW_SUPER
292           flag when parsing unicode.
293
294       I hope this helps :)
295

OBJECT-ORIENTED INTERFACE

297       The object oriented interface lets you configure your own encoding or
298       decoding style, within the limits of supported formats.
299
300       $json = new Cpanel::JSON::XS
301           Creates a new JSON object that can be used to de/encode JSON
302           strings. All boolean flags described below are by default disabled.
303
304           The mutators for flags all return the JSON object again and thus
305           calls can be chained:
306
307              my $json = Cpanel::JSON::XS->new->utf8->space_after->encode ({a => [1,2]})
308              => {"a": [1, 2]}
309
310       $json = $json->ascii ([$enable])
311       $enabled = $json->get_ascii
312           If $enable is true (or missing), then the "encode" method will not
313           generate characters outside the code range 0..127 (which is ASCII).
314           Any Unicode characters outside that range will be escaped using
315           either a single "\uXXXX" (BMP characters) or a double
316           "\uHHHH\uLLLLL" escape sequence, as per RFC4627. The resulting
317           encoded JSON text can be treated as a native Unicode string, an
318           ascii-encoded, latin1-encoded or UTF-8 encoded string, or any other
319           superset of ASCII.
320
321           If $enable is false, then the "encode" method will not escape
322           Unicode characters unless required by the JSON syntax or other
323           flags. This results in a faster and more compact format.
324
325           See also the section ENCODING/CODESET FLAG NOTES later in this
326           document.
327
328           The main use for this flag is to produce JSON texts that can be
329           transmitted over a 7-bit channel, as the encoded JSON texts will
330           not contain any 8 bit characters.
331
332             Cpanel::JSON::XS->new->ascii (1)->encode ([chr 0x10401])
333             => ["\ud801\udc01"]
334
335       $json = $json->latin1 ([$enable])
336       $enabled = $json->get_latin1
337           If $enable is true (or missing), then the "encode" method will
338           encode the resulting JSON text as latin1 (or ISO-8859-1), escaping
339           any characters outside the code range 0..255. The resulting string
340           can be treated as a latin1-encoded JSON text or a native Unicode
341           string. The "decode" method will not be affected in any way by this
342           flag, as "decode" by default expects Unicode, which is a strict
343           superset of latin1.
344
345           If $enable is false, then the "encode" method will not escape
346           Unicode characters unless required by the JSON syntax or other
347           flags.
348
349           See also the section ENCODING/CODESET FLAG NOTES later in this
350           document.
351
352           The main use for this flag is efficiently encoding binary data as
353           JSON text, as most octets will not be escaped, resulting in a
354           smaller encoded size. The disadvantage is that the resulting JSON
355           text is encoded in latin1 (and must correctly be treated as such
356           when storing and transferring), a rare encoding for JSON. It is
357           therefore most useful when you want to store data structures known
358           to contain binary data efficiently in files or databases, not when
359           talking to other JSON encoders/decoders.
360
361             Cpanel::JSON::XS->new->latin1->encode (["\x{89}\x{abc}"]
362             => ["\x{89}\\u0abc"]    # (perl syntax, U+abc escaped, U+89 not)
363
364       $json = $json->binary ([$enable])
365       $enabled = $json = $json->get_binary
366           If the $enable argument is true (or missing), then the "encode"
367           method will not try to detect an UTF-8 encoding in any JSON string,
368           it will strictly interpret it as byte sequence.  The result might
369           contain new "\xNN" sequences, which is unparsable JSON.  The
370           "decode" method forbids "\uNNNN" sequences and accepts "\xNN" and
371           octal "\NNN" sequences.
372
373           There is also a special logic for perl 5.6 and utf8. 5.6 encodes
374           any string to utf-8 automatically when seeing a codepoint >= 0x80
375           and < 0x100. With the binary flag enabled decode the perl utf8
376           encoded string to the original byte encoding and encode this with
377           "\xNN" escapes. This will result to the same encodings as with
378           newer perls. But note that binary multi-byte codepoints with 5.6
379           will result in "illegal unicode character in binary string" errors,
380           unlike with newer perls.
381
382           If $enable is false, then the "encode" method will smartly try to
383           detect Unicode characters unless required by the JSON syntax or
384           other flags and hex and octal sequences are forbidden.
385
386           See also the section ENCODING/CODESET FLAG NOTES later in this
387           document.
388
389           The main use for this flag is to avoid the smart unicode detection
390           and possible double encoding. The disadvantage is that the
391           resulting JSON text is encoded in new "\xNN" and in latin1
392           characters and must correctly be treated as such when storing and
393           transferring, a rare encoding for JSON. It will produce non-
394           readable JSON strings in the browser.  It is therefore most useful
395           when you want to store data structures known to contain binary data
396           efficiently in files or databases, not when talking to other JSON
397           encoders/decoders.  The binary decoding method can also be used
398           when an encoder produced a non-JSON conformant hex or octal
399           encoding "\xNN" or "\NNN".
400
401             Cpanel::JSON::XS->new->binary->encode (["\x{89}\x{abc}"])
402             5.6:   Error: malformed or illegal unicode character in binary string
403             >=5.8: ['\x89\xe0\xaa\xbc']
404
405             Cpanel::JSON::XS->new->binary->encode (["\x{89}\x{bc}"])
406             => ["\x89\xbc"]
407
408             Cpanel::JSON::XS->new->binary->decode (["\x89\ua001"])
409             Error: malformed or illegal unicode character in binary string
410
411             Cpanel::JSON::XS->new->decode (["\x89"])
412             Error: illegal hex character in non-binary string
413
414       $json = $json->utf8 ([$enable])
415       $enabled = $json->get_utf8
416           If $enable is true (or missing), then the "encode" method will
417           encode the JSON result into UTF-8, as required by many protocols,
418           while the "decode" method expects to be handled an UTF-8-encoded
419           string.  Please note that UTF-8-encoded strings do not contain any
420           characters outside the range 0..255, they are thus useful for
421           bytewise/binary I/O. In future versions, enabling this option might
422           enable autodetection of the UTF-16 and UTF-32 encoding families, as
423           described in RFC4627.
424
425           If $enable is false, then the "encode" method will return the JSON
426           string as a (non-encoded) Unicode string, while "decode" expects
427           thus a Unicode string.  Any decoding or encoding (e.g. to UTF-8 or
428           UTF-16) needs to be done yourself, e.g. using the Encode module.
429
430           See also the section ENCODING/CODESET FLAG NOTES later in this
431           document.
432
433           Example, output UTF-16BE-encoded JSON:
434
435             use Encode;
436             $jsontext = encode "UTF-16BE", Cpanel::JSON::XS->new->encode ($object);
437
438           Example, decode UTF-32LE-encoded JSON:
439
440             use Encode;
441             $object = Cpanel::JSON::XS->new->decode (decode "UTF-32LE", $jsontext);
442
443       $json = $json->pretty ([$enable])
444           This enables (or disables) all of the "indent", "space_before" and
445           "space_after" (and in the future possibly more) flags in one call
446           to generate the most readable (or most compact) form possible.
447
448           Example, pretty-print some simple structure:
449
450              my $json = Cpanel::JSON::XS->new->pretty(1)->encode ({a => [1,2]})
451              =>
452              {
453                 "a" : [
454                    1,
455                    2
456                 ]
457              }
458
459       $json = $json->indent ([$enable])
460       $enabled = $json->get_indent
461           If $enable is true (or missing), then the "encode" method will use
462           a multiline format as output, putting every array member or
463           object/hash key-value pair into its own line, indenting them
464           properly.
465
466           If $enable is false, no newlines or indenting will be produced, and
467           the resulting JSON text is guaranteed not to contain any
468           "newlines".
469
470           This setting has no effect when decoding JSON texts.
471
472       $json = $json->indent_length([$number_of_spaces])
473       $length = $json->get_indent_length()
474           Set the indent length (default 3).  This option is only useful when
475           you also enable indent or pretty.  The acceptable range is from 0
476           (no indentation) to 15
477
478       $json = $json->space_before ([$enable])
479       $enabled = $json->get_space_before
480           If $enable is true (or missing), then the "encode" method will add
481           an extra optional space before the ":" separating keys from values
482           in JSON objects.
483
484           If $enable is false, then the "encode" method will not add any
485           extra space at those places.
486
487           This setting has no effect when decoding JSON texts. You will also
488           most likely combine this setting with "space_after".
489
490           Example, space_before enabled, space_after and indent disabled:
491
492              {"key" :"value"}
493
494       $json = $json->space_after ([$enable])
495       $enabled = $json->get_space_after
496           If $enable is true (or missing), then the "encode" method will add
497           an extra optional space after the ":" separating keys from values
498           in JSON objects and extra whitespace after the "," separating key-
499           value pairs and array members.
500
501           If $enable is false, then the "encode" method will not add any
502           extra space at those places.
503
504           This setting has no effect when decoding JSON texts.
505
506           Example, space_before and indent disabled, space_after enabled:
507
508              {"key": "value"}
509
510       $json = $json->relaxed ([$enable])
511       $enabled = $json->get_relaxed
512           If $enable is true (or missing), then "decode" will accept some
513           extensions to normal JSON syntax (see below). "encode" will not be
514           affected in anyway. Be aware that this option makes you accept
515           invalid JSON texts as if they were valid!. I suggest only to use
516           this option to parse application-specific files written by humans
517           (configuration files, resource files etc.)
518
519           If $enable is false (the default), then "decode" will only accept
520           valid JSON texts.
521
522           Currently accepted extensions are:
523
524           ·   list items can have an end-comma
525
526               JSON separates array elements and key-value pairs with commas.
527               This can be annoying if you write JSON texts manually and want
528               to be able to quickly append elements, so this extension
529               accepts comma at the end of such items not just between them:
530
531                  [
532                     1,
533                     2, <- this comma not normally allowed
534                  ]
535                  {
536                     "k1": "v1",
537                     "k2": "v2", <- this comma not normally allowed
538                  }
539
540           ·   shell-style '#'-comments
541
542               Whenever JSON allows whitespace, shell-style comments are
543               additionally allowed. They are terminated by the first
544               carriage-return or line-feed character, after which more white-
545               space and comments are allowed.
546
547                 [
548                    1, # this comment not allowed in JSON
549                       # neither this one...
550                 ]
551
552           ·   literal ASCII TAB characters in strings
553
554               Literal ASCII TAB characters are now allowed in strings (and
555               treated as "\t") in relaxed mode. Despite JSON mandates, that
556               TAB character is substituted for "\t" sequence.
557
558                 [
559                    "Hello\tWorld",
560                    "Hello<TAB>World", # literal <TAB> would not normally be allowed
561                 ]
562
563           ·   allow_singlequote
564
565               Single quotes are accepted instead of double quotes. See the
566               "allow_singlequote" option.
567
568                   { "foo":'bar' }
569                   { 'foo':"bar" }
570                   { 'foo':'bar' }
571
572           ·   allow_barekey
573
574               Accept unquoted object keys instead of with mandatory double
575               quotes. See the "allow_barekey" option.
576
577                   { foo:"bar" }
578
579           ·   allow_dupkeys
580
581               Allow decoding of duplicate keys in hashes. By default
582               duplicate keys are forbidden.  See
583               <http://seriot.ch/parsing_json.php#24>: RFC 7159 section 4:
584               "The names within an object should be unique."  See the
585               "allow_dupkeys" option.
586
587       $json = $json->canonical ([$enable])
588       $enabled = $json->get_canonical
589           If $enable is true (or missing), then the "encode" method will
590           output JSON objects by sorting their keys. This is adding a
591           comparatively high overhead.
592
593           If $enable is false, then the "encode" method will output key-value
594           pairs in the order Perl stores them (which will likely change
595           between runs of the same script, and can change even within the
596           same run from 5.18 onwards).
597
598           This option is useful if you want the same data structure to be
599           encoded as the same JSON text (given the same overall settings). If
600           it is disabled, the same hash might be encoded differently even if
601           contains the same data, as key-value pairs have no inherent
602           ordering in Perl.
603
604           This setting has no effect when decoding JSON texts.
605
606           This is now also done with tied hashes, contrary to JSON::XS.  But
607           note that with most large tied hashes stored as tree it is advised
608           to sort the iterator already and don't sort the hash output here.
609           Most such iterators are already sorted, as such e.g. DB_File with
610           "DB_BTREE".
611
612       $json = $json->sort_by (undef, 0, 1 or a block)
613           This currently only (un)sets the "canonical" option, and ignores
614           custom sort blocks.
615
616           This setting has no effect when decoding JSON texts.
617
618           This setting has currently no effect on tied hashes.
619
620       $json = $json->escape_slash ([$enable])
621       $enabled = $json->get_escape_slash
622           According to the JSON Grammar, the forward slash character (U+002F)
623           "/" need to be escaped.  But by default strings are encoded without
624           escaping slashes in all perl JSON encoders.
625
626           If $enable is true (or missing), then "encode" will escape slashes,
627           "\/".
628
629           This setting has no effect when decoding JSON texts.
630
631       $json = $json->unblessed_bool ([$enable])
632       $enabled = $json->get_unblessed_bool
633               $json = $json->unblessed_bool([$enable])
634
635           If $enable is true (or missing), then "decode" will return Perl
636           non-object boolean variables (1 and 0) for JSON booleans ("true"
637           and "false"). If $enable is false, then "decode" will return
638           "JSON::PP::Boolean" objects for JSON booleans.
639
640       $json = $json->allow_singlequote ([$enable])
641       $enabled = $json->get_allow_singlequote
642               $json = $json->allow_singlequote([$enable])
643
644           If $enable is true (or missing), then "decode" will accept JSON
645           strings quoted by single quotations that are invalid JSON format.
646
647               $json->allow_singlequote->decode({"foo":'bar'});
648               $json->allow_singlequote->decode({'foo':"bar"});
649               $json->allow_singlequote->decode({'foo':'bar'});
650
651           This is also enabled with "relaxed".  As same as the "relaxed"
652           option, this option may be used to parse application-specific files
653           written by humans.
654
655       $json = $json->allow_barekey ([$enable])
656       $enabled = $json->get_allow_barekey
657               $json = $json->allow_barekey([$enable])
658
659           If $enable is true (or missing), then "decode" will accept bare
660           keys of JSON object that are invalid JSON format.
661
662           Same as with the "relaxed" option, this option may be used to parse
663           application-specific files written by humans.
664
665               $json->allow_barekey->decode('{foo:"bar"}');
666
667       $json = $json->allow_bignum ([$enable])
668       $enabled = $json->get_allow_bignum
669               $json = $json->allow_bignum([$enable])
670
671           If $enable is true (or missing), then "decode" will convert the big
672           integer Perl cannot handle as integer into a Math::BigInt object
673           and convert a floating number (any) into a Math::BigFloat.
674
675           On the contrary, "encode" converts "Math::BigInt" objects and
676           "Math::BigFloat" objects into JSON numbers with "allow_blessed"
677           enable.
678
679              $json->allow_nonref->allow_blessed->allow_bignum;
680              $bigfloat = $json->decode('2.000000000000000000000000001');
681              print $json->encode($bigfloat);
682              # => 2.000000000000000000000000001
683
684           See "MAPPING" about the normal conversion of JSON number.
685
686       $json = $json->allow_bigint ([$enable])
687           This option is obsolete and replaced by allow_bignum.
688
689       $json = $json->allow_nonref ([$enable])
690       $enabled = $json->get_allow_nonref
691           If $enable is true (or missing), then the "encode" method can
692           convert a non-reference into its corresponding string, number or
693           null JSON value, which is an extension to RFC4627. Likewise,
694           "decode" will accept those JSON values instead of croaking.
695
696           If $enable is false, then the "encode" method will croak if it
697           isn't passed an arrayref or hashref, as JSON texts must either be
698           an object or array. Likewise, "decode" will croak if given
699           something that is not a JSON object or array.
700
701           Example, encode a Perl scalar as JSON value with enabled
702           "allow_nonref", resulting in an invalid JSON text:
703
704              Cpanel::JSON::XS->new->allow_nonref->encode ("Hello, World!")
705              => "Hello, World!"
706
707       $json = $json->allow_unknown ([$enable])
708       $enabled = $json->get_allow_unknown
709           If $enable is true (or missing), then "encode" will not throw an
710           exception when it encounters values it cannot represent in JSON
711           (for example, filehandles) but instead will encode a JSON "null"
712           value. Note that blessed objects are not included here and are
713           handled separately by c<allow_nonref>.
714
715           If $enable is false (the default), then "encode" will throw an
716           exception when it encounters anything it cannot encode as JSON.
717
718           This option does not affect "decode" in any way, and it is
719           recommended to leave it off unless you know your communications
720           partner.
721
722       $json = $json->allow_stringify ([$enable])
723       $enabled = $json->get_allow_stringify
724           If $enable is true (or missing), then "encode" will stringify the
725           non-object perl value or reference. Note that blessed objects are
726           not included here and are handled separately by "allow_blessed" and
727           "convert_blessed".  String references are stringified to the string
728           value, other references as in perl.
729
730           This option does not affect "decode" in any way.
731
732           This option is special to this module, it is not supported by other
733           encoders.  So it is not recommended to use it.
734
735       $json = $json->require_types ([$enable])
736       $enable = $json->get_require_types
737                $json = $json->require_types([$enable])
738
739           If $enable is true (or missing), then "encode" will require either
740           enabled "type_all_string" or second argument with supplied JSON
741           types.  See Cpanel::JSON::XS::Type. When "type_all_string" is not
742           enabled or second argument is not provided (or is undef), then
743           "encode" croaks. It also croaks when the type for provided
744           structure in "encode" is incomplete.
745
746       $json = $json->type_all_string ([$enable])
747       $enable = $json->get_type_all_string
748                $json = $json->type_all_string([$enable])
749
750           If $enable is true (or missing), then "encode" will always produce
751           stable deterministic JSON string types in resulted output.
752
753           When $enable is false, then result of encoded JSON output may be
754           different for different Perl versions and may depends on loaded
755           modules.
756
757           This is useful it you need deterministic JSON types, independently
758           of used Perl version and other modules, but do not want to write
759           complicated type definitions for Cpanel::JSON::XS::Type.
760
761       $json = $json->allow_dupkeys ([$enable])
762       $enabled = $json->get_allow_dupkeys
763           If $enable is true (or missing), then the "decode" method will not
764           die when it encounters duplicate keys in a hash.  "allow_dupkeys"
765           is also enabled in the "relaxed" mode.
766
767           The JSON spec allows duplicate name in objects but recommends to
768           disable it, however with Perl hashes they are impossible, parsing
769           JSON in Perl silently ignores duplicate names, using the last value
770           found.
771
772           See <http://seriot.ch/parsing_json.php#24>: RFC 7159 section 4:
773           "The names within an object should be unique."
774
775       $json = $json->allow_blessed ([$enable])
776       $enabled = $json->get_allow_blessed
777           If $enable is true (or missing), then the "encode" method will not
778           barf when it encounters a blessed reference. Instead, the value of
779           the convert_blessed option will decide whether "null"
780           ("convert_blessed" disabled or no "TO_JSON" method found) or a
781           representation of the object ("convert_blessed" enabled and
782           "TO_JSON" method found) is being encoded. Has no effect on
783           "decode".
784
785           If $enable is false (the default), then "encode" will throw an
786           exception when it encounters a blessed object without
787           "convert_blessed" and a "TO_JSON" method.
788
789           This setting has no effect on "decode".
790
791       $json = $json->convert_blessed ([$enable])
792       $enabled = $json->get_convert_blessed
793           If $enable is true (or missing), then "encode", upon encountering a
794           blessed object, will check for the availability of the "TO_JSON"
795           method on the object's class. If found, it will be called in scalar
796           context and the resulting scalar will be encoded instead of the
797           object. If no "TO_JSON" method is found, a stringification overload
798           method is tried next.  If both are not found, the value of
799           "allow_blessed" will decide what to do.
800
801           The "TO_JSON" method may safely call die if it wants. If "TO_JSON"
802           returns other blessed objects, those will be handled in the same
803           way. "TO_JSON" must take care of not causing an endless recursion
804           cycle (== crash) in this case. The same care must be taken with
805           calling encode in stringify overloads (even if this works by luck
806           in older perls) or other callbacks.  The name of "TO_JSON" was
807           chosen because other methods called by the Perl core (== not by the
808           user of the object) are usually in upper case letters and to avoid
809           collisions with any "to_json" function or method.
810
811           If $enable is false (the default), then "encode" will not consider
812           this type of conversion.
813
814           This setting has no effect on "decode".
815
816       $json = $json->allow_tags ([$enable])
817       $enabled = $json->get_allow_tags
818           See "OBJECT SERIALIZATION" for details.
819
820           If $enable is true (or missing), then "encode", upon encountering a
821           blessed object, will check for the availability of the "FREEZE"
822           method on the object's class. If found, it will be used to
823           serialize the object into a nonstandard tagged JSON value (that
824           JSON decoders cannot decode).
825
826           It also causes "decode" to parse such tagged JSON values and
827           deserialize them via a call to the "THAW" method.
828
829           If $enable is false (the default), then "encode" will not consider
830           this type of conversion, and tagged JSON values will cause a parse
831           error in "decode", as if tags were not part of the grammar.
832
833       $json = $json->filter_json_object ([$coderef->($hashref)])
834           When $coderef is specified, it will be called from "decode" each
835           time it decodes a JSON object. The only argument is a reference to
836           the newly-created hash. If the code references returns a single
837           scalar (which need not be a reference), this value (i.e. a copy of
838           that scalar to avoid aliasing) is inserted into the deserialized
839           data structure. If it returns an empty list (NOTE: not "undef",
840           which is a valid scalar), the original deserialized hash will be
841           inserted. This setting can slow down decoding considerably.
842
843           When $coderef is omitted or undefined, any existing callback will
844           be removed and "decode" will not change the deserialized hash in
845           any way.
846
847           Example, convert all JSON objects into the integer 5:
848
849              my $js = Cpanel::JSON::XS->new->filter_json_object (sub { 5 });
850              # returns [5]
851              $js->decode ('[{}]')
852              # throw an exception because allow_nonref is not enabled
853              # so a lone 5 is not allowed.
854              $js->decode ('{"a":1, "b":2}');
855
856       $json = $json->filter_json_single_key_object ($key [=>
857       $coderef->($value)])
858           Works remotely similar to "filter_json_object", but is only called
859           for JSON objects having a single key named $key.
860
861           This $coderef is called before the one specified via
862           "filter_json_object", if any. It gets passed the single value in
863           the JSON object. If it returns a single value, it will be inserted
864           into the data structure. If it returns nothing (not even "undef"
865           but the empty list), the callback from "filter_json_object" will be
866           called next, as if no single-key callback were specified.
867
868           If $coderef is omitted or undefined, the corresponding callback
869           will be disabled. There can only ever be one callback for a given
870           key.
871
872           As this callback gets called less often then the
873           "filter_json_object" one, decoding speed will not usually suffer as
874           much. Therefore, single-key objects make excellent targets to
875           serialize Perl objects into, especially as single-key JSON objects
876           are as close to the type-tagged value concept as JSON gets (it's
877           basically an ID/VALUE tuple). Of course, JSON does not support this
878           in any way, so you need to make sure your data never looks like a
879           serialized Perl hash.
880
881           Typical names for the single object key are "__class_whatever__",
882           or "$__dollars_are_rarely_used__$" or "}ugly_brace_placement", or
883           even things like "__class_md5sum(classname)__", to reduce the risk
884           of clashing with real hashes.
885
886           Example, decode JSON objects of the form "{ "__widget__" => <id> }"
887           into the corresponding $WIDGET{<id>} object:
888
889              # return whatever is in $WIDGET{5}:
890              Cpanel::JSON::XS
891                 ->new
892                 ->filter_json_single_key_object (__widget__ => sub {
893                       $WIDGET{ $_[0] }
894                    })
895                 ->decode ('{"__widget__": 5')
896
897              # this can be used with a TO_JSON method in some "widget" class
898              # for serialization to json:
899              sub WidgetBase::TO_JSON {
900                 my ($self) = @_;
901
902                 unless ($self->{id}) {
903                    $self->{id} = ..get..some..id..;
904                    $WIDGET{$self->{id}} = $self;
905                 }
906
907                 { __widget__ => $self->{id} }
908              }
909
910       $json = $json->shrink ([$enable])
911       $enabled = $json->get_shrink
912           Perl usually over-allocates memory a bit when allocating space for
913           strings. This flag optionally resizes strings generated by either
914           "encode" or "decode" to their minimum size possible. This can save
915           memory when your JSON texts are either very very long or you have
916           many short strings. It will also try to downgrade any strings to
917           octet-form if possible: perl stores strings internally either in an
918           encoding called UTF-X or in octet-form. The latter cannot store
919           everything but uses less space in general (and some buggy Perl or C
920           code might even rely on that internal representation being used).
921
922           The actual definition of what shrink does might change in future
923           versions, but it will always try to save space at the expense of
924           time.
925
926           If $enable is true (or missing), the string returned by "encode"
927           will be shrunk-to-fit, while all strings generated by "decode" will
928           also be shrunk-to-fit.
929
930           If $enable is false, then the normal perl allocation algorithms are
931           used.  If you work with your data, then this is likely to be
932           faster.
933
934           In the future, this setting might control other things, such as
935           converting strings that look like integers or floats into integers
936           or floats internally (there is no difference on the Perl level),
937           saving space.
938
939       $json = $json->max_depth ([$maximum_nesting_depth])
940       $max_depth = $json->get_max_depth
941           Sets the maximum nesting level (default 512) accepted while
942           encoding or decoding. If a higher nesting level is detected in JSON
943           text or a Perl data structure, then the encoder and decoder will
944           stop and croak at that point.
945
946           Nesting level is defined by number of hash- or arrayrefs that the
947           encoder needs to traverse to reach a given point or the number of
948           "{" or "[" characters without their matching closing parenthesis
949           crossed to reach a given character in a string.
950
951           Setting the maximum depth to one disallows any nesting, so that
952           ensures that the object is only a single hash/object or array.
953
954           If no argument is given, the highest possible setting will be used,
955           which is rarely useful.
956
957           Note that nesting is implemented by recursion in C. The default
958           value has been chosen to be as large as typical operating systems
959           allow without crashing.
960
961           See "SECURITY CONSIDERATIONS", below, for more info on why this is
962           useful.
963
964       $json = $json->max_size ([$maximum_string_size])
965       $max_size = $json->get_max_size
966           Set the maximum length a JSON text may have (in bytes) where
967           decoding is being attempted. The default is 0, meaning no limit.
968           When "decode" is called on a string that is longer then this many
969           bytes, it will not attempt to decode the string but throw an
970           exception. This setting has no effect on "encode" (yet).
971
972           If no argument is given, the limit check will be deactivated (same
973           as when 0 is specified).
974
975           See "SECURITY CONSIDERATIONS", below, for more info on why this is
976           useful.
977
978       $json->stringify_infnan ([$infnan_mode = 1])
979       $infnan_mode = $json->get_stringify_infnan
980           Get or set how Cpanel::JSON::XS encodes "inf", "-inf" or "nan" for
981           numeric values. Also qnan, snan or negative nan on some platforms.
982
983           "null":     infnan_mode = 0. Similar to most JSON modules in other
984           languages.  Always null.
985
986           stringified: infnan_mode = 1. As in Mojo::JSON. Platform specific
987           strings.  Stringified via sprintf(%g), with double quotes.
988
989           inf/nan:     infnan_mode = 2. As in JSON::XS, and older releases.
990           Passes through platform dependent values, invalid JSON. Stringified
991           via sprintf(%g), but without double quotes.
992
993           "inf/-inf/nan": infnan_mode = 3. Platform independent inf/nan/-inf
994           strings.  No QNAN/SNAN/negative NAN support, unified to "nan". Much
995           easier to detect, but may conflict with valid strings.
996
997       $json_text = $json->encode ($perl_scalar, $json_type)
998           Converts the given Perl data structure (a simple scalar or a
999           reference to a hash or array) to its JSON representation. Simple
1000           scalars will be converted into JSON string or number sequences,
1001           while references to arrays become JSON arrays and references to
1002           hashes become JSON objects. Undefined Perl values (e.g. "undef")
1003           become JSON "null" values. Neither "true" nor "false" values will
1004           be generated.
1005
1006           For the type argument see Cpanel::JSON::XS::Type.
1007
1008       $perl_scalar = $json->decode ($json_text, my $json_type)
1009           The opposite of "encode": expects a JSON text and tries to parse
1010           it, returning the resulting simple scalar or reference. Croaks on
1011           error.
1012
1013           JSON numbers and strings become simple Perl scalars. JSON arrays
1014           become Perl arrayrefs and JSON objects become Perl hashrefs. "true"
1015           becomes 1, "false" becomes 0 and "null" becomes "undef".
1016
1017           For the type argument see Cpanel::JSON::XS::Type.
1018
1019       ($perl_scalar, $characters) = $json->decode_prefix ($json_text)
1020           This works like the "decode" method, but instead of raising an
1021           exception when there is trailing garbage after the first JSON
1022           object, it will silently stop parsing there and return the number
1023           of characters consumed so far.
1024
1025           This is useful if your JSON texts are not delimited by an outer
1026           protocol and you need to know where the JSON text ends.
1027
1028              Cpanel::JSON::XS->new->decode_prefix ("[1] the tail")
1029              => ([1], 3)
1030
1031       $json->to_json ($perl_hash_or_arrayref)
1032           Deprecated method for perl 5.8 and newer. Use encode_json instead.
1033
1034       $json->from_json ($utf8_encoded_json_text)
1035           Deprecated method for perl 5.8 and newer. Use decode_json instead.
1036

INCREMENTAL PARSING

1038       In some cases, there is the need for incremental parsing of JSON texts.
1039       While this module always has to keep both JSON text and resulting Perl
1040       data structure in memory at one time, it does allow you to parse a JSON
1041       stream incrementally. It does so by accumulating text until it has a
1042       full JSON object, which it then can decode. This process is similar to
1043       using "decode_prefix" to see if a full JSON object is available, but is
1044       much more efficient (and can be implemented with a minimum of method
1045       calls).
1046
1047       Cpanel::JSON::XS will only attempt to parse the JSON text once it is
1048       sure it has enough text to get a decisive result, using a very simple
1049       but truly incremental parser. This means that it sometimes won't stop
1050       as early as the full parser, for example, it doesn't detect mismatched
1051       parentheses. The only thing it guarantees is that it starts decoding as
1052       soon as a syntactically valid JSON text has been seen. This means you
1053       need to set resource limits (e.g. "max_size") to ensure the parser will
1054       stop parsing in the presence if syntax errors.
1055
1056       The following methods implement this incremental parser.
1057
1058       [void, scalar or list context] = $json->incr_parse ([$string])
1059           This is the central parsing function. It can both append new text
1060           and extract objects from the stream accumulated so far (both of
1061           these functions are optional).
1062
1063           If $string is given, then this string is appended to the already
1064           existing JSON fragment stored in the $json object.
1065
1066           After that, if the function is called in void context, it will
1067           simply return without doing anything further. This can be used to
1068           add more text in as many chunks as you want.
1069
1070           If the method is called in scalar context, then it will try to
1071           extract exactly one JSON object. If that is successful, it will
1072           return this object, otherwise it will return "undef". If there is a
1073           parse error, this method will croak just as "decode" would do (one
1074           can then use "incr_skip" to skip the erroneous part). This is the
1075           most common way of using the method.
1076
1077           And finally, in list context, it will try to extract as many
1078           objects from the stream as it can find and return them, or the
1079           empty list otherwise. For this to work, there must be no separators
1080           between the JSON objects or arrays, instead they must be
1081           concatenated back-to-back. If an error occurs, an exception will be
1082           raised as in the scalar context case. Note that in this case, any
1083           previously-parsed JSON texts will be lost.
1084
1085           Example: Parse some JSON arrays/objects in a given string and
1086           return them.
1087
1088              my @objs = Cpanel::JSON::XS->new->incr_parse ("[5][7][1,2]");
1089
1090       $lvalue_string = $json->incr_text (>5.8 only)
1091           This method returns the currently stored JSON fragment as an
1092           lvalue, that is, you can manipulate it. This only works when a
1093           preceding call to "incr_parse" in scalar context successfully
1094           returned an object, and 2. only with Perl >= 5.8
1095
1096           Under all other circumstances you must not call this function (I
1097           mean it.  although in simple tests it might actually work, it will
1098           fail under real world conditions). As a special exception, you can
1099           also call this method before having parsed anything.
1100
1101           This function is useful in two cases: a) finding the trailing text
1102           after a JSON object or b) parsing multiple JSON objects separated
1103           by non-JSON text (such as commas).
1104
1105       $json->incr_skip
1106           This will reset the state of the incremental parser and will remove
1107           the parsed text from the input buffer so far. This is useful after
1108           "incr_parse" died, in which case the input buffer and incremental
1109           parser state is left unchanged, to skip the text parsed so far and
1110           to reset the parse state.
1111
1112           The difference to "incr_reset" is that only text until the parse
1113           error occurred is removed.
1114
1115       $json->incr_reset
1116           This completely resets the incremental parser, that is, after this
1117           call, it will be as if the parser had never parsed anything.
1118
1119           This is useful if you want to repeatedly parse JSON objects and
1120           want to ignore any trailing data, which means you have to reset the
1121           parser after each successful decode.
1122
1123   LIMITATIONS
1124       All options that affect decoding are supported, except "allow_nonref".
1125       The reason for this is that it cannot be made to work sensibly: JSON
1126       objects and arrays are self-delimited, i.e. you can concatenate them
1127       back to back and still decode them perfectly. This does not hold true
1128       for JSON numbers, however.
1129
1130       For example, is the string 1 a single JSON number, or is it simply the
1131       start of 12? Or is 12 a single JSON number, or the concatenation of 1
1132       and 2? In neither case you can tell, and this is why Cpanel::JSON::XS
1133       takes the conservative route and disallows this case.
1134
1135   EXAMPLES
1136       Some examples will make all this clearer. First, a simple example that
1137       works similarly to "decode_prefix": We want to decode the JSON object
1138       at the start of a string and identify the portion after the JSON
1139       object:
1140
1141          my $text = "[1,2,3] hello";
1142
1143          my $json = new Cpanel::JSON::XS;
1144
1145          my $obj = $json->incr_parse ($text)
1146             or die "expected JSON object or array at beginning of string";
1147
1148          my $tail = $json->incr_text;
1149          # $tail now contains " hello"
1150
1151       Easy, isn't it?
1152
1153       Now for a more complicated example: Imagine a hypothetical protocol
1154       where you read some requests from a TCP stream, and each request is a
1155       JSON array, without any separation between them (in fact, it is often
1156       useful to use newlines as "separators", as these get interpreted as
1157       whitespace at the start of the JSON text, which makes it possible to
1158       test said protocol with "telnet"...).
1159
1160       Here is how you'd do it (it is trivial to write this in an event-based
1161       manner):
1162
1163          my $json = new Cpanel::JSON::XS;
1164
1165          # read some data from the socket
1166          while (sysread $socket, my $buf, 4096) {
1167
1168             # split and decode as many requests as possible
1169             for my $request ($json->incr_parse ($buf)) {
1170                # act on the $request
1171             }
1172          }
1173
1174       Another complicated example: Assume you have a string with JSON objects
1175       or arrays, all separated by (optional) comma characters (e.g. "[1],[2],
1176       [3]"). To parse them, we have to skip the commas between the JSON
1177       texts, and here is where the lvalue-ness of "incr_text" comes in
1178       useful:
1179
1180          my $text = "[1],[2], [3]";
1181          my $json = new Cpanel::JSON::XS;
1182
1183          # void context, so no parsing done
1184          $json->incr_parse ($text);
1185
1186          # now extract as many objects as possible. note the
1187          # use of scalar context so incr_text can be called.
1188          while (my $obj = $json->incr_parse) {
1189             # do something with $obj
1190
1191             # now skip the optional comma
1192             $json->incr_text =~ s/^ \s* , //x;
1193          }
1194
1195       Now lets go for a very complex example: Assume that you have a gigantic
1196       JSON array-of-objects, many gigabytes in size, and you want to parse
1197       it, but you cannot load it into memory fully (this has actually
1198       happened in the real world :).
1199
1200       Well, you lost, you have to implement your own JSON parser. But
1201       Cpanel::JSON::XS can still help you: You implement a (very simple)
1202       array parser and let JSON decode the array elements, which are all full
1203       JSON objects on their own (this wouldn't work if the array elements
1204       could be JSON numbers, for example):
1205
1206          my $json = new Cpanel::JSON::XS;
1207
1208          # open the monster
1209          open my $fh, "<bigfile.json"
1210             or die "bigfile: $!";
1211
1212          # first parse the initial "["
1213          for (;;) {
1214             sysread $fh, my $buf, 65536
1215                or die "read error: $!";
1216             $json->incr_parse ($buf); # void context, so no parsing
1217
1218             # Exit the loop once we found and removed(!) the initial "[".
1219             # In essence, we are (ab-)using the $json object as a simple scalar
1220             # we append data to.
1221             last if $json->incr_text =~ s/^ \s* \[ //x;
1222          }
1223
1224          # now we have the skipped the initial "[", so continue
1225          # parsing all the elements.
1226          for (;;) {
1227             # in this loop we read data until we got a single JSON object
1228             for (;;) {
1229                if (my $obj = $json->incr_parse) {
1230                   # do something with $obj
1231                   last;
1232                }
1233
1234                # add more data
1235                sysread $fh, my $buf, 65536
1236                   or die "read error: $!";
1237                $json->incr_parse ($buf); # void context, so no parsing
1238             }
1239
1240             # in this loop we read data until we either found and parsed the
1241             # separating "," between elements, or the final "]"
1242             for (;;) {
1243                # first skip whitespace
1244                $json->incr_text =~ s/^\s*//;
1245
1246                # if we find "]", we are done
1247                if ($json->incr_text =~ s/^\]//) {
1248                   print "finished.\n";
1249                   exit;
1250                }
1251
1252                # if we find ",", we can continue with the next element
1253                if ($json->incr_text =~ s/^,//) {
1254                   last;
1255                }
1256
1257                # if we find anything else, we have a parse error!
1258                if (length $json->incr_text) {
1259                   die "parse error near ", $json->incr_text;
1260                }
1261
1262                # else add more data
1263                sysread $fh, my $buf, 65536
1264                   or die "read error: $!";
1265                $json->incr_parse ($buf); # void context, so no parsing
1266             }
1267
1268       This is a complex example, but most of the complexity comes from the
1269       fact that we are trying to be correct (bear with me if I am wrong, I
1270       never ran the above example :).
1271

BOM

1273       Detect all unicode Byte Order Marks on decode.  Which are UTF-8,
1274       UTF-16LE, UTF-16BE, UTF-32LE and UTF-32BE.
1275
1276       The BOM encoding is set only for one specific decode call, it does not
1277       change the state of the JSON object.
1278
1279       Warning: With perls older than 5.20 you need load the Encode module
1280       before loading a multibyte BOM, i.e. >= UTF-16. Otherwise an error is
1281       thrown. This is an implementation limitation and might get fixed later.
1282
1283       See <https://tools.ietf.org/html/rfc7159#section-8.1> "JSON text SHALL
1284       be encoded in UTF-8, UTF-16, or UTF-32."
1285
1286       "Implementations MUST NOT add a byte order mark to the beginning of a
1287       JSON text", "implementations (...) MAY ignore the presence of a byte
1288       order mark rather than treating it as an error".
1289
1290       See also <http://www.unicode.org/faq/utf_bom.html#BOM>.
1291
1292       Beware that Cpanel::JSON::XS is currently the only JSON module which
1293       does accept and decode a BOM.
1294
1295       The latest JSON spec
1296       <https://www.greenbytes.de/tech/webdav/rfc8259.html#character.encoding>
1297       forbid the usage of UTF-16 or UTF-32, the character encoding is UTF-8.
1298       Thus in subsequent updates BOM's of UTF-16 or UTF-32 will throw an
1299       error.
1300

MAPPING

1302       This section describes how Cpanel::JSON::XS maps Perl values to JSON
1303       values and vice versa. These mappings are designed to "do the right
1304       thing" in most circumstances automatically, preserving round-tripping
1305       characteristics (what you put in comes out as something equivalent).
1306
1307       For the more enlightened: note that in the following descriptions,
1308       lowercase perl refers to the Perl interpreter, while uppercase Perl
1309       refers to the abstract Perl language itself.
1310
1311   JSON -> PERL
1312       object
1313           A JSON object becomes a reference to a hash in Perl. No ordering of
1314           object keys is preserved (JSON does not preserve object key
1315           ordering itself).
1316
1317       array
1318           A JSON array becomes a reference to an array in Perl.
1319
1320       string
1321           A JSON string becomes a string scalar in Perl - Unicode codepoints
1322           in JSON are represented by the same codepoints in the Perl string,
1323           so no manual decoding is necessary.
1324
1325       number
1326           A JSON number becomes either an integer, numeric (floating point)
1327           or string scalar in perl, depending on its range and any fractional
1328           parts. On the Perl level, there is no difference between those as
1329           Perl handles all the conversion details, but an integer may take
1330           slightly less memory and might represent more values exactly than
1331           floating point numbers.
1332
1333           If the number consists of digits only, Cpanel::JSON::XS will try to
1334           represent it as an integer value. If that fails, it will try to
1335           represent it as a numeric (floating point) value if that is
1336           possible without loss of precision. Otherwise it will preserve the
1337           number as a string value (in which case you lose roundtripping
1338           ability, as the JSON number will be re-encoded to a JSON string).
1339
1340           Numbers containing a fractional or exponential part will always be
1341           represented as numeric (floating point) values, possibly at a loss
1342           of precision (in which case you might lose perfect roundtripping
1343           ability, but the JSON number will still be re-encoded as a JSON
1344           number).
1345
1346           Note that precision is not accuracy - binary floating point values
1347           cannot represent most decimal fractions exactly, and when
1348           converting from and to floating point, "Cpanel::JSON::XS" only
1349           guarantees precision up to but not including the least significant
1350           bit.
1351
1352       true, false
1353           When "unblessed_bool" is set to true, then JSON "true" becomes 1
1354           and JSON "false" becomes 0.
1355
1356           Otherwise these JSON atoms become "JSON::PP::true" and
1357           "JSON::PP::false", respectively. They are "JSON::PP::Boolean"
1358           objects and are overloaded to act almost exactly like the numbers 1
1359           and 0. You can check whether a scalar is a JSON boolean by using
1360           the "Cpanel::JSON::XS::is_bool" function.
1361
1362           The other round, from perl to JSON, "!0" which is represented as
1363           "yes" becomes "true", and "!1" which is represented as "no" becomes
1364           "false".
1365
1366           Via Cpanel::JSON::XS::Type you can now even force negation in
1367           "encode", without overloading of "!":
1368
1369               my $false = Cpanel::JSON::XS::false;
1370               print($json->encode([!$false], [JSON_TYPE_BOOL]));
1371               => [true]
1372
1373       null
1374           A JSON null atom becomes "undef" in Perl.
1375
1376       shell-style comments ("# text")
1377           As a nonstandard extension to the JSON syntax that is enabled by
1378           the "relaxed" setting, shell-style comments are allowed. They can
1379           start anywhere outside strings and go till the end of the line.
1380
1381       tagged values ("(tag)value").
1382           Another nonstandard extension to the JSON syntax, enabled with the
1383           "allow_tags" setting, are tagged values. In this implementation,
1384           the tag must be a perl package/class name encoded as a JSON string,
1385           and the value must be a JSON array encoding optional constructor
1386           arguments.
1387
1388           See "OBJECT SERIALIZATION", below, for details.
1389
1390   PERL -> JSON
1391       The mapping from Perl to JSON is slightly more difficult, as Perl is a
1392       truly typeless language, so we can only guess which JSON type is meant
1393       by a Perl value.
1394
1395       hash references
1396           Perl hash references become JSON objects. As there is no inherent
1397           ordering in hash keys (or JSON objects), they will usually be
1398           encoded in a pseudo-random order that can change between runs of
1399           the same program but stays generally the same within a single run
1400           of a program. Cpanel::JSON::XS can optionally sort the hash keys
1401           (determined by the canonical flag), so the same datastructure will
1402           serialize to the same JSON text (given same settings and version of
1403           Cpanel::JSON::XS), but this incurs a runtime overhead and is only
1404           rarely useful, e.g. when you want to compare some JSON text against
1405           another for equality.
1406
1407       array references
1408           Perl array references become JSON arrays.
1409
1410       other references
1411           Other unblessed references are generally not allowed and will cause
1412           an exception to be thrown, except for references to the integers 0
1413           and 1, which get turned into "false" and "true" atoms in JSON.
1414
1415           With the option "allow_stringify", you can ignore the exception and
1416           return the stringification of the perl value.
1417
1418           With the option "allow_unknown", you can ignore the exception and
1419           return "null" instead.
1420
1421              encode_json [\"x"]        # => cannot encode reference to scalar 'SCALAR(0x..)'
1422                                        # unless the scalar is 0 or 1
1423              encode_json [\0, \1]      # yields [false,true]
1424
1425              allow_stringify->encode_json [\"x"] # yields "x" unlike JSON::PP
1426              allow_unknown->encode_json [\"x"]   # yields null as in JSON::PP
1427
1428       Cpanel::JSON::XS::true, Cpanel::JSON::XS::false
1429           These special values become JSON true and JSON false values,
1430           respectively. You can also use "\1" and "\0" or "!0" and "!1"
1431           directly if you want.
1432
1433              encode_json [Cpanel::JSON::XS::false, Cpanel::JSON::XS::true] # yields [false,true]
1434              encode_json [!1, !0], [JSON_TYPE_BOOL, JSON_TYPE_BOOL] # yields [false,true]
1435
1436           eq/ne comparisons with true, false:
1437
1438           false is eq to the empty string or the string 'false' or the
1439           special empty string "!!0" or "!1", i.e. "SV_NO", or the numbers 0
1440           or 0.0.
1441
1442           true is eq to the string 'true' or to the special string "!0" (i.e.
1443           "SV_YES") or to the numbers 1 or 1.0.
1444
1445       blessed objects
1446           Blessed objects are not directly representable in JSON, but
1447           "Cpanel::JSON::XS" allows various optional ways of handling
1448           objects. See "OBJECT SERIALIZATION", below, for details.
1449
1450           See the "allow_blessed" and "convert_blessed" methods on various
1451           options on how to deal with this: basically, you can choose between
1452           throwing an exception, encoding the reference as if it weren't
1453           blessed, use the objects overloaded stringification method or
1454           provide your own serializer method.
1455
1456       simple scalars
1457           Simple Perl scalars (any scalar that is not a reference) are the
1458           most difficult objects to encode: Cpanel::JSON::XS will encode
1459           undefined scalars or inf/nan as JSON "null" values and other
1460           scalars to either number or string in non-deterministic way which
1461           may be affected or changed by Perl version or any other loaded Perl
1462           module.
1463
1464           If you want to have stable and deterministic types in JSON encoder
1465           then use Cpanel::JSON::XS::Type.
1466
1467           Alternative way for deterministic types is to use "type_all_string"
1468           method when all perl scalars are encoded to JSON strings.
1469
1470           Non-deterministic behavior is following: scalars that have last
1471           been used in a string context before encoding as JSON strings, and
1472           anything else as number value:
1473
1474              # dump as number
1475              encode_json [2]                      # yields [2]
1476              encode_json [-3.0e17]                # yields [-3e+17]
1477              my $value = 5; encode_json [$value]  # yields [5]
1478
1479              # used as string, but the two representations are for the same number
1480              print $value;
1481              encode_json [$value]                 # yields [5]
1482
1483              # used as different string (non-matching dual-var)
1484              my $str = '0 but true';
1485              my $num = 1 + $str;
1486              encode_json [$num, $str]           # yields [1,"0 but true"]
1487
1488              # undef becomes null
1489              encode_json [undef]                  # yields [null]
1490
1491              # inf or nan becomes null, unless you answered
1492              # "Do you want to handle inf/nan as strings" with yes
1493              encode_json [9**9**9]                # yields [null]
1494
1495           You can force the type to be a JSON string by stringifying it:
1496
1497              my $x = 3.1; # some variable containing a number
1498              "$x";        # stringified
1499              $x .= "";    # another, more awkward way to stringify
1500              print $x;    # perl does it for you, too, quite often
1501
1502           You can force the type to be a JSON number by numifying it:
1503
1504              my $x = "3"; # some variable containing a string
1505              $x += 0;     # numify it, ensuring it will be dumped as a number
1506              $x *= 1;     # same thing, the choice is yours.
1507
1508           Note that numerical precision has the same meaning as under Perl
1509           (so binary to decimal conversion follows the same rules as in Perl,
1510           which can differ to other languages). Also, your perl interpreter
1511           might expose extensions to the floating point numbers of your
1512           platform, such as infinities or NaN's - these cannot be represented
1513           in JSON, and thus null is returned instead. Optionally you can
1514           configure it to stringify inf and nan values.
1515
1516   OBJECT SERIALIZATION
1517       As JSON cannot directly represent Perl objects, you have to choose
1518       between a pure JSON representation (without the ability to deserialize
1519       the object automatically again), and a nonstandard extension to the
1520       JSON syntax, tagged values.
1521
1522       SERIALIZATION
1523
1524       What happens when "Cpanel::JSON::XS" encounters a Perl object depends
1525       on the "allow_blessed", "convert_blessed" and "allow_tags" settings,
1526       which are used in this order:
1527
1528       1. "allow_tags" is enabled and the object has a "FREEZE" method.
1529           In this case, "Cpanel::JSON::XS" uses the Types::Serialiser object
1530           serialization protocol to create a tagged JSON value, using a
1531           nonstandard extension to the JSON syntax.
1532
1533           This works by invoking the "FREEZE" method on the object, with the
1534           first argument being the object to serialize, and the second
1535           argument being the constant string "JSON" to distinguish it from
1536           other serializers.
1537
1538           The "FREEZE" method can return any number of values (i.e. zero or
1539           more). These values and the paclkage/classname of the object will
1540           then be encoded as a tagged JSON value in the following format:
1541
1542              ("classname")[FREEZE return values...]
1543
1544           e.g.:
1545
1546              ("URI")["http://www.google.com/"]
1547              ("MyDate")[2013,10,29]
1548              ("ImageData::JPEG")["Z3...VlCg=="]
1549
1550           For example, the hypothetical "My::Object" "FREEZE" method might
1551           use the objects "type" and "id" members to encode the object:
1552
1553              sub My::Object::FREEZE {
1554                 my ($self, $serializer) = @_;
1555
1556                 ($self->{type}, $self->{id})
1557              }
1558
1559       2. "convert_blessed" is enabled and the object has a "TO_JSON" method.
1560           In this case, the "TO_JSON" method of the object is invoked in
1561           scalar context. It must return a single scalar that can be directly
1562           encoded into JSON. This scalar replaces the object in the JSON
1563           text.
1564
1565           For example, the following "TO_JSON" method will convert all URI
1566           objects to JSON strings when serialized. The fact that these values
1567           originally were URI objects is lost.
1568
1569              sub URI::TO_JSON {
1570                 my ($uri) = @_;
1571                 $uri->as_string
1572              }
1573
1574       3. "convert_blessed" is enabled and the object has a stringification
1575       overload.
1576           In this case, the overloaded "" method of the object is invoked in
1577           scalar context. It must return a single scalar that can be directly
1578           encoded into JSON. This scalar replaces the object in the JSON
1579           text.
1580
1581           For example, the following "" method will convert all URI objects
1582           to JSON strings when serialized. The fact that these values
1583           originally were URI objects is lost.
1584
1585               package URI;
1586               use overload '""' => sub { shift->as_string };
1587
1588       4. "allow_blessed" is enabled.
1589           The object will be serialized as a JSON null value.
1590
1591       5. none of the above
1592           If none of the settings are enabled or the respective methods are
1593           missing, "Cpanel::JSON::XS" throws an exception.
1594
1595       DESERIALIZATION
1596
1597       For deserialization there are only two cases to consider: either
1598       nonstandard tagging was used, in which case "allow_tags" decides, or
1599       objects cannot be automatically be deserialized, in which case you can
1600       use postprocessing or the "filter_json_object" or
1601       "filter_json_single_key_object" callbacks to get some real objects our
1602       of your JSON.
1603
1604       This section only considers the tagged value case: I a tagged JSON
1605       object is encountered during decoding and "allow_tags" is disabled, a
1606       parse error will result (as if tagged values were not part of the
1607       grammar).
1608
1609       If "allow_tags" is enabled, "Cpanel::JSON::XS" will look up the "THAW"
1610       method of the package/classname used during serialization (it will not
1611       attempt to load the package as a Perl module). If there is no such
1612       method, the decoding will fail with an error.
1613
1614       Otherwise, the "THAW" method is invoked with the classname as first
1615       argument, the constant string "JSON" as second argument, and all the
1616       values from the JSON array (the values originally returned by the
1617       "FREEZE" method) as remaining arguments.
1618
1619       The method must then return the object. While technically you can
1620       return any Perl scalar, you might have to enable the "enable_nonref"
1621       setting to make that work in all cases, so better return an actual
1622       blessed reference.
1623
1624       As an example, let's implement a "THAW" function that regenerates the
1625       "My::Object" from the "FREEZE" example earlier:
1626
1627          sub My::Object::THAW {
1628             my ($class, $serializer, $type, $id) = @_;
1629
1630             $class->new (type => $type, id => $id)
1631          }
1632
1633       See the "SECURITY CONSIDERATIONS" section below. Allowing external json
1634       objects being deserialized to perl objects is usually a very bad idea.
1635

ENCODING/CODESET FLAG NOTES

1637       The interested reader might have seen a number of flags that signify
1638       encodings or codesets - "utf8", "latin1", "binary" and "ascii". There
1639       seems to be some confusion on what these do, so here is a short
1640       comparison:
1641
1642       "utf8" controls whether the JSON text created by "encode" (and expected
1643       by "decode") is UTF-8 encoded or not, while "latin1" and "ascii" only
1644       control whether "encode" escapes character values outside their
1645       respective codeset range. Neither of these flags conflict with each
1646       other, although some combinations make less sense than others.
1647
1648       Care has been taken to make all flags symmetrical with respect to
1649       "encode" and "decode", that is, texts encoded with any combination of
1650       these flag values will be correctly decoded when the same flags are
1651       used - in general, if you use different flag settings while encoding
1652       vs. when decoding you likely have a bug somewhere.
1653
1654       Below comes a verbose discussion of these flags. Note that a "codeset"
1655       is simply an abstract set of character-codepoint pairs, while an
1656       encoding takes those codepoint numbers and encodes them, in our case
1657       into octets. Unicode is (among other things) a codeset, UTF-8 is an
1658       encoding, and ISO-8859-1 (= latin 1) and ASCII are both codesets and
1659       encodings at the same time, which can be confusing.
1660
1661       "utf8" flag disabled
1662           When "utf8" is disabled (the default), then "encode"/"decode"
1663           generate and expect Unicode strings, that is, characters with high
1664           ordinal Unicode values (> 255) will be encoded as such characters,
1665           and likewise such characters are decoded as-is, no changes to them
1666           will be done, except "(re-)interpreting" them as Unicode codepoints
1667           or Unicode characters, respectively (to Perl, these are the same
1668           thing in strings unless you do funny/weird/dumb stuff).
1669
1670           This is useful when you want to do the encoding yourself (e.g. when
1671           you want to have UTF-16 encoded JSON texts) or when some other
1672           layer does the encoding for you (for example, when printing to a
1673           terminal using a filehandle that transparently encodes to UTF-8 you
1674           certainly do NOT want to UTF-8 encode your data first and have Perl
1675           encode it another time).
1676
1677       "utf8" flag enabled
1678           If the "utf8"-flag is enabled, "encode"/"decode" will encode all
1679           characters using the corresponding UTF-8 multi-byte sequence, and
1680           will expect your input strings to be encoded as UTF-8, that is, no
1681           "character" of the input string must have any value > 255, as UTF-8
1682           does not allow that.
1683
1684           The "utf8" flag therefore switches between two modes: disabled
1685           means you will get a Unicode string in Perl, enabled means you get
1686           an UTF-8 encoded octet/binary string in Perl.
1687
1688       "latin1", "binary" or "ascii" flags enabled
1689           With "latin1" (or "ascii") enabled, "encode" will escape characters
1690           with ordinal values > 255 (> 127 with "ascii") and encode the
1691           remaining characters as specified by the "utf8" flag.  With
1692           "binary" enabled, ordinal values > 255 are illegal.
1693
1694           If "utf8" is disabled, then the result is also correctly encoded in
1695           those character sets (as both are proper subsets of Unicode,
1696           meaning that a Unicode string with all character values < 256 is
1697           the same thing as a ISO-8859-1 string, and a Unicode string with
1698           all character values < 128 is the same thing as an ASCII string in
1699           Perl).
1700
1701           If "utf8" is enabled, you still get a correct UTF-8-encoded string,
1702           regardless of these flags, just some more characters will be
1703           escaped using "\uXXXX" then before.
1704
1705           Note that ISO-8859-1-encoded strings are not compatible with UTF-8
1706           encoding, while ASCII-encoded strings are. That is because the
1707           ISO-8859-1 encoding is NOT a subset of UTF-8 (despite the
1708           ISO-8859-1 codeset being a subset of Unicode), while ASCII is.
1709
1710           Surprisingly, "decode" will ignore these flags and so treat all
1711           input values as governed by the "utf8" flag. If it is disabled,
1712           this allows you to decode ISO-8859-1- and ASCII-encoded strings, as
1713           both strict subsets of Unicode. If it is enabled, you can correctly
1714           decode UTF-8 encoded strings.
1715
1716           So neither "latin1", "binary" nor "ascii" are incompatible with the
1717           "utf8" flag - they only govern when the JSON output engine escapes
1718           a character or not.
1719
1720           The main use for "latin1" or "binary" is to relatively efficiently
1721           store binary data as JSON, at the expense of breaking compatibility
1722           with most JSON decoders.
1723
1724           The main use for "ascii" is to force the output to not contain
1725           characters with values > 127, which means you can interpret the
1726           resulting string as UTF-8, ISO-8859-1, ASCII, KOI8-R or most about
1727           any character set and 8-bit-encoding, and still get the same data
1728           structure back. This is useful when your channel for JSON transfer
1729           is not 8-bit clean or the encoding might be mangled in between
1730           (e.g. in mail), and works because ASCII is a proper subset of most
1731           8-bit and multibyte encodings in use in the world.
1732
1733   JSON and ECMAscript
1734       JSON syntax is based on how literals are represented in javascript (the
1735       not-standardized predecessor of ECMAscript) which is presumably why it
1736       is called "JavaScript Object Notation".
1737
1738       However, JSON is not a subset (and also not a superset of course) of
1739       ECMAscript (the standard) or javascript (whatever browsers actually
1740       implement).
1741
1742       If you want to use javascript's "eval" function to "parse" JSON, you
1743       might run into parse errors for valid JSON texts, or the resulting data
1744       structure might not be queryable:
1745
1746       One of the problems is that U+2028 and U+2029 are valid characters
1747       inside JSON strings, but are not allowed in ECMAscript string literals,
1748       so the following Perl fragment will not output something that can be
1749       guaranteed to be parsable by javascript's "eval":
1750
1751          use Cpanel::JSON::XS;
1752
1753          print encode_json [chr 0x2028];
1754
1755       The right fix for this is to use a proper JSON parser in your
1756       javascript programs, and not rely on "eval" (see for example Douglas
1757       Crockford's json2.js parser).
1758
1759       If this is not an option, you can, as a stop-gap measure, simply encode
1760       to ASCII-only JSON:
1761
1762          use Cpanel::JSON::XS;
1763
1764          print Cpanel::JSON::XS->new->ascii->encode ([chr 0x2028]);
1765
1766       Note that this will enlarge the resulting JSON text quite a bit if you
1767       have many non-ASCII characters. You might be tempted to run some
1768       regexes to only escape U+2028 and U+2029, e.g.:
1769
1770          # DO NOT USE THIS!
1771          my $json = Cpanel::JSON::XS->new->utf8->encode ([chr 0x2028]);
1772          $json =~ s/\xe2\x80\xa8/\\u2028/g; # escape U+2028
1773          $json =~ s/\xe2\x80\xa9/\\u2029/g; # escape U+2029
1774          print $json;
1775
1776       Note that this is a bad idea: the above only works for U+2028 and
1777       U+2029 and thus only for fully ECMAscript-compliant parsers. Many
1778       existing javascript implementations, however, have issues with other
1779       characters as well - using "eval" naively simply will cause problems.
1780
1781       Another problem is that some javascript implementations reserve some
1782       property names for their own purposes (which probably makes them non-
1783       ECMAscript-compliant). For example, Iceweasel reserves the "__proto__"
1784       property name for its own purposes.
1785
1786       If that is a problem, you could parse try to filter the resulting JSON
1787       output for these property strings, e.g.:
1788
1789          $json =~ s/"__proto__"\s*:/"__proto__renamed":/g;
1790
1791       This works because "__proto__" is not valid outside of strings, so
1792       every occurrence of ""__proto__"\s*:" must be a string used as property
1793       name.
1794
1795       Unicode non-characters between U+FFFD and U+10FFFF are decoded either
1796       to the recommended U+FFFD REPLACEMENT CHARACTER (see Unicode PR #121:
1797       Recommended Practice for Replacement Characters), or in the binary or
1798       relaxed mode left as is, keeping the illegal non-characters as before.
1799
1800       Raw non-Unicode characters outside the valid unicode range fail now to
1801       parse, because "A string is a sequence of zero or more Unicode
1802       characters" RFC 7159 section 1 and "JSON text SHALL be encoded in
1803       Unicode RFC 7159 section 8.1. We use now the UTF8_DISALLOW_SUPER flag
1804       when parsing unicode.
1805
1806       If you know of other incompatibilities, please let me know.
1807
1808   JSON and YAML
1809       You often hear that JSON is a subset of YAML.  in general, there is no
1810       way to configure JSON::XS to output a data structure as valid YAML that
1811       works in all cases.  If you really must use Cpanel::JSON::XS to
1812       generate YAML, you should use this algorithm (subject to change in
1813       future versions):
1814
1815          my $to_yaml = Cpanel::JSON::XS->new->utf8->space_after (1);
1816          my $yaml = $to_yaml->encode ($ref) . "\n";
1817
1818       This will usually generate JSON texts that also parse as valid YAML.
1819
1820   SPEED
1821       It seems that JSON::XS is surprisingly fast, as shown in the following
1822       tables. They have been generated with the help of the "eg/bench"
1823       program in the JSON::XS distribution, to make it easy to compare on
1824       your own system.
1825
1826       JSON::XS is with Data::MessagePack and Sereal one of the fastest
1827       serializers, because JSON and JSON::XS do not support backrefs (no
1828       graph structures), only trees. Storable supports backrefs, i.e. graphs.
1829       Data::MessagePack encodes its data binary (as Storable) and supports
1830       only very simple subset of JSON.
1831
1832       First comes a comparison between various modules using a very short
1833       single-line JSON string (also available at
1834       <http://dist.schmorp.de/misc/json/short.json>).
1835
1836          {"method": "handleMessage", "params": ["user1",
1837          "we were just talking"], "id": null, "array":[1,11,234,-5,1e5,1e7,
1838          1,  0]}
1839
1840       It shows the number of encodes/decodes per second (JSON::XS uses the
1841       functional interface, while Cpanel::JSON::XS/2 uses the OO interface
1842       with pretty-printing and hash key sorting enabled, Cpanel::JSON::XS/3
1843       enables shrink. JSON::DWIW/DS uses the deserialize function, while
1844       JSON::DWIW::FJ uses the from_json method). Higher is better:
1845
1846          module        |     encode |     decode |
1847          --------------|------------|------------|
1848          JSON::DWIW/DS |  86302.551 | 102300.098 |
1849          JSON::DWIW/FJ |  86302.551 |  75983.768 |
1850          JSON::PP      |  15827.562 |   6638.658 |
1851          JSON::Syck    |  63358.066 |  47662.545 |
1852          JSON::XS      | 511500.488 | 511500.488 |
1853          JSON::XS/2    | 291271.111 | 388361.481 |
1854          JSON::XS/3    | 361577.931 | 361577.931 |
1855          Storable      |  66788.280 | 265462.278 |
1856          --------------+------------+------------+
1857
1858       That is, JSON::XS is almost six times faster than JSON::DWIW on
1859       encoding, about five times faster on decoding, and over thirty to
1860       seventy times faster than JSON's pure perl implementation. It also
1861       compares favourably to Storable for small amounts of data.
1862
1863       Using a longer test string (roughly 18KB, generated from Yahoo! Locals
1864       search API (<http://dist.schmorp.de/misc/json/long.json>).
1865
1866          module        |     encode |     decode |
1867          --------------|------------|------------|
1868          JSON::DWIW/DS |   1647.927 |   2673.916 |
1869          JSON::DWIW/FJ |   1630.249 |   2596.128 |
1870          JSON::PP      |    400.640 |     62.311 |
1871          JSON::Syck    |   1481.040 |   1524.869 |
1872          JSON::XS      |  20661.596 |   9541.183 |
1873          JSON::XS/2    |  10683.403 |   9416.938 |
1874          JSON::XS/3    |  20661.596 |   9400.054 |
1875          Storable      |  19765.806 |  10000.725 |
1876          --------------+------------+------------+
1877
1878       Again, JSON::XS leads by far (except for Storable which non-
1879       surprisingly decodes a bit faster).
1880
1881       On large strings containing lots of high Unicode characters, some
1882       modules (such as JSON::PC) seem to decode faster than JSON::XS, but the
1883       result will be broken due to missing (or wrong) Unicode handling.
1884       Others refuse to decode or encode properly, so it was impossible to
1885       prepare a fair comparison table for that case.
1886
1887       For updated graphs see
1888       <https://github.com/Sereal/Sereal/wiki/Sereal-Comparison-Graphs>
1889

INTEROP with JSON and JSON::XS and other JSON modules

1891       As long as you only serialize data that can be directly expressed in
1892       JSON, "Cpanel::JSON::XS" is incapable of generating invalid JSON output
1893       (modulo bugs, but "JSON::XS" has found more bugs in the official JSON
1894       testsuite (1) than the official JSON testsuite has found in "JSON::XS"
1895       (0)).  "Cpanel::JSON::XS" is currently the only known JSON decoder
1896       which passes all <http://seriot.ch/parsing_json.html> tests, while
1897       being the fastest also.
1898
1899       When you have trouble decoding JSON generated by this module using
1900       other decoders, then it is very likely that you have an encoding
1901       mismatch or the other decoder is broken.
1902
1903       When decoding, "JSON::XS" is strict by default and will likely catch
1904       all errors. There are currently two settings that change this:
1905       "relaxed" makes "JSON::XS" accept (but not generate) some non-standard
1906       extensions, and "allow_tags" or "allow_blessed" will allow you to
1907       encode and decode Perl objects, at the cost of being totally insecure
1908       and not outputting valid JSON anymore.
1909
1910       JSON-XS-3.01 broke interoperability with JSON-2.90 with booleans. See
1911       JSON.
1912
1913       Cpanel::JSON::XS needs to know the JSON and JSON::XS versions to be
1914       able work with those objects, especially when encoding a booleans like
1915       "{"is_true":true}".  So you need to load these modules before.
1916
1917       true/false overloading and boolean representations are supported.
1918
1919       JSON::XS and JSON::PP representations are accepted and older JSON::XS
1920       accepts Cpanel::JSON::XS booleans. All JSON modules JSON, JSON, PP,
1921       JSON::XS, Cpanel::JSON::XS produce JSON::PP::Boolean objects, just Mojo
1922       and JSON::YAJL not.  Mojo produces Mojo::JSON::_Bool and
1923       JSON::YAJL::Parser just an unblessed IV.
1924
1925       Cpanel::JSON::XS accepts JSON::PP::Boolean and Mojo::JSON::_Bool
1926       objects as booleans.
1927
1928       I cannot think of any reason to still use JSON::XS anymore.
1929
1930   TAGGED VALUE SYNTAX AND STANDARD JSON EN/DECODERS
1931       When you use "allow_tags" to use the extended (and also nonstandard and
1932       invalid) JSON syntax for serialized objects, and you still want to
1933       decode the generated serialize objects, you can run a regex to replace
1934       the tagged syntax by standard JSON arrays (it only works for "normal"
1935       package names without comma, newlines or single colons). First, the
1936       readable Perl version:
1937
1938          # if your FREEZE methods return no values, you need this replace first:
1939          $json =~ s/\( \s* (" (?: [^\\":,]+|\\.|::)* ") \s* \) \s* \[\s*\]/[$1]/gx;
1940
1941          # this works for non-empty constructor arg lists:
1942          $json =~ s/\( \s* (" (?: [^\\":,]+|\\.|::)* ") \s* \) \s* \[/[$1,/gx;
1943
1944       And here is a less readable version that is easy to adapt to other
1945       languages:
1946
1947          $json =~ s/\(\s*("([^\\":,]+|\\.|::)*")\s*\)\s*\[/[$1,/g;
1948
1949       Here is an ECMAScript version (same regex):
1950
1951          json = json.replace (/\(\s*("([^\\":,]+|\\.|::)*")\s*\)\s*\[/g, "[$1,");
1952
1953       Since this syntax converts to standard JSON arrays, it might be hard to
1954       distinguish serialized objects from normal arrays. You can prepend a
1955       "magic number" as first array element to reduce chances of a collision:
1956
1957          $json =~ s/\(\s*("([^\\":,]+|\\.|::)*")\s*\)\s*\[/["XU1peReLzT4ggEllLanBYq4G9VzliwKF",$1,/g;
1958
1959       And after decoding the JSON text, you could walk the data structure
1960       looking for arrays with a first element of
1961       "XU1peReLzT4ggEllLanBYq4G9VzliwKF".
1962
1963       The same approach can be used to create the tagged format with another
1964       encoder. First, you create an array with the magic string as first
1965       member, the classname as second, and constructor arguments last, encode
1966       it as part of your JSON structure, and then:
1967
1968          $json =~ s/\[\s*"XU1peReLzT4ggEllLanBYq4G9VzliwKF"\s*,\s*("([^\\":,]+|\\.|::)*")\s*,/($1)[/g;
1969
1970       Again, this has some limitations - the magic string must not be encoded
1971       with character escapes, and the constructor arguments must be non-
1972       empty.
1973

RFC7159

1975       Since this module was written, Google has written a new JSON RFC, RFC
1976       7159 (and RFC7158). Unfortunately, this RFC breaks compatibility with
1977       both the original JSON specification on www.json.org and RFC4627.
1978
1979       As far as I can see, you can get partial compatibility when parsing by
1980       using "->allow_nonref". However, consider the security implications of
1981       doing so.
1982
1983       I haven't decided yet when to break compatibility with RFC4627 by
1984       default (and potentially leave applications insecure) and change the
1985       default to follow RFC7159, but application authors are well advised to
1986       call "->allow_nonref(0)" even if this is the current default, if they
1987       cannot handle non-reference values, in preparation for the day when the
1988       default will change.
1989

SECURITY CONSIDERATIONS

1991       JSON::XS and Cpanel::JSON::XS are not only fast. JSON is generally the
1992       most secure serializing format, because it is the only one besides
1993       Data::MessagePack, which does not deserialize objects per default. For
1994       all languages, not just perl.  The binary variant BSON (MongoDB) does
1995       more but is unsafe.
1996
1997       It is trivial for any attacker to create such serialized objects in
1998       JSON and trick perl into expanding them, thereby triggering certain
1999       methods. Watch <https://www.youtube.com/watch?v=Gzx6KlqiIZE> for an
2000       exploit demo for "CVE-2015-1592 SixApart MovableType Storable Perl Code
2001       Execution" for a deserializer which expands objects.  Deserializing
2002       even coderefs (methods, functions) or external data would be considered
2003       the most dangerous.
2004
2005       Security relevant overview of serializers regarding deserializing
2006       objects by default:
2007
2008                             Objects   Coderefs  External Data
2009
2010           Data::Dumper      YES       YES       YES
2011           Storable          YES       NO (def)  NO
2012           Sereal            YES       NO        NO
2013           YAML              YES       NO        NO
2014           B::C              YES       YES       YES
2015           B::Bytecode       YES       YES       YES
2016           BSON              YES       YES       NO
2017           JSON::SL          YES       NO        YES
2018           JSON              NO (def)  NO        NO
2019           Data::MessagePack NO        NO        NO
2020           XML               NO        NO        YES
2021
2022           Pickle            YES       YES       YES
2023           PHP Deserialize   YES       NO        NO
2024
2025       When you are using JSON in a protocol, talking to untrusted potentially
2026       hostile creatures requires relatively few measures.
2027
2028       First of all, your JSON decoder should be secure, that is, should not
2029       have any buffer overflows. Obviously, this module should ensure that.
2030
2031       Second, you need to avoid resource-starving attacks. That means you
2032       should limit the size of JSON texts you accept, or make sure then when
2033       your resources run out, that's just fine (e.g. by using a separate
2034       process that can crash safely). The size of a JSON text in octets or
2035       characters is usually a good indication of the size of the resources
2036       required to decode it into a Perl structure. While JSON::XS can check
2037       the size of the JSON text, it might be too late when you already have
2038       it in memory, so you might want to check the size before you accept the
2039       string.
2040
2041       Third, Cpanel::JSON::XS recurses using the C stack when decoding
2042       objects and arrays. The C stack is a limited resource: for instance, on
2043       my amd64 machine with 8MB of stack size I can decode around 180k nested
2044       arrays but only 14k nested JSON objects (due to perl itself recursing
2045       deeply on croak to free the temporary). If that is exceeded, the
2046       program crashes. To be conservative, the default nesting limit is set
2047       to 512. If your process has a smaller stack, you should adjust this
2048       setting accordingly with the "max_depth" method.
2049
2050       Also keep in mind that Cpanel::JSON::XS might leak contents of your
2051       Perl data structures in its error messages, so when you serialize
2052       sensitive information you might want to make sure that exceptions
2053       thrown by JSON::XS will not end up in front of untrusted eyes.
2054
2055       If you are using Cpanel::JSON::XS to return packets to consumption by
2056       JavaScript scripts in a browser you should have a look at
2057       <http://blog.archive.jpsykes.com/47/practical-csrf-and-json-security/>
2058       to see whether you are vulnerable to some common attack vectors (which
2059       really are browser design bugs, but it is still you who will have to
2060       deal with it, as major browser developers care only for features, not
2061       about getting security right). You might also want to also look at
2062       Mojo::JSON special escape rules to prevent from XSS attacks.
2063

"OLD" VS. "NEW" JSON (RFC 4627 VS. RFC 7159)

2065       TL;DR: Due to security concerns, Cpanel::JSON::XS will not allow scalar
2066       data in JSON texts by default - you need to create your own
2067       Cpanel::JSON::XS object and enable "allow_nonref":
2068
2069          my $json = JSON::XS->new->allow_nonref;
2070
2071          $text = $json->encode ($data);
2072          $data = $json->decode ($text);
2073
2074       The long version: JSON being an important and supposedly stable format,
2075       the IETF standardized it as RFC 4627 in 2006. Unfortunately the
2076       inventor of JSON Douglas Crockford unilaterally changed the definition
2077       of JSON in javascript. Rather than create a fork, the IETF decided to
2078       standardize the new syntax (apparently, so I as told, without finding
2079       it very amusing).
2080
2081       The biggest difference between the original JSON and the new JSON is
2082       that the new JSON supports scalars (anything other than arrays and
2083       objects) at the top-level of a JSON text. While this is strictly
2084       backwards compatible to older versions, it breaks a number of protocols
2085       that relied on sending JSON back-to-back, and is a minor security
2086       concern.
2087
2088       For example, imagine you have two banks communicating, and on one side,
2089       the JSON coder gets upgraded. Two messages, such as 10 and 1000 might
2090       then be confused to mean 101000, something that couldn't happen in the
2091       original JSON, because neither of these messages would be valid JSON.
2092
2093       If one side accepts these messages, then an upgrade in the coder on
2094       either side could result in this becoming exploitable.
2095
2096       This module has always allowed these messages as an optional extension,
2097       by default disabled. The security concerns are the reason why the
2098       default is still disabled, but future versions might/will likely
2099       upgrade to the newer RFC as default format, so you are advised to check
2100       your implementation and/or override the default with "->allow_nonref
2101       (0)" to ensure that future versions are safe.
2102

THREADS

2104       Cpanel::JSON::XS has proper ithreads support, unlike JSON::XS. If you
2105       encounter any bugs with thread support please report them.
2106
2107       From Version 4.00 - 4.19 you couldn't encode true with threads::shared
2108       magic.
2109

BUGS

2111       While the goal of the Cpanel::JSON::XS module is to be correct, that
2112       unfortunately does not mean it's bug-free, only that the author thinks
2113       its design is bug-free. If you keep reporting bugs and tests they will
2114       be fixed swiftly, though.
2115
2116       Since the JSON::XS author refuses to use a public bugtracker and
2117       prefers private emails, we use the tracker at github, so you might want
2118       to report any issues twice. Once in private to MLEHMANN to be fixed in
2119       JSON::XS and one to our the public tracker. Issues fixed by JSON::XS
2120       with a new release will also be backported to Cpanel::JSON::XS and
2121       5.6.2, as long as cPanel relies on 5.6.2 and Cpanel::JSON::XS as our
2122       serializer of choice.
2123
2124       <https://github.com/rurban/Cpanel-JSON-XS/issues>
2125

LICENSE

2127       This module is available under the same licences as perl, the Artistic
2128       license and the GPL.
2129

SEE ALSO

2131       The cpanel_json_xs command line utility for quick experiments.
2132
2133       JSON, JSON::XS, JSON::MaybeXS, Mojo::JSON, Mojo::JSON::MaybeXS,
2134       JSON::SL, JSON::DWIW, JSON::YAJL,  JSON::Any, Test::JSON,
2135       Locale::Wolowitz, <https://metacpan.org/search?q=JSON>
2136
2137       <https://tools.ietf.org/html/rfc7159>
2138
2139       <https://tools.ietf.org/html/rfc4627>
2140

AUTHOR

2142       Reini Urban <rurban@cpan.org>
2143
2144       Marc Lehmann <schmorp@schmorp.de>, http://home.schmorp.de/
2145

MAINTAINER

2147       Reini Urban <rurban@cpan.org>
2148
2149
2150
2151perl v5.32.0                      2020-10-02                             XS(3)
Impressum