summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/site/lib/Cpanel/JSON/XS.pm
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl/site/lib/Cpanel/JSON/XS.pm')
-rwxr-xr-xMaster/tlpkg/tlperl/site/lib/Cpanel/JSON/XS.pm2278
1 files changed, 2278 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl/site/lib/Cpanel/JSON/XS.pm b/Master/tlpkg/tlperl/site/lib/Cpanel/JSON/XS.pm
new file mode 100755
index 00000000000..be1d482bf05
--- /dev/null
+++ b/Master/tlpkg/tlperl/site/lib/Cpanel/JSON/XS.pm
@@ -0,0 +1,2278 @@
+package Cpanel::JSON::XS;
+our $VERSION = '4.01';
+our $XS_VERSION = $VERSION;
+# $VERSION = eval $VERSION;
+
+=pod
+
+=head1 NAME
+
+Cpanel::JSON::XS - cPanel fork of JSON::XS, fast and correct serializing
+
+=head1 SYNOPSIS
+
+ use Cpanel::JSON::XS;
+
+ # exported functions, they croak on error
+ # and expect/generate UTF-8
+
+ $utf8_encoded_json_text = encode_json $perl_hash_or_arrayref;
+ $perl_hash_or_arrayref = decode_json $utf8_encoded_json_text;
+
+ # OO-interface
+
+ $coder = Cpanel::JSON::XS->new->ascii->pretty->allow_nonref;
+ $pretty_printed_unencoded = $coder->encode ($perl_scalar);
+ $perl_scalar = $coder->decode ($unicode_json_text);
+
+ # Note that 5.6 misses most smart utf8 and encoding functionalities
+ # of newer releases.
+
+ # Note that L<JSON::MaybeXS> will automatically use Cpanel::JSON::XS
+ # if available, at virtually no speed overhead either, so you should
+ # be able to just:
+
+ use JSON::MaybeXS;
+
+ # and do the same things, except that you have a pure-perl fallback now.
+
+=head1 DESCRIPTION
+
+This module converts Perl data structures to JSON and vice versa. Its
+primary goal is to be I<correct> and its secondary goal is to be
+I<fast>. To reach the latter goal it was written in C.
+
+As this is the n-th-something JSON module on CPAN, what was the reason
+to write yet another JSON module? While it seems there are many JSON
+modules, none of them correctly handle all corner cases, and in most cases
+their maintainers are unresponsive, gone missing, or not listening to bug
+reports for other reasons.
+
+See below for the cPanel fork.
+
+See MAPPING, below, on how Cpanel::JSON::XS maps perl values to JSON
+values and vice versa.
+
+=head2 FEATURES
+
+=over 4
+
+=item * correct Unicode handling
+
+This module knows how to handle Unicode with Perl version higher than 5.8.5,
+documents how and when it does so, and even documents what "correct" means.
+
+=item * round-trip integrity
+
+When you serialize a perl data structure using only data types supported
+by JSON and Perl, the deserialized data structure is identical on the Perl
+level. (e.g. the string "2.0" doesn't suddenly become "2" just because
+it looks like a number). There I<are> minor exceptions to this, read the
+MAPPING section below to learn about those.
+
+=item * strict checking of JSON correctness
+
+There is no guessing, no generating of illegal JSON texts by default,
+and only JSON is accepted as input by default. the latter is a security
+feature.
+
+=item * fast
+
+Compared to other JSON modules and other serializers such as Storable,
+this module usually compares favourably in terms of speed, too.
+
+=item * simple to use
+
+This module has both a simple functional interface as well as an object
+oriented interface.
+
+=item * reasonably versatile output formats
+
+You can choose between the most compact guaranteed-single-line format
+possible (nice for simple line-based protocols), a pure-ASCII format
+(for when your transport is not 8-bit clean, still supports the whole
+Unicode range), or a pretty-printed format (for when you want to read that
+stuff). Or you can combine those features in whatever way you like.
+
+=back
+
+=head2 cPanel fork
+
+Since the original author MLEHMANN has no public
+bugtracker, this cPanel fork sits now on github.
+
+src repo: L<https://github.com/rurban/Cpanel-JSON-XS>
+original: L<http://cvs.schmorp.de/JSON-XS/>
+
+RT: L<https://github.com/rurban/Cpanel-JSON-XS/issues>
+or L<https://rt.cpan.org/Public/Dist/Display.html?Queue=Cpanel-JSON-XS>
+
+B<Changes to JSON::XS>
+
+- stricter decode_json() as documented. non-refs are disallowed.
+ added a 2nd optional argument. decode() honors now allow_nonref.
+
+- fixed encode of numbers for dual-vars. Different string
+ representations are preserved, but numbers with temporary strings
+ which represent the same number are here treated as numbers, not
+ strings. Cpanel::JSON::XS is a bit slower, but preserves numeric
+ types better.
+
+- numbers ending with .0 stay numbers, are not converted to
+ integers. [#63] dual-vars which are represented as number not
+ integer (42+"bar" != 5.8.9) are now encoded as number (=> 42.0)
+ because internally it's now a NOK type. However !!1 which is
+ wrongly encoded in 5.8 as "1"/1.0 is still represented as integer.
+
+- different handling of inf/nan. Default now to null, optionally with
+ stringify_infnan() to "inf"/"nan". [#28, #32]
+
+- added C<binary> extension, non-JSON and non JSON parsable, allows
+ C<\xNN> and C<\NNN> sequences.
+
+- 5.6.2 support; sacrificing some utf8 features (assuming bytes
+ all-over), no multi-byte unicode characters with 5.6.
+
+- interop for true/false overloading. JSON::XS, JSON::PP and Mojo::JSON
+ representations for booleans are accepted and JSON::XS accepts
+ Cpanel::JSON::XS booleans [#13, #37]
+ Fixed overloading of booleans. Cpanel::JSON::XS::true stringifies again
+ to "1", not "true", analog to all other JSON modules.
+
+- native boolean mapping of yes and no to true and false, as in YAML::XS.
+ In perl C<!0> is yes, C<!1> is no.
+ The JSON value true maps to 1, false maps to 0. [#39]
+
+- support arbitrary stringification with encode, with convert_blessed
+ and allow_blessed.
+
+- ithread support. Cpanel::JSON::XS is thread-safe, JSON::XS not
+
+- is_bool can be called as method, JSON::XS::is_bool not.
+
+- performance optimizations for threaded Perls
+
+- relaxed mode, allowing many popular extensions
+
+- additional fixes for:
+
+ - [cpan #88061] AIX atof without USE_LONG_DOUBLE
+
+ - #10 unshare_hek crash
+
+ - #7, #29 avoid re-blessing where possible. It fails in JSON::XS for
+ READONLY values, i.e. restricted hashes.
+
+ - #41 overloading of booleans, use the object not the reference.
+
+ - #62 -Dusequadmath conversion and no SEGV.
+
+ - #72 parsing of values followed \0, like 1\0 does fail.
+
+ - #72 parsing of illegal unicode or non-unicode characters.
+
+ - #96 locale-insensitive numeric conversion
+
+- public maintenance and bugtracker
+
+- use ppport.h, sanify XS.xs comment styles, harness C coding style
+
+- common::sense is optional. When available it is not used in the
+ published production module, just during development and testing.
+
+- extended testsuite, passes all http://seriot.ch/parsing_json.html
+ tests. In fact it is the only know JSON decoder which does so,
+ while also being the fastest.
+
+- support many more options and methods from JSON::PP:
+ stringify_infnan, allow_unknown, allow_stringify, allow_barekey,
+ encode_stringify, allow_bignum, allow_singlequote, sort_by
+ (partially), escape_slash, convert_blessed, ... optional
+ decode_json(, allow_nonref) arg.
+ relaxed implements allow_dupkeys.
+
+- support all 5 unicode BOM's: UTF-8, UTF-16LE, UTF-16BE, UTF-32LE,
+ UTF-32BE, encoding internally to UTF-8.
+
+=cut
+
+our @ISA = qw(Exporter);
+our @EXPORT = qw(encode_json decode_json to_json from_json);
+
+sub to_json($@) {
+ if ($] >= 5.008) {
+ require Carp;
+ Carp::croak ("Cpanel::JSON::XS::to_json has been renamed to encode_json,".
+ " either downgrade to pre-2.0 versions of Cpanel::JSON::XS or".
+ " rename the call");
+ } else {
+ _to_json(@_);
+ }
+}
+
+sub from_json($@) {
+ if ($] >= 5.008) {
+ require Carp;
+ Carp::croak ("Cpanel::JSON::XS::from_json has been renamed to decode_json,".
+ " either downgrade to pre-2.0 versions of Cpanel::JSON::XS or".
+ " rename the call");
+ } else {
+ _from_json(@_);
+ }
+}
+
+use Exporter;
+use XSLoader;
+
+=head1 FUNCTIONAL INTERFACE
+
+The following convenience methods are provided by this module. They are
+exported by default:
+
+=over 4
+
+=item $json_text = encode_json $perl_scalar, [json_type]
+
+Converts the given Perl data structure to a UTF-8 encoded, binary string
+(that is, the string contains octets only). Croaks on error.
+
+This function call is functionally identical to:
+
+ $json_text = Cpanel::JSON::XS->new->utf8->encode ($perl_scalar)
+
+Except being faster.
+
+For the type argument see L<Cpanel::JSON::XS::Type>.
+
+=item $perl_scalar = decode_json $json_text [, $allow_nonref ]
+
+The opposite of C<encode_json>: expects an UTF-8 (binary) string of an
+json reference and tries to parse that as an UTF-8 encoded JSON text,
+returning the resulting reference. Croaks on error.
+
+This function call is functionally identical to:
+
+ $perl_scalar = Cpanel::JSON::XS->new->utf8->decode ($json_text)
+
+except being faster.
+
+Note that older decode_json versions in Cpanel::JSON::XS older than
+3.0116 and JSON::XS did not set allow_nonref but allowed them due to a
+bug in the decoder.
+
+If the new optional $allow_nonref argument is set and not false, the
+allow_nonref option will be set and the function will act is described
+as in the relaxed RFC 7159 allowing all values such as objects,
+arrays, strings, numbers, "null", "true", and "false".
+
+=item $is_boolean = Cpanel::JSON::XS::is_bool $scalar
+
+Returns true if the passed scalar represents either C<JSON::XS::true>
+or C<JSON::XS::false>, two constants that act like C<1> and C<0>,
+respectively and are used to represent JSON C<true> and C<false>
+values in Perl.
+
+See MAPPING, below, for more information on how JSON values are mapped
+to Perl.
+
+=back
+
+=head1 DEPRECATED FUNCTIONS
+
+=over
+
+=item from_json
+
+from_json has been renamed to decode_json
+
+=item to_json
+
+to_json has been renamed to encode_json
+
+=back
+
+
+=head1 A FEW NOTES ON UNICODE AND PERL
+
+Since this often leads to confusion, here are a few very clear words on
+how Unicode works in Perl, modulo bugs.
+
+=over 4
+
+=item 1. Perl strings can store characters with ordinal values > 255.
+
+This enables you to store Unicode characters as single characters in a
+Perl string - very natural.
+
+=item 2. Perl does I<not> associate an encoding with your strings.
+
+... until you force it to, e.g. when matching it against a regex, or
+printing the scalar to a file, in which case Perl either interprets
+your string as locale-encoded text, octets/binary, or as Unicode,
+depending on various settings. In no case is an encoding stored
+together with your data, it is I<use> that decides encoding, not any
+magical meta data.
+
+=item 3. The internal utf-8 flag has no meaning with regards to the
+encoding of your string.
+
+=item 4. A "Unicode String" is simply a string where each character
+can be validly interpreted as a Unicode code point.
+
+If you have UTF-8 encoded data, it is no longer a Unicode string, but
+a Unicode string encoded in UTF-8, giving you a binary string.
+
+=item 5. A string containing "high" (> 255) character values is I<not>
+a UTF-8 string.
+
+=item 6. Unicode noncharacters only warn, as in core.
+
+The 66 Unicode noncharacters U+FDD0..U+FDEF, and U+*FFFE, U+*FFFF just
+warn, see L<http://www.unicode.org/versions/corrigendum9.html>. But
+illegal surrogate pairs fail to parse.
+
+=item 7. Raw non-Unicode characters above U+10FFFF are disallowed.
+
+Raw non-Unicode characters outside the valid unicode range fail to
+parse, because "A string is a sequence of zero or more Unicode
+characters" RFC 7159 section 1 and "JSON text SHALL be encoded in
+Unicode RFC 7159 section 8.1. We use now the UTF8_DISALLOW_SUPER
+flag when parsing unicode.
+
+=back
+
+I hope this helps :)
+
+
+=head1 OBJECT-ORIENTED INTERFACE
+
+The object oriented interface lets you configure your own encoding or
+decoding style, within the limits of supported formats.
+
+=over 4
+
+=item $json = new Cpanel::JSON::XS
+
+Creates a new JSON object that can be used to de/encode JSON
+strings. All boolean flags described below are by default I<disabled>.
+
+The mutators for flags all return the JSON object again and thus calls can
+be chained:
+
+ my $json = Cpanel::JSON::XS->new->utf8->space_after->encode ({a => [1,2]})
+ => {"a": [1, 2]}
+
+=item $json = $json->ascii ([$enable])
+
+=item $enabled = $json->get_ascii
+
+If C<$enable> is true (or missing), then the C<encode> method will not
+generate characters outside the code range C<0..127> (which is ASCII). Any
+Unicode characters outside that range will be escaped using either a
+single C<\uXXXX> (BMP characters) or a double C<\uHHHH\uLLLLL> escape sequence,
+as per RFC4627. The resulting encoded JSON text can be treated as a native
+Unicode string, an ascii-encoded, latin1-encoded or UTF-8 encoded string,
+or any other superset of ASCII.
+
+If C<$enable> is false, then the C<encode> method will not escape Unicode
+characters unless required by the JSON syntax or other flags. This results
+in a faster and more compact format.
+
+See also the section I<ENCODING/CODESET FLAG NOTES> later in this
+document.
+
+The main use for this flag is to produce JSON texts that can be
+transmitted over a 7-bit channel, as the encoded JSON texts will not
+contain any 8 bit characters.
+
+ Cpanel::JSON::XS->new->ascii (1)->encode ([chr 0x10401])
+ => ["\ud801\udc01"]
+
+=item $json = $json->latin1 ([$enable])
+
+=item $enabled = $json->get_latin1
+
+If C<$enable> is true (or missing), then the C<encode> method will encode
+the resulting JSON text as latin1 (or ISO-8859-1), escaping any characters
+outside the code range C<0..255>. The resulting string can be treated as a
+latin1-encoded JSON text or a native Unicode string. The C<decode> method
+will not be affected in any way by this flag, as C<decode> by default
+expects Unicode, which is a strict superset of latin1.
+
+If C<$enable> is false, then the C<encode> method will not escape Unicode
+characters unless required by the JSON syntax or other flags.
+
+See also the section I<ENCODING/CODESET FLAG NOTES> later in this
+document.
+
+The main use for this flag is efficiently encoding binary data as JSON
+text, as most octets will not be escaped, resulting in a smaller encoded
+size. The disadvantage is that the resulting JSON text is encoded
+in latin1 (and must correctly be treated as such when storing and
+transferring), a rare encoding for JSON. It is therefore most useful when
+you want to store data structures known to contain binary data efficiently
+in files or databases, not when talking to other JSON encoders/decoders.
+
+ Cpanel::JSON::XS->new->latin1->encode (["\x{89}\x{abc}"]
+ => ["\x{89}\\u0abc"] # (perl syntax, U+abc escaped, U+89 not)
+
+
+=item $json = $json->binary ([$enable])
+
+=item $enabled = $json = $json->get_binary
+
+If the C<$enable> argument is true (or missing), then the C<encode>
+method will not try to detect an UTF-8 encoding in any JSON string, it
+will strictly interpret it as byte sequence. The result might contain
+new C<\xNN> sequences, which is B<unparsable JSON>. The C<decode>
+method forbids C<\uNNNN> sequences and accepts C<\xNN> and octal
+C<\NNN> sequences.
+
+There is also a special logic for perl 5.6 and utf8. 5.6 encodes any
+string to utf-8 automatically when seeing a codepoint >= C<0x80> and
+< C<0x100>. With the binary flag enabled decode the perl utf8 encoded
+string to the original byte encoding and encode this with C<\xNN>
+escapes. This will result to the same encodings as with newer
+perls. But note that binary multi-byte codepoints with 5.6 will
+result in C<illegal unicode character in binary string> errors,
+unlike with newer perls.
+
+If C<$enable> is false, then the C<encode> method will smartly try to
+detect Unicode characters unless required by the JSON syntax or other
+flags and hex and octal sequences are forbidden.
+
+See also the section I<ENCODING/CODESET FLAG NOTES> later in this
+document.
+
+The main use for this flag is to avoid the smart unicode detection and
+possible double encoding. The disadvantage is that the resulting JSON
+text is encoded in new C<\xNN> and in latin1 characters and must
+correctly be treated as such when storing and transferring, a rare
+encoding for JSON. It will produce non-readable JSON strings in the
+browser. It is therefore most useful when you want to store data
+structures known to contain binary data efficiently in files or
+databases, not when talking to other JSON encoders/decoders. The
+binary decoding method can also be used when an encoder produced a
+non-JSON conformant hex or octal encoding C<\xNN> or C<\NNN>.
+
+ Cpanel::JSON::XS->new->binary->encode (["\x{89}\x{abc}"])
+ 5.6: Error: malformed or illegal unicode character in binary string
+ >=5.8: ['\x89\xe0\xaa\xbc']
+
+ Cpanel::JSON::XS->new->binary->encode (["\x{89}\x{bc}"])
+ => ["\x89\xbc"]
+
+ Cpanel::JSON::XS->new->binary->decode (["\x89\ua001"])
+ Error: malformed or illegal unicode character in binary string
+
+ Cpanel::JSON::XS->new->decode (["\x89"])
+ Error: illegal hex character in non-binary string
+
+
+=item $json = $json->utf8 ([$enable])
+
+=item $enabled = $json->get_utf8
+
+If C<$enable> is true (or missing), then the C<encode> method will encode
+the JSON result into UTF-8, as required by many protocols, while the
+C<decode> method expects to be handled an UTF-8-encoded string. Please
+note that UTF-8-encoded strings do not contain any characters outside the
+range C<0..255>, they are thus useful for bytewise/binary I/O. In future
+versions, enabling this option might enable autodetection of the UTF-16
+and UTF-32 encoding families, as described in RFC4627.
+
+If C<$enable> is false, then the C<encode> method will return the JSON
+string as a (non-encoded) Unicode string, while C<decode> expects thus a
+Unicode string. Any decoding or encoding (e.g. to UTF-8 or UTF-16) needs
+to be done yourself, e.g. using the Encode module.
+
+See also the section I<ENCODING/CODESET FLAG NOTES> later in this
+document.
+
+Example, output UTF-16BE-encoded JSON:
+
+ use Encode;
+ $jsontext = encode "UTF-16BE", Cpanel::JSON::XS->new->encode ($object);
+
+Example, decode UTF-32LE-encoded JSON:
+
+ use Encode;
+ $object = Cpanel::JSON::XS->new->decode (decode "UTF-32LE", $jsontext);
+
+=item $json = $json->pretty ([$enable])
+
+This enables (or disables) all of the C<indent>, C<space_before> and
+C<space_after> (and in the future possibly more) flags in one call to
+generate the most readable (or most compact) form possible.
+
+Example, pretty-print some simple structure:
+
+ my $json = Cpanel::JSON::XS->new->pretty(1)->encode ({a => [1,2]})
+ =>
+ {
+ "a" : [
+ 1,
+ 2
+ ]
+ }
+
+
+=item $json = $json->indent ([$enable])
+
+=item $enabled = $json->get_indent
+
+If C<$enable> is true (or missing), then the C<encode> method will use
+a multiline format as output, putting every array member or
+object/hash key-value pair into its own line, indenting them properly.
+
+If C<$enable> is false, no newlines or indenting will be produced, and the
+resulting JSON text is guaranteed not to contain any C<newlines>.
+
+This setting has no effect when decoding JSON texts.
+
+
+=item $json = $json->space_before ([$enable])
+
+=item $enabled = $json->get_space_before
+
+If C<$enable> is true (or missing), then the C<encode> method will add an extra
+optional space before the C<:> separating keys from values in JSON objects.
+
+If C<$enable> is false, then the C<encode> method will not add any extra
+space at those places.
+
+This setting has no effect when decoding JSON texts. You will also
+most likely combine this setting with C<space_after>.
+
+Example, space_before enabled, space_after and indent disabled:
+
+ {"key" :"value"}
+
+=item $json = $json->space_after ([$enable])
+
+=item $enabled = $json->get_space_after
+
+If C<$enable> is true (or missing), then the C<encode> method will add
+an extra optional space after the C<:> separating keys from values in
+JSON objects and extra whitespace after the C<,> separating key-value
+pairs and array members.
+
+If C<$enable> is false, then the C<encode> method will not add any extra
+space at those places.
+
+This setting has no effect when decoding JSON texts.
+
+Example, space_before and indent disabled, space_after enabled:
+
+ {"key": "value"}
+
+=item $json = $json->relaxed ([$enable])
+
+=item $enabled = $json->get_relaxed
+
+If C<$enable> is true (or missing), then C<decode> will accept some
+extensions to normal JSON syntax (see below). C<encode> will not be
+affected in anyway. I<Be aware that this option makes you accept invalid
+JSON texts as if they were valid!>. I suggest only to use this option to
+parse application-specific files written by humans (configuration files,
+resource files etc.)
+
+If C<$enable> is false (the default), then C<decode> will only accept
+valid JSON texts.
+
+Currently accepted extensions are:
+
+=over 4
+
+=item * list items can have an end-comma
+
+JSON I<separates> array elements and key-value pairs with commas. This
+can be annoying if you write JSON texts manually and want to be able to
+quickly append elements, so this extension accepts comma at the end of
+such items not just between them:
+
+ [
+ 1,
+ 2, <- this comma not normally allowed
+ ]
+ {
+ "k1": "v1",
+ "k2": "v2", <- this comma not normally allowed
+ }
+
+=item * shell-style '#'-comments
+
+Whenever JSON allows whitespace, shell-style comments are additionally
+allowed. They are terminated by the first carriage-return or line-feed
+character, after which more white-space and comments are allowed.
+
+ [
+ 1, # this comment not allowed in JSON
+ # neither this one...
+ ]
+
+=item * literal ASCII TAB characters in strings
+
+Literal ASCII TAB characters are now allowed in strings (and treated as
+C<\t>) in relaxed mode. Despite JSON mandates, that TAB character is
+substituted for "\t" sequence.
+
+ [
+ "Hello\tWorld",
+ "Hello<TAB>World", # literal <TAB> would not normally be allowed
+ ]
+
+=item * allow_singlequote
+
+Single quotes are accepted instead of double quotes. See the
+L</allow_singlequote> option.
+
+ { "foo":'bar' }
+ { 'foo':"bar" }
+ { 'foo':'bar' }
+
+=item * allow_barekey
+
+Accept unquoted object keys instead of with mandatory double quotes. See the
+L</allow_barekey> option.
+
+ { foo:"bar" }
+
+=item * duplicate keys
+
+With relaxed decoding of duplicate keys does not error and are silently accepted.
+See L<http://seriot.ch/parsing_json.php#24>:
+RFC 7159 section 4: "The names within an object should be unique."
+
+=back
+
+
+=item $json = $json->canonical ([$enable])
+
+=item $enabled = $json->get_canonical
+
+If C<$enable> is true (or missing), then the C<encode> method will
+output JSON objects by sorting their keys. This is adding a
+comparatively high overhead.
+
+If C<$enable> is false, then the C<encode> method will output key-value
+pairs in the order Perl stores them (which will likely change between runs
+of the same script, and can change even within the same run from 5.18
+onwards).
+
+This option is useful if you want the same data structure to be encoded as
+the same JSON text (given the same overall settings). If it is disabled,
+the same hash might be encoded differently even if contains the same data,
+as key-value pairs have no inherent ordering in Perl.
+
+This setting has no effect when decoding JSON texts.
+
+This setting has currently no effect on tied hashes.
+
+
+=item $json = $json->sort_by (undef, 0, 1 or a block)
+
+This currently only (un)sets the C<canonical> option, and ignores
+custom sort blocks.
+
+This setting has no effect when decoding JSON texts.
+
+This setting has currently no effect on tied hashes.
+
+
+=item $json = $json->escape_slash ([$enable])
+
+=item $enabled = $json->get_escape_slash
+
+According to the JSON Grammar, the I<forward slash> character (U+002F)
+C<"/"> need to be escaped. But by default strings are encoded without
+escaping slashes in all perl JSON encoders.
+
+If C<$enable> is true (or missing), then C<encode> will escape slashes,
+C<"\/">.
+
+This setting has no effect when decoding JSON texts.
+
+
+=item $json = $json->allow_singlequote ([$enable])
+
+=item $enabled = $json->get_allow_singlequote
+
+ $json = $json->allow_singlequote([$enable])
+
+If C<$enable> is true (or missing), then C<decode> will accept
+JSON strings quoted by single quotations that are invalid JSON
+format.
+
+ $json->allow_singlequote->decode({"foo":'bar'});
+ $json->allow_singlequote->decode({'foo':"bar"});
+ $json->allow_singlequote->decode({'foo':'bar'});
+
+This is also enabled with C<relaxed>.
+As same as the C<relaxed> option, this option may be used to parse
+application-specific files written by humans.
+
+
+=item $json = $json->allow_barekey ([$enable])
+
+=item $enabled = $json->get_allow_barekey
+
+ $json = $json->allow_barekey([$enable])
+
+If C<$enable> is true (or missing), then C<decode> will accept
+bare keys of JSON object that are invalid JSON format.
+
+Same as with the C<relaxed> option, this option may be used to parse
+application-specific files written by humans.
+
+ $json->allow_barekey->decode('{foo:"bar"}');
+
+=item $json = $json->allow_bignum ([$enable])
+
+=item $enabled = $json->get_allow_bignum
+
+ $json = $json->allow_bignum([$enable])
+
+If C<$enable> is true (or missing), then C<decode> will convert
+the big integer Perl cannot handle as integer into a L<Math::BigInt>
+object and convert a floating number (any) into a L<Math::BigFloat>.
+
+On the contrary, C<encode> converts C<Math::BigInt> objects and
+C<Math::BigFloat> objects into JSON numbers with C<allow_blessed>
+enable.
+
+ $json->allow_nonref->allow_blessed->allow_bignum;
+ $bigfloat = $json->decode('2.000000000000000000000000001');
+ print $json->encode($bigfloat);
+ # => 2.000000000000000000000000001
+
+See L</MAPPING> about the normal conversion of JSON number.
+
+
+=item $json = $json->allow_bigint ([$enable])
+
+This option is obsolete and replaced by allow_bignum.
+
+
+=item $json = $json->allow_nonref ([$enable])
+
+=item $enabled = $json->get_allow_nonref
+
+If C<$enable> is true (or missing), then the C<encode> method can
+convert a non-reference into its corresponding string, number or null
+JSON value, which is an extension to RFC4627. Likewise, C<decode> will
+accept those JSON values instead of croaking.
+
+If C<$enable> is false, then the C<encode> method will croak if it isn't
+passed an arrayref or hashref, as JSON texts must either be an object
+or array. Likewise, C<decode> will croak if given something that is not a
+JSON object or array.
+
+Example, encode a Perl scalar as JSON value with enabled C<allow_nonref>,
+resulting in an invalid JSON text:
+
+ Cpanel::JSON::XS->new->allow_nonref->encode ("Hello, World!")
+ => "Hello, World!"
+
+=item $json = $json->allow_unknown ([$enable])
+
+=item $enabled = $json->get_allow_unknown
+
+If C<$enable> is true (or missing), then C<encode> will I<not> throw an
+exception when it encounters values it cannot represent in JSON (for
+example, filehandles) but instead will encode a JSON C<null> value. Note
+that blessed objects are not included here and are handled separately by
+c<allow_nonref>.
+
+If C<$enable> is false (the default), then C<encode> will throw an
+exception when it encounters anything it cannot encode as JSON.
+
+This option does not affect C<decode> in any way, and it is recommended to
+leave it off unless you know your communications partner.
+
+=item $json = $json->allow_stringify ([$enable])
+
+=item $enabled = $json->get_allow_stringify
+
+If C<$enable> is true (or missing), then C<encode> will stringify the
+non-object perl value or reference. Note that blessed objects are not
+included here and are handled separately by C<allow_blessed> and
+C<convert_blessed>. String references are stringified to the string
+value, other references as in perl.
+
+This option does not affect C<decode> in any way.
+
+This option is special to this module, it is not supported by other
+encoders. So it is not recommended to use it.
+
+=item $json = $json->allow_blessed ([$enable])
+
+=item $enabled = $json->get_allow_blessed
+
+If C<$enable> is true (or missing), then the C<encode> method will not
+barf when it encounters a blessed reference. Instead, the value of the
+B<convert_blessed> option will decide whether C<null> (C<convert_blessed>
+disabled or no C<TO_JSON> method found) or a representation of the
+object (C<convert_blessed> enabled and C<TO_JSON> method found) is being
+encoded. Has no effect on C<decode>.
+
+If C<$enable> is false (the default), then C<encode> will throw an
+exception when it encounters a blessed object.
+
+This setting has no effect on C<decode>.
+
+=item $json = $json->convert_blessed ([$enable])
+
+=item $enabled = $json->get_convert_blessed
+
+If C<$enable> is true (or missing), then C<encode>, upon encountering a
+blessed object, will check for the availability of the C<TO_JSON> method
+on the object's class. If found, it will be called in scalar context
+and the resulting scalar will be encoded instead of the object. If no
+C<TO_JSON> method is found, a stringification overload method is tried next.
+If both are not found, the value of C<allow_blessed> will decide what
+to do.
+
+The C<TO_JSON> method may safely call die if it wants. If C<TO_JSON>
+returns other blessed objects, those will be handled in the same
+way. C<TO_JSON> must take care of not causing an endless recursion cycle
+(== crash) in this case. The name of C<TO_JSON> was chosen because other
+methods called by the Perl core (== not by the user of the object) are
+usually in upper case letters and to avoid collisions with any C<to_json>
+function or method.
+
+If C<$enable> is false (the default), then C<encode> will not consider
+this type of conversion.
+
+This setting has no effect on C<decode>.
+
+=item $json = $json->allow_tags ([$enable])
+
+=item $enabled = $json->get_allow_tags
+
+See L<OBJECT SERIALIZATION> for details.
+
+If C<$enable> is true (or missing), then C<encode>, upon encountering a
+blessed object, will check for the availability of the C<FREEZE> method on
+the object's class. If found, it will be used to serialize the object into
+a nonstandard tagged JSON value (that JSON decoders cannot decode).
+
+It also causes C<decode> to parse such tagged JSON values and deserialize
+them via a call to the C<THAW> method.
+
+If C<$enable> is false (the default), then C<encode> will not consider
+this type of conversion, and tagged JSON values will cause a parse error
+in C<decode>, as if tags were not part of the grammar.
+
+=item $json = $json->filter_json_object ([$coderef->($hashref)])
+
+When C<$coderef> is specified, it will be called from C<decode> each
+time it decodes a JSON object. The only argument is a reference to the
+newly-created hash. If the code references returns a single scalar (which
+need not be a reference), this value (i.e. a copy of that scalar to avoid
+aliasing) is inserted into the deserialized data structure. If it returns
+an empty list (NOTE: I<not> C<undef>, which is a valid scalar), the
+original deserialized hash will be inserted. This setting can slow down
+decoding considerably.
+
+When C<$coderef> is omitted or undefined, any existing callback will
+be removed and C<decode> will not change the deserialized hash in any
+way.
+
+Example, convert all JSON objects into the integer 5:
+
+ my $js = Cpanel::JSON::XS->new->filter_json_object (sub { 5 });
+ # returns [5]
+ $js->decode ('[{}]')
+ # throw an exception because allow_nonref is not enabled
+ # so a lone 5 is not allowed.
+ $js->decode ('{"a":1, "b":2}');
+
+=item $json = $json->filter_json_single_key_object ($key [=> $coderef->($value)])
+
+Works remotely similar to C<filter_json_object>, but is only called for
+JSON objects having a single key named C<$key>.
+
+This C<$coderef> is called before the one specified via
+C<filter_json_object>, if any. It gets passed the single value in the JSON
+object. If it returns a single value, it will be inserted into the data
+structure. If it returns nothing (not even C<undef> but the empty list),
+the callback from C<filter_json_object> will be called next, as if no
+single-key callback were specified.
+
+If C<$coderef> is omitted or undefined, the corresponding callback will be
+disabled. There can only ever be one callback for a given key.
+
+As this callback gets called less often then the C<filter_json_object>
+one, decoding speed will not usually suffer as much. Therefore, single-key
+objects make excellent targets to serialize Perl objects into, especially
+as single-key JSON objects are as close to the type-tagged value concept
+as JSON gets (it's basically an ID/VALUE tuple). Of course, JSON does not
+support this in any way, so you need to make sure your data never looks
+like a serialized Perl hash.
+
+Typical names for the single object key are C<__class_whatever__>, or
+C<$__dollars_are_rarely_used__$> or C<}ugly_brace_placement>, or even
+things like C<__class_md5sum(classname)__>, to reduce the risk of clashing
+with real hashes.
+
+Example, decode JSON objects of the form C<< { "__widget__" => <id> } >>
+into the corresponding C<< $WIDGET{<id>} >> object:
+
+ # return whatever is in $WIDGET{5}:
+ Cpanel::JSON::XS
+ ->new
+ ->filter_json_single_key_object (__widget__ => sub {
+ $WIDGET{ $_[0] }
+ })
+ ->decode ('{"__widget__": 5')
+
+ # this can be used with a TO_JSON method in some "widget" class
+ # for serialization to json:
+ sub WidgetBase::TO_JSON {
+ my ($self) = @_;
+
+ unless ($self->{id}) {
+ $self->{id} = ..get..some..id..;
+ $WIDGET{$self->{id}} = $self;
+ }
+
+ { __widget__ => $self->{id} }
+ }
+
+=item $json = $json->shrink ([$enable])
+
+=item $enabled = $json->get_shrink
+
+Perl usually over-allocates memory a bit when allocating space for
+strings. This flag optionally resizes strings generated by either
+C<encode> or C<decode> to their minimum size possible. This can save
+memory when your JSON texts are either very very long or you have many
+short strings. It will also try to downgrade any strings to octet-form
+if possible: perl stores strings internally either in an encoding called
+UTF-X or in octet-form. The latter cannot store everything but uses less
+space in general (and some buggy Perl or C code might even rely on that
+internal representation being used).
+
+The actual definition of what shrink does might change in future versions,
+but it will always try to save space at the expense of time.
+
+If C<$enable> is true (or missing), the string returned by C<encode> will
+be shrunk-to-fit, while all strings generated by C<decode> will also be
+shrunk-to-fit.
+
+If C<$enable> is false, then the normal perl allocation algorithms are used.
+If you work with your data, then this is likely to be faster.
+
+In the future, this setting might control other things, such as converting
+strings that look like integers or floats into integers or floats
+internally (there is no difference on the Perl level), saving space.
+
+=item $json = $json->max_depth ([$maximum_nesting_depth])
+
+=item $max_depth = $json->get_max_depth
+
+Sets the maximum nesting level (default C<512>) accepted while encoding
+or decoding. If a higher nesting level is detected in JSON text or a Perl
+data structure, then the encoder and decoder will stop and croak at that
+point.
+
+Nesting level is defined by number of hash- or arrayrefs that the encoder
+needs to traverse to reach a given point or the number of C<{> or C<[>
+characters without their matching closing parenthesis crossed to reach a
+given character in a string.
+
+Setting the maximum depth to one disallows any nesting, so that ensures
+that the object is only a single hash/object or array.
+
+If no argument is given, the highest possible setting will be used, which
+is rarely useful.
+
+Note that nesting is implemented by recursion in C. The default value has
+been chosen to be as large as typical operating systems allow without
+crashing.
+
+See SECURITY CONSIDERATIONS, below, for more info on why this is useful.
+
+=item $json = $json->max_size ([$maximum_string_size])
+
+=item $max_size = $json->get_max_size
+
+Set the maximum length a JSON text may have (in bytes) where decoding is
+being attempted. The default is C<0>, meaning no limit. When C<decode>
+is called on a string that is longer then this many bytes, it will not
+attempt to decode the string but throw an exception. This setting has no
+effect on C<encode> (yet).
+
+If no argument is given, the limit check will be deactivated (same as when
+C<0> is specified).
+
+See L</SECURITY CONSIDERATIONS>, below, for more info on why this is useful.
+
+=item $json->stringify_infnan ([$infnan_mode = 1])
+
+=item $infnan_mode = $json->get_stringify_infnan
+
+Get or set how Cpanel::JSON::XS encodes C<inf>, C<-inf> or C<nan> for numeric
+values. Also qnan, snan or negative nan on some platforms.
+
+C<null>: infnan_mode = 0. Similar to most JSON modules in other languages.
+Always null.
+
+stringified: infnan_mode = 1. As in Mojo::JSON. Platform specific strings.
+Stringified via sprintf(%g), with double quotes.
+
+inf/nan: infnan_mode = 2. As in JSON::XS, and older releases.
+Passes through platform dependent values, invalid JSON. Stringified via
+sprintf(%g), but without double quotes.
+
+"inf/-inf/nan": infnan_mode = 3. Platform independent inf/nan/-inf
+strings. No QNAN/SNAN/negative NAN support, unified to "nan". Much
+easier to detect, but may conflict with valid strings.
+
+=item $json_text = $json->encode ($perl_scalar)
+
+Converts the given Perl data structure (a simple scalar or a reference
+to a hash or array) to its JSON representation. Simple scalars will be
+converted into JSON string or number sequences, while references to
+arrays become JSON arrays and references to hashes become JSON
+objects. Undefined Perl values (e.g. C<undef>) become JSON C<null>
+values. Neither C<true> nor C<false> values will be generated.
+
+=item $perl_scalar = $json->decode ($json_text)
+
+The opposite of C<encode>: expects a JSON text and tries to parse it,
+returning the resulting simple scalar or reference. Croaks on error.
+
+JSON numbers and strings become simple Perl scalars. JSON arrays become
+Perl arrayrefs and JSON objects become Perl hashrefs. C<true> becomes
+C<1>, C<false> becomes C<0> and C<null> becomes C<undef>.
+
+=item ($perl_scalar, $characters) = $json->decode_prefix ($json_text)
+
+This works like the C<decode> method, but instead of raising an exception
+when there is trailing garbage after the first JSON object, it will
+silently stop parsing there and return the number of characters consumed
+so far.
+
+This is useful if your JSON texts are not delimited by an outer protocol
+and you need to know where the JSON text ends.
+
+ Cpanel::JSON::XS->new->decode_prefix ("[1] the tail")
+ => ([1], 3)
+
+=item $json->to_json ($perl_hash_or_arrayref)
+
+Deprecated method for perl 5.8 and newer. Use L<encode_json> instead.
+
+=item $json->from_json ($utf8_encoded_json_text)
+
+Deprecated method for perl 5.8 and newer. Use L<decode_json> instead.
+
+=back
+
+
+=head1 INCREMENTAL PARSING
+
+In some cases, there is the need for incremental parsing of JSON
+texts. While this module always has to keep both JSON text and resulting
+Perl data structure in memory at one time, it does allow you to parse a
+JSON stream incrementally. It does so by accumulating text until it has
+a full JSON object, which it then can decode. This process is similar to
+using C<decode_prefix> to see if a full JSON object is available, but
+is much more efficient (and can be implemented with a minimum of method
+calls).
+
+Cpanel::JSON::XS will only attempt to parse the JSON text once it is
+sure it has enough text to get a decisive result, using a very simple
+but truly incremental parser. This means that it sometimes won't stop
+as early as the full parser, for example, it doesn't detect mismatched
+parentheses. The only thing it guarantees is that it starts decoding
+as soon as a syntactically valid JSON text has been seen. This means
+you need to set resource limits (e.g. C<max_size>) to ensure the
+parser will stop parsing in the presence if syntax errors.
+
+The following methods implement this incremental parser.
+
+=over 4
+
+=item [void, scalar or list context] = $json->incr_parse ([$string])
+
+This is the central parsing function. It can both append new text and
+extract objects from the stream accumulated so far (both of these
+functions are optional).
+
+If C<$string> is given, then this string is appended to the already
+existing JSON fragment stored in the C<$json> object.
+
+After that, if the function is called in void context, it will simply
+return without doing anything further. This can be used to add more text
+in as many chunks as you want.
+
+If the method is called in scalar context, then it will try to extract
+exactly I<one> JSON object. If that is successful, it will return this
+object, otherwise it will return C<undef>. If there is a parse error,
+this method will croak just as C<decode> would do (one can then use
+C<incr_skip> to skip the erroneous part). This is the most common way of
+using the method.
+
+And finally, in list context, it will try to extract as many objects
+from the stream as it can find and return them, or the empty list
+otherwise. For this to work, there must be no separators between the JSON
+objects or arrays, instead they must be concatenated back-to-back. If
+an error occurs, an exception will be raised as in the scalar context
+case. Note that in this case, any previously-parsed JSON texts will be
+lost.
+
+Example: Parse some JSON arrays/objects in a given string and return
+them.
+
+ my @objs = Cpanel::JSON::XS->new->incr_parse ("[5][7][1,2]");
+
+=item $lvalue_string = $json->incr_text (>5.8 only)
+
+This method returns the currently stored JSON fragment as an lvalue, that
+is, you can manipulate it. This I<only> works when a preceding call to
+C<incr_parse> in I<scalar context> successfully returned an object, and
+2. only with Perl >= 5.8
+
+Under all other circumstances you must not call this function (I mean
+it. although in simple tests it might actually work, it I<will> fail
+under real world conditions). As a special exception, you can also
+call this method before having parsed anything.
+
+This function is useful in two cases: a) finding the trailing text after a
+JSON object or b) parsing multiple JSON objects separated by non-JSON text
+(such as commas).
+
+=item $json->incr_skip
+
+This will reset the state of the incremental parser and will remove
+the parsed text from the input buffer so far. This is useful after
+C<incr_parse> died, in which case the input buffer and incremental parser
+state is left unchanged, to skip the text parsed so far and to reset the
+parse state.
+
+The difference to C<incr_reset> is that only text until the parse error
+occurred is removed.
+
+=item $json->incr_reset
+
+This completely resets the incremental parser, that is, after this call,
+it will be as if the parser had never parsed anything.
+
+This is useful if you want to repeatedly parse JSON objects and want to
+ignore any trailing data, which means you have to reset the parser after
+each successful decode.
+
+=back
+
+=head2 LIMITATIONS
+
+All options that affect decoding are supported, except
+C<allow_nonref>. The reason for this is that it cannot be made to work
+sensibly: JSON objects and arrays are self-delimited, i.e. you can
+concatenate them back to back and still decode them perfectly. This
+does not hold true for JSON numbers, however.
+
+For example, is the string C<1> a single JSON number, or is it simply
+the start of C<12>? Or is C<12> a single JSON number, or the
+concatenation of C<1> and C<2>? In neither case you can tell, and this
+is why Cpanel::JSON::XS takes the conservative route and disallows
+this case.
+
+=head2 EXAMPLES
+
+Some examples will make all this clearer. First, a simple example that
+works similarly to C<decode_prefix>: We want to decode the JSON object at
+the start of a string and identify the portion after the JSON object:
+
+ my $text = "[1,2,3] hello";
+
+ my $json = new Cpanel::JSON::XS;
+
+ my $obj = $json->incr_parse ($text)
+ or die "expected JSON object or array at beginning of string";
+
+ my $tail = $json->incr_text;
+ # $tail now contains " hello"
+
+Easy, isn't it?
+
+Now for a more complicated example: Imagine a hypothetical protocol where
+you read some requests from a TCP stream, and each request is a JSON
+array, without any separation between them (in fact, it is often useful to
+use newlines as "separators", as these get interpreted as whitespace at
+the start of the JSON text, which makes it possible to test said protocol
+with C<telnet>...).
+
+Here is how you'd do it (it is trivial to write this in an event-based
+manner):
+
+ my $json = new Cpanel::JSON::XS;
+
+ # read some data from the socket
+ while (sysread $socket, my $buf, 4096) {
+
+ # split and decode as many requests as possible
+ for my $request ($json->incr_parse ($buf)) {
+ # act on the $request
+ }
+ }
+
+Another complicated example: Assume you have a string with JSON objects
+or arrays, all separated by (optional) comma characters (e.g. C<[1],[2],
+[3]>). To parse them, we have to skip the commas between the JSON texts,
+and here is where the lvalue-ness of C<incr_text> comes in useful:
+
+ my $text = "[1],[2], [3]";
+ my $json = new Cpanel::JSON::XS;
+
+ # void context, so no parsing done
+ $json->incr_parse ($text);
+
+ # now extract as many objects as possible. note the
+ # use of scalar context so incr_text can be called.
+ while (my $obj = $json->incr_parse) {
+ # do something with $obj
+
+ # now skip the optional comma
+ $json->incr_text =~ s/^ \s* , //x;
+ }
+
+Now lets go for a very complex example: Assume that you have a gigantic
+JSON array-of-objects, many gigabytes in size, and you want to parse it,
+but you cannot load it into memory fully (this has actually happened in
+the real world :).
+
+Well, you lost, you have to implement your own JSON parser. But
+Cpanel::JSON::XS can still help you: You implement a (very simple)
+array parser and let JSON decode the array elements, which are all
+full JSON objects on their own (this wouldn't work if the array
+elements could be JSON numbers, for example):
+
+ my $json = new Cpanel::JSON::XS;
+
+ # open the monster
+ open my $fh, "<bigfile.json"
+ or die "bigfile: $!";
+
+ # first parse the initial "["
+ for (;;) {
+ sysread $fh, my $buf, 65536
+ or die "read error: $!";
+ $json->incr_parse ($buf); # void context, so no parsing
+
+ # Exit the loop once we found and removed(!) the initial "[".
+ # In essence, we are (ab-)using the $json object as a simple scalar
+ # we append data to.
+ last if $json->incr_text =~ s/^ \s* \[ //x;
+ }
+
+ # now we have the skipped the initial "[", so continue
+ # parsing all the elements.
+ for (;;) {
+ # in this loop we read data until we got a single JSON object
+ for (;;) {
+ if (my $obj = $json->incr_parse) {
+ # do something with $obj
+ last;
+ }
+
+ # add more data
+ sysread $fh, my $buf, 65536
+ or die "read error: $!";
+ $json->incr_parse ($buf); # void context, so no parsing
+ }
+
+ # in this loop we read data until we either found and parsed the
+ # separating "," between elements, or the final "]"
+ for (;;) {
+ # first skip whitespace
+ $json->incr_text =~ s/^\s*//;
+
+ # if we find "]", we are done
+ if ($json->incr_text =~ s/^\]//) {
+ print "finished.\n";
+ exit;
+ }
+
+ # if we find ",", we can continue with the next element
+ if ($json->incr_text =~ s/^,//) {
+ last;
+ }
+
+ # if we find anything else, we have a parse error!
+ if (length $json->incr_text) {
+ die "parse error near ", $json->incr_text;
+ }
+
+ # else add more data
+ sysread $fh, my $buf, 65536
+ or die "read error: $!";
+ $json->incr_parse ($buf); # void context, so no parsing
+ }
+
+This is a complex example, but most of the complexity comes from the fact
+that we are trying to be correct (bear with me if I am wrong, I never ran
+the above example :).
+
+=head1 BOM
+
+Detect all unicode B<Byte Order Marks> on decode.
+Which are UTF-8, UTF-16LE, UTF-16BE, UTF-32LE and UTF-32BE.
+
+B<Warning>: With perls older than 5.20 you need load the Encode module
+before loading a multibyte BOM, i.e. >= UTF-16. Otherwise an error is
+thrown. This is an implementation limitation and might get fixed later.
+
+See L<https://tools.ietf.org/html/rfc7159#section-8.1>
+I<"JSON text SHALL be encoded in UTF-8, UTF-16, or UTF-32.">
+
+I<"Implementations MUST NOT add a byte order mark to the beginning of a
+JSON text", "implementations (...) MAY ignore the presence of a byte
+order mark rather than treating it as an error".>
+
+See also L<http://www.unicode.org/faq/utf_bom.html#BOM>.
+
+Beware that Cpanel::JSON::XS is currently the only JSON module which
+does accept and decode a BOM.
+
+The latest JSON spec
+L<https://www.greenbytes.de/tech/webdav/rfc8259.html#character.encoding>
+forbid the usage of UTF-16 or UTF-32, the character encoding is UTF-8.
+Thus in subsequent updates BOM's of UTF-16 or UTF-32 will throw an error.
+
+=head1 MAPPING
+
+This section describes how Cpanel::JSON::XS maps Perl values to JSON
+values and vice versa. These mappings are designed to "do the right
+thing" in most circumstances automatically, preserving round-tripping
+characteristics (what you put in comes out as something equivalent).
+
+For the more enlightened: note that in the following descriptions,
+lowercase I<perl> refers to the Perl interpreter, while uppercase I<Perl>
+refers to the abstract Perl language itself.
+
+
+=head2 JSON -> PERL
+
+=over 4
+
+=item object
+
+A JSON object becomes a reference to a hash in Perl. No ordering of object
+keys is preserved (JSON does not preserve object key ordering itself).
+
+=item array
+
+A JSON array becomes a reference to an array in Perl.
+
+=item string
+
+A JSON string becomes a string scalar in Perl - Unicode codepoints in JSON
+are represented by the same codepoints in the Perl string, so no manual
+decoding is necessary.
+
+=item number
+
+A JSON number becomes either an integer, numeric (floating point) or
+string scalar in perl, depending on its range and any fractional parts. On
+the Perl level, there is no difference between those as Perl handles all
+the conversion details, but an integer may take slightly less memory and
+might represent more values exactly than floating point numbers.
+
+If the number consists of digits only, Cpanel::JSON::XS will try to
+represent it as an integer value. If that fails, it will try to
+represent it as a numeric (floating point) value if that is possible
+without loss of precision. Otherwise it will preserve the number as a
+string value (in which case you lose roundtripping ability, as the
+JSON number will be re-encoded to a JSON string).
+
+Numbers containing a fractional or exponential part will always be
+represented as numeric (floating point) values, possibly at a loss of
+precision (in which case you might lose perfect roundtripping ability, but
+the JSON number will still be re-encoded as a JSON number).
+
+Note that precision is not accuracy - binary floating point values
+cannot represent most decimal fractions exactly, and when converting
+from and to floating point, C<Cpanel::JSON::XS> only guarantees precision
+up to but not including the least significant bit.
+
+=item true, false
+
+These JSON atoms become C<Cpanel::JSON::XS::true> and
+C<Cpanel::JSON::XS::false>, respectively. They are C<JSON::PP::Boolean>
+objects and are overloaded to act almost exactly like the numbers C<1>
+and C<0>. You can check whether a scalar is a JSON boolean by using
+the C<Cpanel::JSON::XS::is_bool> function.
+
+The other round, from perl to JSON, C<!0> which is represented as
+C<yes> becomes C<true>, and C<!1> which is represented as
+C<no> becomes C<false>.
+
+Via L<Cpanel::JSON::XS::Type> you can now even force negation in C<encode>,
+without overloading of C<!>:
+
+ my $false = Cpanel::JSON::XS::false;
+ print($json->encode([!$false], [JSON_TYPE_BOOL]));
+ => [true]
+
+=item null
+
+A JSON null atom becomes C<undef> in Perl.
+
+=item shell-style comments (C<< # I<text> >>)
+
+As a nonstandard extension to the JSON syntax that is enabled by the
+C<relaxed> setting, shell-style comments are allowed. They can start
+anywhere outside strings and go till the end of the line.
+
+=item tagged values (C<< (I<tag>)I<value> >>).
+
+Another nonstandard extension to the JSON syntax, enabled with the
+C<allow_tags> setting, are tagged values. In this implementation, the
+I<tag> must be a perl package/class name encoded as a JSON string, and the
+I<value> must be a JSON array encoding optional constructor arguments.
+
+See L<OBJECT SERIALIZATION>, below, for details.
+
+=back
+
+
+=head2 PERL -> JSON
+
+The mapping from Perl to JSON is slightly more difficult, as Perl is a
+truly typeless language, so we can only guess which JSON type is meant by
+a Perl value.
+
+=over 4
+
+=item hash references
+
+Perl hash references become JSON objects. As there is no inherent ordering
+in hash keys (or JSON objects), they will usually be encoded in a
+pseudo-random order that can change between runs of the same program but
+stays generally the same within a single run of a program. Cpanel::JSON::XS can
+optionally sort the hash keys (determined by the I<canonical> flag), so
+the same datastructure will serialize to the same JSON text (given same
+settings and version of Cpanel::JSON::XS), but this incurs a runtime overhead
+and is only rarely useful, e.g. when you want to compare some JSON text
+against another for equality.
+
+=item array references
+
+Perl array references become JSON arrays.
+
+=item other references
+
+Other unblessed references are generally not allowed and will cause an
+exception to be thrown, except for references to the integers C<0> and
+C<1>, which get turned into C<false> and C<true> atoms in JSON.
+
+With the option C<allow_stringify>, you can ignore the exception and return
+the stringification of the perl value.
+
+With the option C<allow_unknown>, you can ignore the exception and
+return C<null> instead.
+
+ encode_json [\"x"] # => cannot encode reference to scalar 'SCALAR(0x..)'
+ # unless the scalar is 0 or 1
+ encode_json [\0, \1] # yields [false,true]
+
+ allow_stringify->encode_json [\"x"] # yields "x" unlike JSON::PP
+ allow_unknown->encode_json [\"x"] # yields null as in JSON::PP
+
+=item Cpanel::JSON::XS::true, Cpanel::JSON::XS::false
+
+These special values become JSON true and JSON false values,
+respectively. You can also use C<\1> and C<\0> or C<!0> and C<!1>
+directly if you want.
+
+ encode_json [Cpanel::JSON::XS::true, Cpanel::JSON::XS::true] # yields [false,true]
+ encode_json [!1, !0] # yields [false,true]
+
+=item blessed objects
+
+Blessed objects are not directly representable in JSON, but
+C<Cpanel::JSON::XS> allows various optional ways of handling
+objects. See L<OBJECT SERIALIZATION>, below, for details.
+
+See the C<allow_blessed> and C<convert_blessed> methods on various
+options on how to deal with this: basically, you can choose between
+throwing an exception, encoding the reference as if it weren't
+blessed, use the objects overloaded stringification method or provide
+your own serializer method.
+
+=item simple scalars
+
+Simple Perl scalars (any scalar that is not a reference) are the most
+difficult objects to encode: Cpanel::JSON::XS will encode undefined
+scalars or inf/nan as JSON C<null> values, scalars that have last been
+used in a string context before encoding as JSON strings, and anything
+else as number value:
+
+ # dump as number
+ encode_json [2] # yields [2]
+ encode_json [-3.0e17] # yields [-3e+17]
+ my $value = 5; encode_json [$value] # yields [5]
+
+ # used as string, but the two representations are for the same number
+ print $value;
+ encode_json [$value] # yields [5]
+
+ # used as different string (non-matching dual-var)
+ my $str = '0 but true';
+ my $num = 1 + $str;
+ encode_json [$num, $str] # yields [1,"0 but true"]
+
+ # undef becomes null
+ encode_json [undef] # yields [null]
+
+ # inf or nan becomes null, unless you answered
+ # "Do you want to handle inf/nan as strings" with yes
+ encode_json [9**9**9] # yields [null]
+
+You can force the type to be a JSON string by stringifying it:
+
+ my $x = 3.1; # some variable containing a number
+ "$x"; # stringified
+ $x .= ""; # another, more awkward way to stringify
+ print $x; # perl does it for you, too, quite often
+
+You can force the type to be a JSON number by numifying it:
+
+ my $x = "3"; # some variable containing a string
+ $x += 0; # numify it, ensuring it will be dumped as a number
+ $x *= 1; # same thing, the choice is yours.
+
+Note that numerical precision has the same meaning as under Perl (so
+binary to decimal conversion follows the same rules as in Perl, which
+can differ to other languages). Also, your perl interpreter might expose
+extensions to the floating point numbers of your platform, such as
+infinities or NaN's - these cannot be represented in JSON, and thus
+null is returned instead. Optionally you can configure it to stringify
+inf and nan values.
+
+=back
+
+=head2 OBJECT SERIALIZATION
+
+As JSON cannot directly represent Perl objects, you have to choose between
+a pure JSON representation (without the ability to deserialize the object
+automatically again), and a nonstandard extension to the JSON syntax,
+tagged values.
+
+=head3 SERIALIZATION
+
+What happens when C<Cpanel::JSON::XS> encounters a Perl object depends
+on the C<allow_blessed>, C<convert_blessed> and C<allow_tags>
+settings, which are used in this order:
+
+=over 4
+
+=item 1. C<allow_tags> is enabled and the object has a C<FREEZE> method.
+
+In this case, C<Cpanel::JSON::XS> uses the L<Types::Serialiser> object
+serialization protocol to create a tagged JSON value, using a nonstandard
+extension to the JSON syntax.
+
+This works by invoking the C<FREEZE> method on the object, with the first
+argument being the object to serialize, and the second argument being the
+constant string C<JSON> to distinguish it from other serializers.
+
+The C<FREEZE> method can return any number of values (i.e. zero or
+more). These values and the paclkage/classname of the object will then be
+encoded as a tagged JSON value in the following format:
+
+ ("classname")[FREEZE return values...]
+
+e.g.:
+
+ ("URI")["http://www.google.com/"]
+ ("MyDate")[2013,10,29]
+ ("ImageData::JPEG")["Z3...VlCg=="]
+
+For example, the hypothetical C<My::Object> C<FREEZE> method might use the
+objects C<type> and C<id> members to encode the object:
+
+ sub My::Object::FREEZE {
+ my ($self, $serializer) = @_;
+
+ ($self->{type}, $self->{id})
+ }
+
+=item 2. C<convert_blessed> is enabled and the object has a C<TO_JSON> method.
+
+In this case, the C<TO_JSON> method of the object is invoked in scalar
+context. It must return a single scalar that can be directly encoded into
+JSON. This scalar replaces the object in the JSON text.
+
+For example, the following C<TO_JSON> method will convert all L<URI>
+objects to JSON strings when serialized. The fact that these values
+originally were L<URI> objects is lost.
+
+ sub URI::TO_JSON {
+ my ($uri) = @_;
+ $uri->as_string
+ }
+
+=item 2. C<convert_blessed> is enabled and the object has a stringification overload.
+
+In this case, the overloaded C<""> method of the object is invoked in scalar
+context. It must return a single scalar that can be directly encoded into
+JSON. This scalar replaces the object in the JSON text.
+
+For example, the following C<""> method will convert all L<URI>
+objects to JSON strings when serialized. The fact that these values
+originally were L<URI> objects is lost.
+
+ package URI;
+ use overload '""' => sub { shift->as_string };
+
+=item 3. C<allow_blessed> is enabled.
+
+The object will be serialized as a JSON null value.
+
+=item 4. none of the above
+
+If none of the settings are enabled or the respective methods are missing,
+C<Cpanel::JSON::XS> throws an exception.
+
+=back
+
+=head3 DESERIALIZATION
+
+For deserialization there are only two cases to consider: either
+nonstandard tagging was used, in which case C<allow_tags> decides,
+or objects cannot be automatically be deserialized, in which
+case you can use postprocessing or the C<filter_json_object> or
+C<filter_json_single_key_object> callbacks to get some real objects our of
+your JSON.
+
+This section only considers the tagged value case: I a tagged JSON object
+is encountered during decoding and C<allow_tags> is disabled, a parse
+error will result (as if tagged values were not part of the grammar).
+
+If C<allow_tags> is enabled, C<Cpanel::JSON::XS> will look up the C<THAW> method
+of the package/classname used during serialization (it will not attempt
+to load the package as a Perl module). If there is no such method, the
+decoding will fail with an error.
+
+Otherwise, the C<THAW> method is invoked with the classname as first
+argument, the constant string C<JSON> as second argument, and all the
+values from the JSON array (the values originally returned by the
+C<FREEZE> method) as remaining arguments.
+
+The method must then return the object. While technically you can return
+any Perl scalar, you might have to enable the C<enable_nonref> setting to
+make that work in all cases, so better return an actual blessed reference.
+
+As an example, let's implement a C<THAW> function that regenerates the
+C<My::Object> from the C<FREEZE> example earlier:
+
+ sub My::Object::THAW {
+ my ($class, $serializer, $type, $id) = @_;
+
+ $class->new (type => $type, id => $id)
+ }
+
+See the L</SECURITY CONSIDERATIONS> section below. Allowing external
+json objects being deserialized to perl objects is usually a very bad
+idea.
+
+
+=head1 ENCODING/CODESET FLAG NOTES
+
+The interested reader might have seen a number of flags that signify
+encodings or codesets - C<utf8>, C<latin1>, C<binary> and
+C<ascii>. There seems to be some confusion on what these do, so here
+is a short comparison:
+
+C<utf8> controls whether the JSON text created by C<encode> (and expected
+by C<decode>) is UTF-8 encoded or not, while C<latin1> and C<ascii> only
+control whether C<encode> escapes character values outside their respective
+codeset range. Neither of these flags conflict with each other, although
+some combinations make less sense than others.
+
+Care has been taken to make all flags symmetrical with respect to
+C<encode> and C<decode>, that is, texts encoded with any combination of
+these flag values will be correctly decoded when the same flags are used
+- in general, if you use different flag settings while encoding vs. when
+decoding you likely have a bug somewhere.
+
+Below comes a verbose discussion of these flags. Note that a "codeset" is
+simply an abstract set of character-codepoint pairs, while an encoding
+takes those codepoint numbers and I<encodes> them, in our case into
+octets. Unicode is (among other things) a codeset, UTF-8 is an encoding,
+and ISO-8859-1 (= latin 1) and ASCII are both codesets I<and> encodings at
+the same time, which can be confusing.
+
+=over 4
+
+=item C<utf8> flag disabled
+
+When C<utf8> is disabled (the default), then C<encode>/C<decode> generate
+and expect Unicode strings, that is, characters with high ordinal Unicode
+values (> 255) will be encoded as such characters, and likewise such
+characters are decoded as-is, no changes to them will be done, except
+"(re-)interpreting" them as Unicode codepoints or Unicode characters,
+respectively (to Perl, these are the same thing in strings unless you do
+funny/weird/dumb stuff).
+
+This is useful when you want to do the encoding yourself (e.g. when you
+want to have UTF-16 encoded JSON texts) or when some other layer does
+the encoding for you (for example, when printing to a terminal using a
+filehandle that transparently encodes to UTF-8 you certainly do NOT want
+to UTF-8 encode your data first and have Perl encode it another time).
+
+=item C<utf8> flag enabled
+
+If the C<utf8>-flag is enabled, C<encode>/C<decode> will encode all
+characters using the corresponding UTF-8 multi-byte sequence, and will
+expect your input strings to be encoded as UTF-8, that is, no "character"
+of the input string must have any value > 255, as UTF-8 does not allow
+that.
+
+The C<utf8> flag therefore switches between two modes: disabled means you
+will get a Unicode string in Perl, enabled means you get an UTF-8 encoded
+octet/binary string in Perl.
+
+=item C<latin1>, C<binary> or C<ascii> flags enabled
+
+With C<latin1> (or C<ascii>) enabled, C<encode> will escape
+characters with ordinal values > 255 (> 127 with C<ascii>) and encode
+the remaining characters as specified by the C<utf8> flag.
+With C<binary> enabled, ordinal values > 255 are illegal.
+
+If C<utf8> is disabled, then the result is also correctly encoded in those
+character sets (as both are proper subsets of Unicode, meaning that a
+Unicode string with all character values < 256 is the same thing as a
+ISO-8859-1 string, and a Unicode string with all character values < 128 is
+the same thing as an ASCII string in Perl).
+
+If C<utf8> is enabled, you still get a correct UTF-8-encoded string,
+regardless of these flags, just some more characters will be escaped using
+C<\uXXXX> then before.
+
+Note that ISO-8859-1-I<encoded> strings are not compatible with UTF-8
+encoding, while ASCII-encoded strings are. That is because the ISO-8859-1
+encoding is NOT a subset of UTF-8 (despite the ISO-8859-1 I<codeset> being
+a subset of Unicode), while ASCII is.
+
+Surprisingly, C<decode> will ignore these flags and so treat all input
+values as governed by the C<utf8> flag. If it is disabled, this allows you
+to decode ISO-8859-1- and ASCII-encoded strings, as both strict subsets of
+Unicode. If it is enabled, you can correctly decode UTF-8 encoded strings.
+
+So neither C<latin1>, C<binary> nor C<ascii> are incompatible with the
+C<utf8> flag - they only govern when the JSON output engine escapes a
+character or not.
+
+The main use for C<latin1> or C<binary> is to relatively efficiently
+store binary data as JSON, at the expense of breaking compatibility
+with most JSON decoders.
+
+The main use for C<ascii> is to force the output to not contain characters
+with values > 127, which means you can interpret the resulting string
+as UTF-8, ISO-8859-1, ASCII, KOI8-R or most about any character set and
+8-bit-encoding, and still get the same data structure back. This is useful
+when your channel for JSON transfer is not 8-bit clean or the encoding
+might be mangled in between (e.g. in mail), and works because ASCII is a
+proper subset of most 8-bit and multibyte encodings in use in the world.
+
+=back
+
+
+=head2 JSON and ECMAscript
+
+JSON syntax is based on how literals are represented in javascript (the
+not-standardized predecessor of ECMAscript) which is presumably why it is
+called "JavaScript Object Notation".
+
+However, JSON is not a subset (and also not a superset of course) of
+ECMAscript (the standard) or javascript (whatever browsers actually
+implement).
+
+If you want to use javascript's C<eval> function to "parse" JSON, you
+might run into parse errors for valid JSON texts, or the resulting data
+structure might not be queryable:
+
+One of the problems is that U+2028 and U+2029 are valid characters inside
+JSON strings, but are not allowed in ECMAscript string literals, so the
+following Perl fragment will not output something that can be guaranteed
+to be parsable by javascript's C<eval>:
+
+ use Cpanel::JSON::XS;
+
+ print encode_json [chr 0x2028];
+
+The right fix for this is to use a proper JSON parser in your javascript
+programs, and not rely on C<eval> (see for example Douglas Crockford's
+F<json2.js> parser).
+
+If this is not an option, you can, as a stop-gap measure, simply encode to
+ASCII-only JSON:
+
+ use Cpanel::JSON::XS;
+
+ print Cpanel::JSON::XS->new->ascii->encode ([chr 0x2028]);
+
+Note that this will enlarge the resulting JSON text quite a bit if you
+have many non-ASCII characters. You might be tempted to run some regexes
+to only escape U+2028 and U+2029, e.g.:
+
+ # DO NOT USE THIS!
+ my $json = Cpanel::JSON::XS->new->utf8->encode ([chr 0x2028]);
+ $json =~ s/\xe2\x80\xa8/\\u2028/g; # escape U+2028
+ $json =~ s/\xe2\x80\xa9/\\u2029/g; # escape U+2029
+ print $json;
+
+Note that I<this is a bad idea>: the above only works for U+2028 and
+U+2029 and thus only for fully ECMAscript-compliant parsers. Many existing
+javascript implementations, however, have issues with other characters as
+well - using C<eval> naively simply I<will> cause problems.
+
+Another problem is that some javascript implementations reserve
+some property names for their own purposes (which probably makes
+them non-ECMAscript-compliant). For example, Iceweasel reserves the
+C<__proto__> property name for its own purposes.
+
+If that is a problem, you could parse try to filter the resulting JSON
+output for these property strings, e.g.:
+
+ $json =~ s/"__proto__"\s*:/"__proto__renamed":/g;
+
+This works because C<__proto__> is not valid outside of strings, so every
+occurrence of C<"__proto__"\s*:> must be a string used as property name.
+
+Unicode non-characters between U+FFFD and U+10FFFF are decoded either
+to the recommended U+FFFD REPLACEMENT CHARACTER (see Unicode PR #121:
+Recommended Practice for Replacement Characters), or in the binary or
+relaxed mode left as is, keeping the illegal non-characters as before.
+
+Raw non-Unicode characters outside the valid unicode range fail now to
+parse, because "A string is a sequence of zero or more Unicode
+characters" RFC 7159 section 1 and "JSON text SHALL be encoded in
+Unicode RFC 7159 section 8.1. We use now the UTF8_DISALLOW_SUPER
+flag when parsing unicode.
+
+If you know of other incompatibilities, please let me know.
+
+
+=head2 JSON and YAML
+
+You often hear that JSON is a subset of YAML. I<in general, there is
+no way to configure JSON::XS to output a data structure as valid YAML>
+that works in all cases. If you really must use Cpanel::JSON::XS to
+generate YAML, you should use this algorithm (subject to change in
+future versions):
+
+ my $to_yaml = Cpanel::JSON::XS->new->utf8->space_after (1);
+ my $yaml = $to_yaml->encode ($ref) . "\n";
+
+This will I<usually> generate JSON texts that also parse as valid
+YAML.
+
+
+=head2 SPEED
+
+It seems that JSON::XS is surprisingly fast, as shown in the following
+tables. They have been generated with the help of the C<eg/bench> program
+in the JSON::XS distribution, to make it easy to compare on your own
+system.
+
+JSON::XS is with L<Data::MessagePack> and L<Sereal> one of the fastest
+serializers, because JSON and JSON::XS do not support backrefs (no
+graph structures), only trees. Storable supports backrefs,
+i.e. graphs. Data::MessagePack encodes its data binary (as Storable)
+and supports only very simple subset of JSON.
+
+First comes a comparison between various modules using
+a very short single-line JSON string (also available at
+L<http://dist.schmorp.de/misc/json/short.json>).
+
+ {"method": "handleMessage", "params": ["user1",
+ "we were just talking"], "id": null, "array":[1,11,234,-5,1e5,1e7,
+ 1, 0]}
+
+It shows the number of encodes/decodes per second (JSON::XS uses
+the functional interface, while Cpanel::JSON::XS/2 uses the OO interface
+with pretty-printing and hash key sorting enabled, Cpanel::JSON::XS/3 enables
+shrink. JSON::DWIW/DS uses the deserialize function, while JSON::DWIW::FJ
+uses the from_json method). Higher is better:
+
+ module | encode | decode |
+ --------------|------------|------------|
+ JSON::DWIW/DS | 86302.551 | 102300.098 |
+ JSON::DWIW/FJ | 86302.551 | 75983.768 |
+ JSON::PP | 15827.562 | 6638.658 |
+ JSON::Syck | 63358.066 | 47662.545 |
+ JSON::XS | 511500.488 | 511500.488 |
+ JSON::XS/2 | 291271.111 | 388361.481 |
+ JSON::XS/3 | 361577.931 | 361577.931 |
+ Storable | 66788.280 | 265462.278 |
+ --------------+------------+------------+
+
+That is, JSON::XS is almost six times faster than JSON::DWIW on encoding,
+about five times faster on decoding, and over thirty to seventy times
+faster than JSON's pure perl implementation. It also compares favourably
+to Storable for small amounts of data.
+
+Using a longer test string (roughly 18KB, generated from Yahoo! Locals
+search API (L<http://dist.schmorp.de/misc/json/long.json>).
+
+ module | encode | decode |
+ --------------|------------|------------|
+ JSON::DWIW/DS | 1647.927 | 2673.916 |
+ JSON::DWIW/FJ | 1630.249 | 2596.128 |
+ JSON::PP | 400.640 | 62.311 |
+ JSON::Syck | 1481.040 | 1524.869 |
+ JSON::XS | 20661.596 | 9541.183 |
+ JSON::XS/2 | 10683.403 | 9416.938 |
+ JSON::XS/3 | 20661.596 | 9400.054 |
+ Storable | 19765.806 | 10000.725 |
+ --------------+------------+------------+
+
+Again, JSON::XS leads by far (except for Storable which non-surprisingly
+decodes a bit faster).
+
+On large strings containing lots of high Unicode characters, some modules
+(such as JSON::PC) seem to decode faster than JSON::XS, but the result
+will be broken due to missing (or wrong) Unicode handling. Others refuse
+to decode or encode properly, so it was impossible to prepare a fair
+comparison table for that case.
+
+For updated graphs see L<https://github.com/Sereal/Sereal/wiki/Sereal-Comparison-Graphs>
+
+
+=head1 INTEROP with JSON and JSON::XS and other JSON modules
+
+As long as you only serialize data that can be directly expressed in
+JSON, C<Cpanel::JSON::XS> is incapable of generating invalid JSON
+output (modulo bugs, but C<JSON::XS> has found more bugs in the
+official JSON testsuite (1) than the official JSON testsuite has found
+in C<JSON::XS> (0)).
+C<Cpanel::JSON::XS> is currently the only known JSON decoder which passes all
+L<http://seriot.ch/parsing_json.html> tests, while being the fastest also.
+
+When you have trouble decoding JSON generated by this module using other
+decoders, then it is very likely that you have an encoding mismatch or the
+other decoder is broken.
+
+When decoding, C<JSON::XS> is strict by default and will likely catch
+all errors. There are currently two settings that change this:
+C<relaxed> makes C<JSON::XS> accept (but not generate) some
+non-standard extensions, and C<allow_tags> or C<allow_blessed> will
+allow you to encode and decode Perl objects, at the cost of being
+totally insecure and not outputting valid JSON anymore.
+
+JSON-XS-3.01 broke interoperability with JSON-2.90 with booleans. See L<JSON>.
+
+Cpanel::JSON::XS needs to know the JSON and JSON::XS versions to be able work
+with those objects, especially when encoding a booleans like C<{"is_true":true}>.
+So you need to load these modules before.
+
+true/false overloading and boolean representations are supported.
+
+JSON::XS and JSON::PP representations are accepted and older JSON::XS
+accepts Cpanel::JSON::XS booleans. All JSON modules JSON, JSON, PP,
+JSON::XS, Cpanel::JSON::XS produce JSON::PP::Boolean objects, just
+Mojo and JSON::YAJL not. Mojo produces Mojo::JSON::_Bool and
+JSON::YAJL::Parser just an unblessed IV.
+
+Cpanel::JSON::XS accepts JSON::PP::Boolean and Mojo::JSON::_Bool
+objects as booleans.
+
+I cannot think of any reason to still use JSON::XS anymore.
+
+
+=head2 TAGGED VALUE SYNTAX AND STANDARD JSON EN/DECODERS
+
+When you use C<allow_tags> to use the extended (and also nonstandard
+and invalid) JSON syntax for serialized objects, and you still want to
+decode the generated serialize objects, you can run a regex to replace
+the tagged syntax by standard JSON arrays (it only works for "normal"
+package names without comma, newlines or single colons). First, the
+readable Perl version:
+
+ # if your FREEZE methods return no values, you need this replace first:
+ $json =~ s/\( \s* (" (?: [^\\":,]+|\\.|::)* ") \s* \) \s* \[\s*\]/[$1]/gx;
+
+ # this works for non-empty constructor arg lists:
+ $json =~ s/\( \s* (" (?: [^\\":,]+|\\.|::)* ") \s* \) \s* \[/[$1,/gx;
+
+And here is a less readable version that is easy to adapt to other
+languages:
+
+ $json =~ s/\(\s*("([^\\":,]+|\\.|::)*")\s*\)\s*\[/[$1,/g;
+
+Here is an ECMAScript version (same regex):
+
+ json = json.replace (/\(\s*("([^\\":,]+|\\.|::)*")\s*\)\s*\[/g, "[$1,");
+
+Since this syntax converts to standard JSON arrays, it might be hard to
+distinguish serialized objects from normal arrays. You can prepend a
+"magic number" as first array element to reduce chances of a collision:
+
+ $json =~ s/\(\s*("([^\\":,]+|\\.|::)*")\s*\)\s*\[/["XU1peReLzT4ggEllLanBYq4G9VzliwKF",$1,/g;
+
+And after decoding the JSON text, you could walk the data
+structure looking for arrays with a first element of
+C<XU1peReLzT4ggEllLanBYq4G9VzliwKF>.
+
+The same approach can be used to create the tagged format with another
+encoder. First, you create an array with the magic string as first member,
+the classname as second, and constructor arguments last, encode it as part
+of your JSON structure, and then:
+
+ $json =~ s/\[\s*"XU1peReLzT4ggEllLanBYq4G9VzliwKF"\s*,\s*("([^\\":,]+|\\.|::)*")\s*,/($1)[/g;
+
+Again, this has some limitations - the magic string must not be encoded
+with character escapes, and the constructor arguments must be non-empty.
+
+
+=head1 RFC7159
+
+Since this module was written, Google has written a new JSON RFC, RFC 7159
+(and RFC7158). Unfortunately, this RFC breaks compatibility with both the
+original JSON specification on www.json.org and RFC4627.
+
+As far as I can see, you can get partial compatibility when parsing by
+using C<< ->allow_nonref >>. However, consider the security implications
+of doing so.
+
+I haven't decided yet when to break compatibility with RFC4627 by default
+(and potentially leave applications insecure) and change the default to
+follow RFC7159, but application authors are well advised to call C<<
+->allow_nonref(0) >> even if this is the current default, if they cannot
+handle non-reference values, in preparation for the day when the default
+will change.
+
+=head1 SECURITY CONSIDERATIONS
+
+JSON::XS and Cpanel::JSON::XS are not only fast. JSON is generally the
+most secure serializing format, because it is the only one besides
+Data::MessagePack, which does not deserialize objects per default. For
+all languages, not just perl. The binary variant BSON (MongoDB) does
+more but is unsafe.
+
+It is trivial for any attacker to create such serialized objects in
+JSON and trick perl into expanding them, thereby triggering certain
+methods. Watch L<https://www.youtube.com/watch?v=Gzx6KlqiIZE> for an
+exploit demo for "CVE-2015-1592 SixApart MovableType Storable Perl
+Code Execution" for a deserializer which expands objects.
+Deserializing even coderefs (methods, functions) or external
+data would be considered the most dangerous.
+
+Security relevant overview of serializers regarding deserializing
+objects by default:
+
+ Objects Coderefs External Data
+
+ Data::Dumper YES YES YES
+ Storable YES NO (def) NO
+ Sereal YES NO NO
+ YAML YES NO NO
+ B::C YES YES YES
+ B::Bytecode YES YES YES
+ BSON YES YES NO
+ JSON::SL YES NO YES
+ JSON NO (def) NO NO
+ Data::MessagePack NO NO NO
+ XML NO NO YES
+
+ Pickle YES YES YES
+ PHP Deserialize YES NO NO
+
+When you are using JSON in a protocol, talking to untrusted potentially
+hostile creatures requires relatively few measures.
+
+First of all, your JSON decoder should be secure, that is, should not have
+any buffer overflows. Obviously, this module should ensure that.
+
+Second, you need to avoid resource-starving attacks. That means you should
+limit the size of JSON texts you accept, or make sure then when your
+resources run out, that's just fine (e.g. by using a separate process that
+can crash safely). The size of a JSON text in octets or characters is
+usually a good indication of the size of the resources required to decode
+it into a Perl structure. While JSON::XS can check the size of the JSON
+text, it might be too late when you already have it in memory, so you
+might want to check the size before you accept the string.
+
+Third, Cpanel::JSON::XS recurses using the C stack when decoding objects and
+arrays. The C stack is a limited resource: for instance, on my amd64
+machine with 8MB of stack size I can decode around 180k nested arrays but
+only 14k nested JSON objects (due to perl itself recursing deeply on croak
+to free the temporary). If that is exceeded, the program crashes. To be
+conservative, the default nesting limit is set to 512. If your process
+has a smaller stack, you should adjust this setting accordingly with the
+C<max_depth> method.
+
+Also keep in mind that Cpanel::JSON::XS might leak contents of your Perl data
+structures in its error messages, so when you serialize sensitive
+information you might want to make sure that exceptions thrown by JSON::XS
+will not end up in front of untrusted eyes.
+
+If you are using Cpanel::JSON::XS to return packets to consumption
+by JavaScript scripts in a browser you should have a look at
+L<http://blog.archive.jpsykes.com/47/practical-csrf-and-json-security/> to
+see whether you are vulnerable to some common attack vectors (which really
+are browser design bugs, but it is still you who will have to deal with
+it, as major browser developers care only for features, not about getting
+security right). You might also want to also look at L<Mojo::JSON>
+special escape rules to prevent from XSS attacks.
+
+=head1 "OLD" VS. "NEW" JSON (RFC 4627 VS. RFC 7159)
+
+TL;DR: Due to security concerns, Cpanel::JSON::XS will not allow
+scalar data in JSON texts by default - you need to create your own
+Cpanel::JSON::XS object and enable C<allow_nonref>:
+
+
+ my $json = JSON::XS->new->allow_nonref;
+
+ $text = $json->encode ($data);
+ $data = $json->decode ($text);
+
+The long version: JSON being an important and supposedly stable format,
+the IETF standardized it as RFC 4627 in 2006. Unfortunately the inventor
+of JSON Douglas Crockford unilaterally changed the definition of JSON in
+javascript. Rather than create a fork, the IETF decided to standardize the
+new syntax (apparently, so I as told, without finding it very amusing).
+
+The biggest difference between the original JSON and the new JSON is that
+the new JSON supports scalars (anything other than arrays and objects) at
+the top-level of a JSON text. While this is strictly backwards compatible
+to older versions, it breaks a number of protocols that relied on sending
+JSON back-to-back, and is a minor security concern.
+
+For example, imagine you have two banks communicating, and on one side,
+the JSON coder gets upgraded. Two messages, such as C<10> and C<1000>
+might then be confused to mean C<101000>, something that couldn't happen
+in the original JSON, because neither of these messages would be valid
+JSON.
+
+If one side accepts these messages, then an upgrade in the coder on either
+side could result in this becoming exploitable.
+
+This module has always allowed these messages as an optional extension, by
+default disabled. The security concerns are the reason why the default is
+still disabled, but future versions might/will likely upgrade to the newer
+RFC as default format, so you are advised to check your implementation
+and/or override the default with C<< ->allow_nonref (0) >> to ensure that
+future versions are safe.
+
+=head1 THREADS
+
+Cpanel::JSON::XS has proper ithreads support, unlike JSON::XS. If you
+encounter any bugs with thread support please report them.
+
+=head1 BUGS
+
+While the goal of the Cpanel::JSON::XS module is to be correct, that
+unfortunately does not mean it's bug-free, only that the author thinks
+its design is bug-free. If you keep reporting bugs and tests they will
+be fixed swiftly, though.
+
+Since the JSON::XS author refuses to use a public bugtracker and
+prefers private emails, we've setup a tracker at RT, so you might want
+to report any issues twice. Once in private to MLEHMANN to be fixed in
+JSON::XS and one to our the public tracker. Issues fixed by JSON::XS
+with a new release will also be backported to Cpanel::JSON::XS and
+5.6.2, as long as cPanel relies on 5.6.2 and Cpanel::JSON::XS as our
+serializer of choice.
+
+L<https://rt.cpan.org/Public/Dist/Display.html?Queue=Cpanel-JSON-XS>
+
+=head1 LICENSE
+
+This module is available under the same licences as perl, the Artistic
+license and the GPL.
+
+=cut
+
+sub allow_bigint {
+ Carp::carp("allow_bigint() is obsoleted. use allow_bignum() instead.");
+}
+
+BEGIN {
+ package
+ JSON::PP::Boolean;
+
+ require overload;
+
+ local $^W; # silence redefine warnings. no warnings 'redefine' does not help
+ &overload::import( 'overload', # workaround 5.6 reserved keyword warning
+ "0+" => sub { ${$_[0]} },
+ "++" => sub { $_[0] = ${$_[0]} + 1 },
+ "--" => sub { $_[0] = ${$_[0]} - 1 },
+ '""' => sub { ${$_[0]} == 1 ? '1' : '0' }, # GH 29
+ 'eq' => sub {
+ my ($obj, $op) = ref ($_[0]) ? ($_[0], $_[1]) : ($_[1], $_[0]);
+ if ($op eq 'true' or $op eq 'false') {
+ return "$obj" eq '1' ? 'true' eq $op : 'false' eq $op;
+ }
+ else {
+ return $obj ? 1 == $op : 0 == $op;
+ }
+ },
+ fallback => 1);
+}
+
+our ($true, $false);
+BEGIN {
+ if ($INC{'JSON/XS.pm'}
+ and $INC{'Types/Serialiser.pm'}
+ and $JSON::XS::VERSION ge "3.00") {
+ $true = $Types::Serialiser::true; # readonly if loaded by JSON::XS
+ $false = $Types::Serialiser::false;
+ } else {
+ $true = do { bless \(my $dummy = 1), "JSON::PP::Boolean" };
+ $false = do { bless \(my $dummy = 0), "JSON::PP::Boolean" };
+ }
+}
+
+BEGIN {
+ my $const_true = $true;
+ my $const_false = $false;
+ *true = sub () { $const_true };
+ *false = sub () { $const_false };
+}
+
+sub is_bool($) {
+ shift if @_ == 2; # as method call
+ (ref($_[0]) and UNIVERSAL::isa( $_[0], JSON::PP::Boolean::))
+ or (exists $INC{'Types/Serialiser.pm'} and Types::Serialiser::is_bool($_[0]))
+}
+
+XSLoader::load 'Cpanel::JSON::XS', $XS_VERSION;
+
+1;
+
+=head1 SEE ALSO
+
+The F<cpanel_json_xs> command line utility for quick experiments.
+
+L<JSON>, L<JSON::XS>, L<JSON::MaybeXS>, L<Mojo::JSON>, L<Mojo::JSON::MaybeXS>,
+L<JSON::SL>, L<JSON::DWIW>, L<JSON::YAJL>, L<JSON::Any>, L<Test::JSON>,
+L<Locale::Wolowitz>,
+L<https://metacpan.org/search?q=JSON>
+
+L<https://tools.ietf.org/html/rfc7159>
+
+L<https://tools.ietf.org/html/rfc4627>
+
+
+=head1 AUTHOR
+
+Reini Urban <rurban@cpan.org>
+
+Marc Lehmann <schmorp@schmorp.de>, http://home.schmorp.de/
+
+=head1 MAINTAINER
+
+Reini Urban <rurban@cpan.org>
+
+=cut
+