Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 1536 insertions, 0 deletions

diff --git a/upstream/debian-unstable/man3/JSON::PP.3perl b/upstream/debian-unstable/man3/JSON::PP.3perl
new file mode 100644
index 00000000..df007bea
--- /dev/null
+++ b/upstream/debian-unstable/man3/JSON::PP.3perl
@@ -0,0 +1,1536 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "JSON::PP 3perl"
+.TH JSON::PP 3perl 2024-01-12 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH NAME
+JSON::PP \- JSON::XS compatible pure\-Perl module.
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 1
+\& use JSON::PP;
+\&
+\& # 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
+\&
+\& $json = JSON::PP\->new\->ascii\->pretty\->allow_nonref;
+\& 
+\& $pretty_printed_json_text = $json\->encode( $perl_scalar );
+\& $perl_scalar = $json\->decode( $json_text );
+\& 
+\& # Note that JSON version 2.0 and above will automatically use
+\& # JSON::XS or JSON::PP, so you should be able to just:
+\& 
+\& use JSON;
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+JSON::PP is a pure perl JSON decoder/encoder, and (almost) compatible to much
+faster JSON::XS written by Marc Lehmann in C. JSON::PP works as
+a fallback module when you use JSON module without having
+installed JSON::XS.
+.PP
+Because of this fallback feature of JSON.pm, JSON::PP tries not to
+be more JavaScript-friendly than JSON::XS (i.e. not to escape extra
+characters such as U+2028 and U+2029, etc),
+in order for you not to lose such JavaScript-friendliness silently
+when you use JSON.pm and install JSON::XS for speed or by accident.
+If you need JavaScript-friendly RFC7159\-compliant pure perl module,
+try JSON::Tiny, which is derived from Mojolicious web
+framework and is also smaller and faster than JSON::PP.
+.PP
+JSON::PP has been in the Perl core since Perl 5.14, mainly for
+CPAN toolchain modules to parse META.json.
+.SH "FUNCTIONAL INTERFACE"
+.IX Header "FUNCTIONAL INTERFACE"
+This section is taken from JSON::XS almost verbatim. \f(CW\*(C`encode_json\*(C'\fR
+and \f(CW\*(C`decode_json\*(C'\fR are exported by default.
+.SS encode_json
+.IX Subsection "encode_json"
+.Vb 1
+\&    $json_text = encode_json $perl_scalar
+.Ve
+.PP
+Converts the given Perl data structure to a UTF\-8 encoded, binary string
+(that is, the string contains octets only). Croaks on error.
+.PP
+This function call is functionally identical to:
+.PP
+.Vb 1
+\&    $json_text = JSON::PP\->new\->utf8\->encode($perl_scalar)
+.Ve
+.PP
+Except being faster.
+.SS decode_json
+.IX Subsection "decode_json"
+.Vb 1
+\&    $perl_scalar = decode_json $json_text
+.Ve
+.PP
+The opposite of \f(CW\*(C`encode_json\*(C'\fR: expects an UTF\-8 (binary) string and tries
+to parse that as an UTF\-8 encoded JSON text, returning the resulting
+reference. Croaks on error.
+.PP
+This function call is functionally identical to:
+.PP
+.Vb 1
+\&    $perl_scalar = JSON::PP\->new\->utf8\->decode($json_text)
+.Ve
+.PP
+Except being faster.
+.SS JSON::PP::is_bool
+.IX Subsection "JSON::PP::is_bool"
+.Vb 1
+\&    $is_boolean = JSON::PP::is_bool($scalar)
+.Ve
+.PP
+Returns true if the passed scalar represents either JSON::PP::true or
+JSON::PP::false, two constants that act like \f(CW1\fR and \f(CW0\fR respectively
+and are also used to represent JSON \f(CW\*(C`true\*(C'\fR and \f(CW\*(C`false\*(C'\fR in Perl strings.
+.PP
+On perl 5.36 and above, will also return true when given one of perl's
+standard boolean values, such as the result of a comparison.
+.PP
+See MAPPING, below, for more information on how JSON values are mapped to
+Perl.
+.SH "OBJECT-ORIENTED INTERFACE"
+.IX Header "OBJECT-ORIENTED INTERFACE"
+This section is also taken from JSON::XS.
+.PP
+The object oriented interface lets you configure your own encoding or
+decoding style, within the limits of supported formats.
+.SS new
+.IX Subsection "new"
+.Vb 1
+\&    $json = JSON::PP\->new
+.Ve
+.PP
+Creates a new JSON::PP object that can be used to de/encode JSON
+strings. All boolean flags described below are by default \fIdisabled\fR
+(with the exception of \f(CW\*(C`allow_nonref\*(C'\fR, which defaults to \fIenabled\fR since
+version \f(CW4.0\fR).
+.PP
+The mutators for flags all return the JSON::PP object again and thus calls can
+be chained:
+.PP
+.Vb 2
+\&   my $json = JSON::PP\->new\->utf8\->space_after\->encode({a => [1,2]})
+\&   => {"a": [1, 2]}
+.Ve
+.SS ascii
+.IX Subsection "ascii"
+.Vb 1
+\&    $json = $json\->ascii([$enable])
+\&    
+\&    $enabled = $json\->get_ascii
+.Ve
+.PP
+If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will not
+generate characters outside the code range \f(CW0..127\fR (which is ASCII). Any
+Unicode characters outside that range will be escaped using either a
+single \euXXXX (BMP characters) or a double \euHHHH\euLLLLL 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.
+.PP
+If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will not escape Unicode
+characters unless required by the JSON syntax or other flags. This results
+in a faster and more compact format.
+.PP
+See also the section \fIENCODING/CODESET FLAG NOTES\fR later in this document.
+.PP
+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.
+.PP
+.Vb 2
+\&  JSON::PP\->new\->ascii(1)\->encode([chr 0x10401])
+\&  => ["\eud801\eudc01"]
+.Ve
+.SS latin1
+.IX Subsection "latin1"
+.Vb 1
+\&    $json = $json\->latin1([$enable])
+\&    
+\&    $enabled = $json\->get_latin1
+.Ve
+.PP
+If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will encode
+the resulting JSON text as latin1 (or iso\-8859\-1), escaping any characters
+outside the code range \f(CW0..255\fR. The resulting string can be treated as a
+latin1\-encoded JSON text or a native Unicode string. The \f(CW\*(C`decode\*(C'\fR method
+will not be affected in any way by this flag, as \f(CW\*(C`decode\*(C'\fR by default
+expects Unicode, which is a strict superset of latin1.
+.PP
+If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will not escape Unicode
+characters unless required by the JSON syntax or other flags.
+.PP
+See also the section \fIENCODING/CODESET FLAG NOTES\fR later in this document.
+.PP
+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.
+.PP
+.Vb 2
+\&  JSON::PP\->new\->latin1\->encode (["\ex{89}\ex{abc}"]
+\&  => ["\ex{89}\e\eu0abc"]    # (perl syntax, U+abc escaped, U+89 not)
+.Ve
+.SS utf8
+.IX Subsection "utf8"
+.Vb 1
+\&    $json = $json\->utf8([$enable])
+\&    
+\&    $enabled = $json\->get_utf8
+.Ve
+.PP
+If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will encode
+the JSON result into UTF\-8, as required by many protocols, while the
+\&\f(CW\*(C`decode\*(C'\fR 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 \f(CW0..255\fR, 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.
+.PP
+If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will return the JSON
+string as a (non-encoded) Unicode string, while \f(CW\*(C`decode\*(C'\fR 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.
+.PP
+See also the section \fIENCODING/CODESET FLAG NOTES\fR later in this document.
+.PP
+Example, output UTF\-16BE\-encoded JSON:
+.PP
+.Vb 2
+\&  use Encode;
+\&  $jsontext = encode "UTF\-16BE", JSON::PP\->new\->encode ($object);
+.Ve
+.PP
+Example, decode UTF\-32LE\-encoded JSON:
+.PP
+.Vb 2
+\&  use Encode;
+\&  $object = JSON::PP\->new\->decode (decode "UTF\-32LE", $jsontext);
+.Ve
+.SS pretty
+.IX Subsection "pretty"
+.Vb 1
+\&    $json = $json\->pretty([$enable])
+.Ve
+.PP
+This enables (or disables) all of the \f(CW\*(C`indent\*(C'\fR, \f(CW\*(C`space_before\*(C'\fR and
+\&\f(CW\*(C`space_after\*(C'\fR (and in the future possibly more) flags in one call to
+generate the most readable (or most compact) form possible.
+.SS indent
+.IX Subsection "indent"
+.Vb 1
+\&    $json = $json\->indent([$enable])
+\&    
+\&    $enabled = $json\->get_indent
+.Ve
+.PP
+If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR 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.
+.PP
+If \f(CW$enable\fR is false, no newlines or indenting will be produced, and the
+resulting JSON text is guaranteed not to contain any \f(CW\*(C`newlines\*(C'\fR.
+.PP
+This setting has no effect when decoding JSON texts.
+.PP
+The default indent space length is three.
+You can use \f(CW\*(C`indent_length\*(C'\fR to change the length.
+.SS space_before
+.IX Subsection "space_before"
+.Vb 1
+\&    $json = $json\->space_before([$enable])
+\&    
+\&    $enabled = $json\->get_space_before
+.Ve
+.PP
+If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will add an extra
+optional space before the \f(CW\*(C`:\*(C'\fR separating keys from values in JSON objects.
+.PP
+If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will not add any extra
+space at those places.
+.PP
+This setting has no effect when decoding JSON texts. You will also
+most likely combine this setting with \f(CW\*(C`space_after\*(C'\fR.
+.PP
+Example, space_before enabled, space_after and indent disabled:
+.PP
+.Vb 1
+\&   {"key" :"value"}
+.Ve
+.SS space_after
+.IX Subsection "space_after"
+.Vb 1
+\&    $json = $json\->space_after([$enable])
+\&    
+\&    $enabled = $json\->get_space_after
+.Ve
+.PP
+If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will add an extra
+optional space after the \f(CW\*(C`:\*(C'\fR separating keys from values in JSON objects
+and extra whitespace after the \f(CW\*(C`,\*(C'\fR separating key-value pairs and array
+members.
+.PP
+If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will not add any extra
+space at those places.
+.PP
+This setting has no effect when decoding JSON texts.
+.PP
+Example, space_before and indent disabled, space_after enabled:
+.PP
+.Vb 1
+\&   {"key": "value"}
+.Ve
+.SS relaxed
+.IX Subsection "relaxed"
+.Vb 1
+\&    $json = $json\->relaxed([$enable])
+\&    
+\&    $enabled = $json\->get_relaxed
+.Ve
+.PP
+If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`decode\*(C'\fR will accept some
+extensions to normal JSON syntax (see below). \f(CW\*(C`encode\*(C'\fR will not be
+affected in anyway. \fIBe aware that this option makes you accept invalid
+JSON texts as if they were valid!\fR. I suggest only to use this option to
+parse application-specific files written by humans (configuration files,
+resource files etc.)
+.PP
+If \f(CW$enable\fR is false (the default), then \f(CW\*(C`decode\*(C'\fR will only accept
+valid JSON texts.
+.PP
+Currently accepted extensions are:
+.IP \(bu 4
+list items can have an end-comma
+.Sp
+JSON \fIseparates\fR 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:
+.Sp
+.Vb 8
+\&   [
+\&      1,
+\&      2, <\- this comma not normally allowed
+\&   ]
+\&   {
+\&      "k1": "v1",
+\&      "k2": "v2", <\- this comma not normally allowed
+\&   }
+.Ve
+.IP \(bu 4
+shell-style '#'\-comments
+.Sp
+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.
+.Sp
+.Vb 4
+\&  [
+\&     1, # this comment not allowed in JSON
+\&        # neither this one...
+\&  ]
+.Ve
+.IP \(bu 4
+C\-style multiple-line '/* */'\-comments (JSON::PP only)
+.Sp
+Whenever JSON allows whitespace, C\-style multiple-line comments are additionally
+allowed. Everything between \f(CW\*(C`/*\*(C'\fR and \f(CW\*(C`*/\*(C'\fR is a comment, after which
+more white-space and comments are allowed.
+.Sp
+.Vb 4
+\&  [
+\&     1, /* this comment not allowed in JSON */
+\&        /* neither this one... */
+\&  ]
+.Ve
+.IP \(bu 4
+C++\-style one-line '//'\-comments (JSON::PP only)
+.Sp
+Whenever JSON allows whitespace, C++\-style one-line 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.
+.Sp
+.Vb 4
+\&  [
+\&     1, // this comment not allowed in JSON
+\&        // neither this one...
+\&  ]
+.Ve
+.IP \(bu 4
+literal ASCII TAB characters in strings
+.Sp
+Literal ASCII TAB characters are now allowed in strings (and treated as
+\&\f(CW\*(C`\et\*(C'\fR).
+.Sp
+.Vb 4
+\&  [
+\&     "Hello\etWorld",
+\&     "Hello<TAB>World", # literal <TAB> would not normally be allowed
+\&  ]
+.Ve
+.SS canonical
+.IX Subsection "canonical"
+.Vb 1
+\&    $json = $json\->canonical([$enable])
+\&    
+\&    $enabled = $json\->get_canonical
+.Ve
+.PP
+If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will output JSON objects
+by sorting their keys. This is adding a comparatively high overhead.
+.PP
+If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR 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).
+.PP
+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.
+.PP
+This setting has no effect when decoding JSON texts.
+.PP
+This setting has currently no effect on tied hashes.
+.SS allow_nonref
+.IX Subsection "allow_nonref"
+.Vb 1
+\&    $json = $json\->allow_nonref([$enable])
+\&    
+\&    $enabled = $json\->get_allow_nonref
+.Ve
+.PP
+Unlike other boolean options, this opotion is enabled by default beginning
+with version \f(CW4.0\fR.
+.PP
+If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method can convert a
+non-reference into its corresponding string, number or null JSON value,
+which is an extension to RFC4627. Likewise, \f(CW\*(C`decode\*(C'\fR will accept those JSON
+values instead of croaking.
+.PP
+If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will croak if it isn't
+passed an arrayref or hashref, as JSON texts must either be an object
+or array. Likewise, \f(CW\*(C`decode\*(C'\fR will croak if given something that is not a
+JSON object or array.
+.PP
+Example, encode a Perl scalar as JSON value without enabled \f(CW\*(C`allow_nonref\*(C'\fR,
+resulting in an error:
+.PP
+.Vb 2
+\&   JSON::PP\->new\->allow_nonref(0)\->encode ("Hello, World!")
+\&   => hash\- or arrayref expected...
+.Ve
+.SS allow_unknown
+.IX Subsection "allow_unknown"
+.Vb 1
+\&    $json = $json\->allow_unknown([$enable])
+\&    
+\&    $enabled = $json\->get_allow_unknown
+.Ve
+.PP
+If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`encode\*(C'\fR will \fInot\fR throw an
+exception when it encounters values it cannot represent in JSON (for
+example, filehandles) but instead will encode a JSON \f(CW\*(C`null\*(C'\fR value. Note
+that blessed objects are not included here and are handled separately by
+c<allow_blessed>.
+.PP
+If \f(CW$enable\fR is false (the default), then \f(CW\*(C`encode\*(C'\fR will throw an
+exception when it encounters anything it cannot encode as JSON.
+.PP
+This option does not affect \f(CW\*(C`decode\*(C'\fR in any way, and it is recommended to
+leave it off unless you know your communications partner.
+.SS allow_blessed
+.IX Subsection "allow_blessed"
+.Vb 1
+\&    $json = $json\->allow_blessed([$enable])
+\&    
+\&    $enabled = $json\->get_allow_blessed
+.Ve
+.PP
+See "OBJECT SERIALISATION" for details.
+.PP
+If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will not
+barf when it encounters a blessed reference that it cannot convert
+otherwise. Instead, a JSON \f(CW\*(C`null\*(C'\fR value is encoded instead of the object.
+.PP
+If \f(CW$enable\fR is false (the default), then \f(CW\*(C`encode\*(C'\fR will throw an
+exception when it encounters a blessed object that it cannot convert
+otherwise.
+.PP
+This setting has no effect on \f(CW\*(C`decode\*(C'\fR.
+.SS convert_blessed
+.IX Subsection "convert_blessed"
+.Vb 1
+\&    $json = $json\->convert_blessed([$enable])
+\&    
+\&    $enabled = $json\->get_convert_blessed
+.Ve
+.PP
+See "OBJECT SERIALISATION" for details.
+.PP
+If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`encode\*(C'\fR, upon encountering a
+blessed object, will check for the availability of the \f(CW\*(C`TO_JSON\*(C'\fR 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.
+.PP
+The \f(CW\*(C`TO_JSON\*(C'\fR method may safely call die if it wants. If \f(CW\*(C`TO_JSON\*(C'\fR
+returns other blessed objects, those will be handled in the same
+way. \f(CW\*(C`TO_JSON\*(C'\fR must take care of not causing an endless recursion cycle
+(== crash) in this case. The name of \f(CW\*(C`TO_JSON\*(C'\fR 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 \f(CW\*(C`to_json\*(C'\fR
+function or method.
+.PP
+If \f(CW$enable\fR is false (the default), then \f(CW\*(C`encode\*(C'\fR will not consider
+this type of conversion.
+.PP
+This setting has no effect on \f(CW\*(C`decode\*(C'\fR.
+.SS allow_tags
+.IX Subsection "allow_tags"
+.Vb 1
+\&    $json = $json\->allow_tags([$enable])
+\&
+\&    $enabled = $json\->get_allow_tags
+.Ve
+.PP
+See "OBJECT SERIALISATION" for details.
+.PP
+If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`encode\*(C'\fR, upon encountering a
+blessed object, will check for the availability of the \f(CW\*(C`FREEZE\*(C'\fR method on
+the object's class. If found, it will be used to serialise the object into
+a nonstandard tagged JSON value (that JSON decoders cannot decode).
+.PP
+It also causes \f(CW\*(C`decode\*(C'\fR to parse such tagged JSON values and deserialise
+them via a call to the \f(CW\*(C`THAW\*(C'\fR method.
+.PP
+If \f(CW$enable\fR is false (the default), then \f(CW\*(C`encode\*(C'\fR will not consider
+this type of conversion, and tagged JSON values will cause a parse error
+in \f(CW\*(C`decode\*(C'\fR, as if tags were not part of the grammar.
+.SS boolean_values
+.IX Subsection "boolean_values"
+.Vb 1
+\&    $json\->boolean_values([$false, $true])
+\&
+\&    ($false,  $true) = $json\->get_boolean_values
+.Ve
+.PP
+By default, JSON booleans will be decoded as overloaded
+\&\f(CW$JSON::PP::false\fR and \f(CW$JSON::PP::true\fR objects.
+.PP
+With this method you can specify your own boolean values for decoding \-
+on decode, JSON \f(CW\*(C`false\*(C'\fR will be decoded as a copy of \f(CW$false\fR, and JSON
+\&\f(CW\*(C`true\*(C'\fR will be decoded as \f(CW$true\fR ("copy" here is the same thing as
+assigning a value to another variable, i.e. \f(CW\*(C`$copy = $false\*(C'\fR).
+.PP
+This is useful when you want to pass a decoded data structure directly
+to other serialisers like YAML, Data::MessagePack and so on.
+.PP
+Note that this works only when you \f(CW\*(C`decode\*(C'\fR. You can set incompatible
+boolean objects (like boolean), but when you \f(CW\*(C`encode\*(C'\fR a data structure
+with such boolean objects, you still need to enable \f(CW\*(C`convert_blessed\*(C'\fR
+(and add a \f(CW\*(C`TO_JSON\*(C'\fR method if necessary).
+.PP
+Calling this method without any arguments will reset the booleans
+to their default values.
+.PP
+\&\f(CW\*(C`get_boolean_values\*(C'\fR will return both \f(CW$false\fR and \f(CW$true\fR values, or
+the empty list when they are set to the default.
+.SS core_bools
+.IX Subsection "core_bools"
+.Vb 1
+\&    $json\->core_bools([$enable]);
+.Ve
+.PP
+If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`decode\*(C'\fR, will produce standard
+perl boolean values. Equivalent to calling:
+.PP
+.Vb 1
+\&    $json\->boolean_values(!!1, !!0)
+.Ve
+.PP
+\&\f(CW\*(C`get_core_bools\*(C'\fR will return true if this has been set. On perl 5.36, it will
+also return true if the boolean values have been set to perl's core booleans
+using the \f(CW\*(C`boolean_values\*(C'\fR method.
+.PP
+The methods \f(CW\*(C`unblessed_bool\*(C'\fR and \f(CW\*(C`get_unblessed_bool\*(C'\fR are provided as aliases
+for compatibility with Cpanel::JSON::XS.
+.SS filter_json_object
+.IX Subsection "filter_json_object"
+.Vb 1
+\&    $json = $json\->filter_json_object([$coderef])
+.Ve
+.PP
+When \f(CW$coderef\fR is specified, it will be called from \f(CW\*(C`decode\*(C'\fR 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 (or rather a copy of it) is
+inserted into the deserialised data structure. If it returns an empty
+list (NOTE: \fInot\fR \f(CW\*(C`undef\*(C'\fR, which is a valid scalar), the original
+deserialised hash will be inserted. This setting can slow down decoding
+considerably.
+.PP
+When \f(CW$coderef\fR is omitted or undefined, any existing callback will
+be removed and \f(CW\*(C`decode\*(C'\fR will not change the deserialised hash in any
+way.
+.PP
+Example, convert all JSON objects into the integer 5:
+.PP
+.Vb 5
+\&   my $js = JSON::PP\->new\->filter_json_object(sub { 5 });
+\&   # returns [5]
+\&   $js\->decode(\*(Aq[{}]\*(Aq);
+\&   # returns 5
+\&   $js\->decode(\*(Aq{"a":1, "b":2}\*(Aq);
+.Ve
+.SS filter_json_single_key_object
+.IX Subsection "filter_json_single_key_object"
+.Vb 1
+\&    $json = $json\->filter_json_single_key_object($key [=> $coderef])
+.Ve
+.PP
+Works remotely similar to \f(CW\*(C`filter_json_object\*(C'\fR, but is only called for
+JSON objects having a single key named \f(CW$key\fR.
+.PP
+This \f(CW$coderef\fR is called before the one specified via
+\&\f(CW\*(C`filter_json_object\*(C'\fR, 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 \f(CW\*(C`undef\*(C'\fR but the empty list),
+the callback from \f(CW\*(C`filter_json_object\*(C'\fR will be called next, as if no
+single-key callback were specified.
+.PP
+If \f(CW$coderef\fR is omitted or undefined, the corresponding callback will be
+disabled. There can only ever be one callback for a given key.
+.PP
+As this callback gets called less often then the \f(CW\*(C`filter_json_object\*(C'\fR
+one, decoding speed will not usually suffer as much. Therefore, single-key
+objects make excellent targets to serialise 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 serialised Perl hash.
+.PP
+Typical names for the single object key are \f(CW\*(C`_\|_class_whatever_\|_\*(C'\fR, or
+\&\f(CW\*(C`$_\|_dollars_are_rarely_used_\|_$\*(C'\fR or \f(CW\*(C`}ugly_brace_placement\*(C'\fR, or even
+things like \f(CW\*(C`_\|_class_md5sum(classname)_\|_\*(C'\fR, to reduce the risk of clashing
+with real hashes.
+.PP
+Example, decode JSON objects of the form \f(CW\*(C`{ "_\|_widget_\|_" => <id> }\*(C'\fR
+into the corresponding \f(CW$WIDGET{<id>}\fR object:
+.PP
+.Vb 7
+\&   # return whatever is in $WIDGET{5}:
+\&   JSON::PP
+\&      \->new
+\&      \->filter_json_single_key_object (_\|_widget_\|_ => sub {
+\&            $WIDGET{ $_[0] }
+\&         })
+\&      \->decode (\*(Aq{"_\|_widget_\|_": 5\*(Aq)
+\&
+\&   # this can be used with a TO_JSON method in some "widget" class
+\&   # for serialisation to json:
+\&   sub WidgetBase::TO_JSON {
+\&      my ($self) = @_;
+\&
+\&      unless ($self\->{id}) {
+\&         $self\->{id} = ..get..some..id..;
+\&         $WIDGET{$self\->{id}} = $self;
+\&      }
+\&
+\&      { _\|_widget_\|_ => $self\->{id} }
+\&   }
+.Ve
+.SS shrink
+.IX Subsection "shrink"
+.Vb 1
+\&    $json = $json\->shrink([$enable])
+\&    
+\&    $enabled = $json\->get_shrink
+.Ve
+.PP
+If \f(CW$enable\fR is true (or missing), the string returned by \f(CW\*(C`encode\*(C'\fR will
+be shrunk (i.e. downgraded if possible).
+.PP
+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.
+.PP
+If \f(CW$enable\fR is false, then JSON::PP does nothing.
+.SS max_depth
+.IX Subsection "max_depth"
+.Vb 1
+\&    $json = $json\->max_depth([$maximum_nesting_depth])
+\&    
+\&    $max_depth = $json\->get_max_depth
+.Ve
+.PP
+Sets the maximum nesting level (default \f(CW512\fR) 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.
+.PP
+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 \f(CW\*(C`{\*(C'\fR or \f(CW\*(C`[\*(C'\fR
+characters without their matching closing parenthesis crossed to reach a
+given character in a string.
+.PP
+Setting the maximum depth to one disallows any nesting, so that ensures
+that the object is only a single hash/object or array.
+.PP
+If no argument is given, the highest possible setting will be used, which
+is rarely useful.
+.PP
+See "SECURITY CONSIDERATIONS" in JSON::XS for more info on why this is useful.
+.SS max_size
+.IX Subsection "max_size"
+.Vb 1
+\&    $json = $json\->max_size([$maximum_string_size])
+\&    
+\&    $max_size = $json\->get_max_size
+.Ve
+.PP
+Set the maximum length a JSON text may have (in bytes) where decoding is
+being attempted. The default is \f(CW0\fR, meaning no limit. When \f(CW\*(C`decode\*(C'\fR
+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 \f(CW\*(C`encode\*(C'\fR (yet).
+.PP
+If no argument is given, the limit check will be deactivated (same as when
+\&\f(CW0\fR is specified).
+.PP
+See "SECURITY CONSIDERATIONS" in JSON::XS for more info on why this is useful.
+.SS encode
+.IX Subsection "encode"
+.Vb 1
+\&    $json_text = $json\->encode($perl_scalar)
+.Ve
+.PP
+Converts the given Perl value or data structure to its JSON
+representation. Croaks on error.
+.SS decode
+.IX Subsection "decode"
+.Vb 1
+\&    $perl_scalar = $json\->decode($json_text)
+.Ve
+.PP
+The opposite of \f(CW\*(C`encode\*(C'\fR: expects a JSON text and tries to parse it,
+returning the resulting simple scalar or reference. Croaks on error.
+.SS decode_prefix
+.IX Subsection "decode_prefix"
+.Vb 1
+\&    ($perl_scalar, $characters) = $json\->decode_prefix($json_text)
+.Ve
+.PP
+This works like the \f(CW\*(C`decode\*(C'\fR 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.
+.PP
+This is useful if your JSON texts are not delimited by an outer protocol
+and you need to know where the JSON text ends.
+.PP
+.Vb 2
+\&   JSON::PP\->new\->decode_prefix ("[1] the tail")
+\&   => ([1], 3)
+.Ve
+.SH "FLAGS FOR JSON::PP ONLY"
+.IX Header "FLAGS FOR JSON::PP ONLY"
+The following flags and properties are for JSON::PP only. If you use
+any of these, you can't make your application run faster by replacing
+JSON::PP with JSON::XS. If you need these and also speed boost,
+you might want to try Cpanel::JSON::XS, a fork of JSON::XS by
+Reini Urban, which supports some of these (with a different set of
+incompatibilities). Most of these historical flags are only kept
+for backward compatibility, and should not be used in a new application.
+.SS allow_singlequote
+.IX Subsection "allow_singlequote"
+.Vb 2
+\&    $json = $json\->allow_singlequote([$enable])
+\&    $enabled = $json\->get_allow_singlequote
+.Ve
+.PP
+If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`decode\*(C'\fR will accept
+invalid JSON texts that contain strings that begin and end with
+single quotation marks. \f(CW\*(C`encode\*(C'\fR will not be affected in any way.
+\&\fIBe aware that this option makes you accept invalid JSON texts
+as if they were valid!\fR. I suggest only to use this option to
+parse application-specific files written by humans (configuration
+files, resource files etc.)
+.PP
+If \f(CW$enable\fR is false (the default), then \f(CW\*(C`decode\*(C'\fR will only accept
+valid JSON texts.
+.PP
+.Vb 3
+\&    $json\->allow_singlequote\->decode(qq|{"foo":\*(Aqbar\*(Aq}|);
+\&    $json\->allow_singlequote\->decode(qq|{\*(Aqfoo\*(Aq:"bar"}|);
+\&    $json\->allow_singlequote\->decode(qq|{\*(Aqfoo\*(Aq:\*(Aqbar\*(Aq}|);
+.Ve
+.SS allow_barekey
+.IX Subsection "allow_barekey"
+.Vb 2
+\&    $json = $json\->allow_barekey([$enable])
+\&    $enabled = $json\->get_allow_barekey
+.Ve
+.PP
+If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`decode\*(C'\fR will accept
+invalid JSON texts that contain JSON objects whose names don't
+begin and end with quotation marks. \f(CW\*(C`encode\*(C'\fR will not be affected
+in any way. \fIBe aware that this option makes you accept invalid JSON
+texts as if they were valid!\fR. I suggest only to use this option to
+parse application-specific files written by humans (configuration
+files, resource files etc.)
+.PP
+If \f(CW$enable\fR is false (the default), then \f(CW\*(C`decode\*(C'\fR will only accept
+valid JSON texts.
+.PP
+.Vb 1
+\&    $json\->allow_barekey\->decode(qq|{foo:"bar"}|);
+.Ve
+.SS allow_bignum
+.IX Subsection "allow_bignum"
+.Vb 2
+\&    $json = $json\->allow_bignum([$enable])
+\&    $enabled = $json\->get_allow_bignum
+.Ve
+.PP
+If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`decode\*(C'\fR will convert
+big integers Perl cannot handle as integer into Math::BigInt
+objects and convert floating numbers into Math::BigFloat
+objects. \f(CW\*(C`encode\*(C'\fR will convert \f(CW\*(C`Math::BigInt\*(C'\fR and \f(CW\*(C`Math::BigFloat\*(C'\fR
+objects into JSON numbers.
+.PP
+.Vb 4
+\&   $json\->allow_nonref\->allow_bignum;
+\&   $bigfloat = $json\->decode(\*(Aq2.000000000000000000000000001\*(Aq);
+\&   print $json\->encode($bigfloat);
+\&   # => 2.000000000000000000000000001
+.Ve
+.PP
+See also MAPPING.
+.SS loose
+.IX Subsection "loose"
+.Vb 2
+\&    $json = $json\->loose([$enable])
+\&    $enabled = $json\->get_loose
+.Ve
+.PP
+If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`decode\*(C'\fR will accept
+invalid JSON texts that contain unescaped [\ex00\-\ex1f\ex22\ex5c]
+characters. \f(CW\*(C`encode\*(C'\fR will not be affected in any way.
+\&\fIBe aware that this option makes you accept invalid JSON texts
+as if they were valid!\fR. I suggest only to use this option to
+parse application-specific files written by humans (configuration
+files, resource files etc.)
+.PP
+If \f(CW$enable\fR is false (the default), then \f(CW\*(C`decode\*(C'\fR will only accept
+valid JSON texts.
+.PP
+.Vb 2
+\&    $json\->loose\->decode(qq|["abc
+\&                                   def"]|);
+.Ve
+.SS escape_slash
+.IX Subsection "escape_slash"
+.Vb 2
+\&    $json = $json\->escape_slash([$enable])
+\&    $enabled = $json\->get_escape_slash
+.Ve
+.PP
+If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`encode\*(C'\fR will explicitly
+escape \fIslash\fR (solidus; \f(CW\*(C`U+002F\*(C'\fR) characters to reduce the risk of
+XSS (cross site scripting) that may be caused by \f(CW\*(C`</script>\*(C'\fR
+in a JSON text, with the cost of bloating the size of JSON texts.
+.PP
+This option may be useful when you embed JSON in HTML, but embedding
+arbitrary JSON in HTML (by some HTML template toolkit or by string
+interpolation) is risky in general. You must escape necessary
+characters in correct order, depending on the context.
+.PP
+\&\f(CW\*(C`decode\*(C'\fR will not be affected in any way.
+.SS indent_length
+.IX Subsection "indent_length"
+.Vb 2
+\&    $json = $json\->indent_length($number_of_spaces)
+\&    $length = $json\->get_indent_length
+.Ve
+.PP
+This option is only useful when you also enable \f(CW\*(C`indent\*(C'\fR or \f(CW\*(C`pretty\*(C'\fR.
+.PP
+JSON::XS indents with three spaces when you \f(CW\*(C`encode\*(C'\fR (if requested
+by \f(CW\*(C`indent\*(C'\fR or \f(CW\*(C`pretty\*(C'\fR), and the number cannot be changed.
+JSON::PP allows you to change/get the number of indent spaces with these
+mutator/accessor. The default number of spaces is three (the same as
+JSON::XS), and the acceptable range is from \f(CW0\fR (no indentation;
+it'd be better to disable indentation by \f(CWindent(0)\fR) to \f(CW15\fR.
+.SS sort_by
+.IX Subsection "sort_by"
+.Vb 2
+\&    $json = $json\->sort_by($code_ref)
+\&    $json = $json\->sort_by($subroutine_name)
+.Ve
+.PP
+If you just want to sort keys (names) in JSON objects when you
+\&\f(CW\*(C`encode\*(C'\fR, enable \f(CW\*(C`canonical\*(C'\fR option (see above) that allows you to
+sort object keys alphabetically.
+.PP
+If you do need to sort non-alphabetically for whatever reasons,
+you can give a code reference (or a subroutine name) to \f(CW\*(C`sort_by\*(C'\fR,
+then the argument will be passed to Perl's \f(CW\*(C`sort\*(C'\fR built-in function.
+.PP
+As the sorting is done in the JSON::PP scope, you usually need to
+prepend \f(CW\*(C`JSON::PP::\*(C'\fR to the subroutine name, and the special variables
+\&\f(CW$a\fR and \f(CW$b\fR used in the subrontine used by \f(CW\*(C`sort\*(C'\fR function.
+.PP
+Example:
+.PP
+.Vb 9
+\&   my %ORDER = (id => 1, class => 2, name => 3);
+\&   $json\->sort_by(sub {
+\&       ($ORDER{$JSON::PP::a} // 999) <=> ($ORDER{$JSON::PP::b} // 999)
+\&       or $JSON::PP::a cmp $JSON::PP::b
+\&   });
+\&   print $json\->encode([
+\&       {name => \*(AqCPAN\*(Aq, id => 1, href => \*(Aqhttp://cpan.org\*(Aq}
+\&   ]);
+\&   # [{"id":1,"name":"CPAN","href":"http://cpan.org"}]
+.Ve
+.PP
+Note that \f(CW\*(C`sort_by\*(C'\fR affects all the plain hashes in the data structure.
+If you need finer control, \f(CW\*(C`tie\*(C'\fR necessary hashes with a module that
+implements ordered hash (such as Hash::Ordered and Tie::IxHash).
+\&\f(CW\*(C`canonical\*(C'\fR and \f(CW\*(C`sort_by\*(C'\fR don't affect the key order in \f(CW\*(C`tie\*(C'\fRd
+hashes.
+.PP
+.Vb 5
+\&   use Hash::Ordered;
+\&   tie my %hash, \*(AqHash::Ordered\*(Aq,
+\&       (name => \*(AqCPAN\*(Aq, id => 1, href => \*(Aqhttp://cpan.org\*(Aq);
+\&   print $json\->encode([\e%hash]);
+\&   # [{"name":"CPAN","id":1,"href":"http://cpan.org"}] # order is kept
+.Ve
+.SH "INCREMENTAL PARSING"
+.IX Header "INCREMENTAL PARSING"
+This section is also taken from JSON::XS.
+.PP
+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 \f(CW\*(C`decode_prefix\*(C'\fR to see if a full JSON object is available, but
+is much more efficient (and can be implemented with a minimum of method
+calls).
+.PP
+JSON::PP 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. \f(CW\*(C`max_size\*(C'\fR) to ensure the parser will stop
+parsing in the presence if syntax errors.
+.PP
+The following methods implement this incremental parser.
+.SS incr_parse
+.IX Subsection "incr_parse"
+.Vb 1
+\&    $json\->incr_parse( [$string] ) # void context
+\&    
+\&    $obj_or_undef = $json\->incr_parse( [$string] ) # scalar context
+\&    
+\&    @obj_or_empty = $json\->incr_parse( [$string] ) # list context
+.Ve
+.PP
+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).
+.PP
+If \f(CW$string\fR is given, then this string is appended to the already
+existing JSON fragment stored in the \f(CW$json\fR object.
+.PP
+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.
+.PP
+If the method is called in scalar context, then it will try to extract
+exactly \fIone\fR JSON object. If that is successful, it will return this
+object, otherwise it will return \f(CW\*(C`undef\*(C'\fR. If there is a parse error,
+this method will croak just as \f(CW\*(C`decode\*(C'\fR would do (one can then use
+\&\f(CW\*(C`incr_skip\*(C'\fR to skip the erroneous part). This is the most common way of
+using the method.
+.PP
+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 (other than
+whitespace) 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.
+.PP
+Example: Parse some JSON arrays/objects in a given string and return
+them.
+.PP
+.Vb 1
+\&    my @objs = JSON::PP\->new\->incr_parse ("[5][7][1,2]");
+.Ve
+.SS incr_text
+.IX Subsection "incr_text"
+.Vb 1
+\&    $lvalue_string = $json\->incr_text
+.Ve
+.PP
+This method returns the currently stored JSON fragment as an lvalue, that
+is, you can manipulate it. This \fIonly\fR works when a preceding call to
+\&\f(CW\*(C`incr_parse\*(C'\fR in \fIscalar context\fR successfully returned an object. Under
+all other circumstances you must not call this function (I mean it.
+although in simple tests it might actually work, it \fIwill\fR fail under
+real world conditions). As a special exception, you can also call this
+method before having parsed anything.
+.PP
+That means you can only use this function to look at or manipulate text
+before or after complete JSON objects, not while the parser is in the
+middle of parsing a JSON object.
+.PP
+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).
+.SS incr_skip
+.IX Subsection "incr_skip"
+.Vb 1
+\&    $json\->incr_skip
+.Ve
+.PP
+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
+\&\f(CW\*(C`incr_parse\*(C'\fR 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.
+.PP
+The difference to \f(CW\*(C`incr_reset\*(C'\fR is that only text until the parse error
+occurred is removed.
+.SS incr_reset
+.IX Subsection "incr_reset"
+.Vb 1
+\&    $json\->incr_reset
+.Ve
+.PP
+This completely resets the incremental parser, that is, after this call,
+it will be as if the parser had never parsed anything.
+.PP
+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.
+.SH MAPPING
+.IX Header "MAPPING"
+Most of this section is also taken from JSON::XS.
+.PP
+This section describes how JSON::PP 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).
+.PP
+For the more enlightened: note that in the following descriptions,
+lowercase \fIperl\fR refers to the Perl interpreter, while uppercase \fIPerl\fR
+refers to the abstract Perl language itself.
+.SS "JSON \-> PERL"
+.IX Subsection "JSON -> PERL"
+.IP object 4
+.IX 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).
+.IP array 4
+.IX Item "array"
+A JSON array becomes a reference to an array in Perl.
+.IP string 4
+.IX 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.
+.IP number 4
+.IX 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.
+.Sp
+If the number consists of digits only, JSON::PP 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).
+.Sp
+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).
+.Sp
+Note that precision is not accuracy \- binary floating point values cannot
+represent most decimal fractions exactly, and when converting from and to
+floating point, JSON::PP only guarantees precision up to but not including
+the least significant bit.
+.Sp
+When \f(CW\*(C`allow_bignum\*(C'\fR is enabled, big integer values and any numeric
+values will be converted into Math::BigInt and Math::BigFloat
+objects respectively, without becoming string scalars or losing
+precision.
+.IP "true, false" 4
+.IX Item "true, false"
+These JSON atoms become \f(CW\*(C`JSON::PP::true\*(C'\fR and \f(CW\*(C`JSON::PP::false\*(C'\fR,
+respectively. They are overloaded to act almost exactly like the numbers
+\&\f(CW1\fR and \f(CW0\fR. You can check whether a scalar is a JSON boolean by using
+the \f(CW\*(C`JSON::PP::is_bool\*(C'\fR function.
+.IP null 4
+.IX Item "null"
+A JSON null atom becomes \f(CW\*(C`undef\*(C'\fR in Perl.
+.ie n .IP "shell-style comments (""# \fItext\fR"")" 4
+.el .IP "shell-style comments (\f(CW# \fR\f(CItext\fR\f(CW\fR)" 4
+.IX Item "shell-style comments (# text)"
+As a nonstandard extension to the JSON syntax that is enabled by the
+\&\f(CW\*(C`relaxed\*(C'\fR setting, shell-style comments are allowed. They can start
+anywhere outside strings and go till the end of the line.
+.ie n .IP "tagged values (""(\fItag\fR)\fIvalue\fR"")." 4
+.el .IP "tagged values (\f(CW(\fR\f(CItag\fR\f(CW)\fR\f(CIvalue\fR\f(CW\fR)." 4
+.IX Item "tagged values ((tag)value)."
+Another nonstandard extension to the JSON syntax, enabled with the
+\&\f(CW\*(C`allow_tags\*(C'\fR setting, are tagged values. In this implementation, the
+\&\fItag\fR must be a perl package/class name encoded as a JSON string, and the
+\&\fIvalue\fR must be a JSON array encoding optional constructor arguments.
+.Sp
+See "OBJECT SERIALISATION", below, for details.
+.SS "PERL \-> JSON"
+.IX Subsection "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.
+.IP "hash references" 4
+.IX 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. JSON::PP can optionally sort the hash keys
+(determined by the \fIcanonical\fR flag and/or \fIsort_by\fR property), so
+the same data structure will serialise to the same JSON text (given
+same settings and version of JSON::PP), 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.
+.IP "array references" 4
+.IX Item "array references"
+Perl array references become JSON arrays.
+.IP "other references" 4
+.IX Item "other references"
+Other unblessed references are generally not allowed and will cause an
+exception to be thrown, except for references to the integers \f(CW0\fR and
+\&\f(CW1\fR, which get turned into \f(CW\*(C`false\*(C'\fR and \f(CW\*(C`true\*(C'\fR atoms in JSON. You can
+also use \f(CW\*(C`JSON::PP::false\*(C'\fR and \f(CW\*(C`JSON::PP::true\*(C'\fR to improve
+readability.
+.Sp
+.Vb 1
+\&   to_json [\e0, JSON::PP::true]      # yields [false,true]
+.Ve
+.IP "JSON::PP::true, JSON::PP::false" 4
+.IX Item "JSON::PP::true, JSON::PP::false"
+These special values become JSON true and JSON false values,
+respectively. You can also use \f(CW\*(C`\e1\*(C'\fR and \f(CW\*(C`\e0\*(C'\fR directly if you want.
+.IP JSON::PP::null 4
+.IX Item "JSON::PP::null"
+This special value becomes JSON null.
+.IP "blessed objects" 4
+.IX Item "blessed objects"
+Blessed objects are not directly representable in JSON, but \f(CW\*(C`JSON::PP\*(C'\fR
+allows various ways of handling objects. See "OBJECT SERIALISATION",
+below, for details.
+.IP "simple scalars" 4
+.IX Item "simple scalars"
+Simple Perl scalars (any scalar that is not a reference) are the most
+difficult objects to encode: JSON::PP will encode undefined scalars as
+JSON \f(CW\*(C`null\*(C'\fR values, scalars that have last been used in a string context
+before encoding as JSON strings, and anything else as number value:
+.Sp
+.Vb 4
+\&   # 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, so dump as string
+\&   print $value;
+\&   encode_json [$value]                 # yields ["5"]
+\&
+\&   # undef becomes null
+\&   encode_json [undef]                  # yields [null]
+.Ve
+.Sp
+You can force the type to be a JSON string by stringifying it:
+.Sp
+.Vb 5
+\&   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
+\&                # (but for older perls)
+.Ve
+.Sp
+You can force the type to be a JSON number by numifying it:
+.Sp
+.Vb 3
+\&   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.
+.Ve
+.Sp
+You can not currently force the type in other, less obscure, ways.
+.Sp
+Since version 2.91_01, JSON::PP uses a different number detection logic
+that converts a scalar that is possible to turn into a number safely.
+The new logic is slightly faster, and tends to help people who use older
+perl or who want to encode complicated data structure. However, this may
+results in a different JSON text from the one JSON::XS encodes (and
+thus may break tests that compare entire JSON texts). If you do
+need the previous behavior for compatibility or for finer control,
+set PERL_JSON_PP_USE_B environmental variable to true before you
+\&\f(CW\*(C`use\*(C'\fR JSON::PP (or JSON.pm).
+.Sp
+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 it is an
+error to pass those in.
+.Sp
+JSON::PP (and JSON::XS) trusts what you pass to \f(CW\*(C`encode\*(C'\fR method
+(or \f(CW\*(C`encode_json\*(C'\fR function) is a clean, validated data structure with
+values that can be represented as valid JSON values only, because it's
+not from an external data source (as opposed to JSON texts you pass to
+\&\f(CW\*(C`decode\*(C'\fR or \f(CW\*(C`decode_json\*(C'\fR, which JSON::PP considers tainted and
+doesn't trust). As JSON::PP doesn't know exactly what you and consumers
+of your JSON texts want the unexpected values to be (you may want to
+convert them into null, or to stringify them with or without
+normalisation (string representation of infinities/NaN may vary
+depending on platforms), or to croak without conversion), you're advised
+to do what you and your consumers need before you encode, and also not
+to numify values that may start with values that look like a number
+(including infinities/NaN), without validating.
+.SS "OBJECT SERIALISATION"
+.IX Subsection "OBJECT SERIALISATION"
+As JSON cannot directly represent Perl objects, you have to choose between
+a pure JSON representation (without the ability to deserialise the object
+automatically again), and a nonstandard extension to the JSON syntax,
+tagged values.
+.PP
+\fISERIALISATION\fR
+.IX Subsection "SERIALISATION"
+.PP
+What happens when \f(CW\*(C`JSON::PP\*(C'\fR encounters a Perl object depends on the
+\&\f(CW\*(C`allow_blessed\*(C'\fR, \f(CW\*(C`convert_blessed\*(C'\fR, \f(CW\*(C`allow_tags\*(C'\fR and \f(CW\*(C`allow_bignum\*(C'\fR
+settings, which are used in this order:
+.ie n .IP "1. ""allow_tags"" is enabled and the object has a ""FREEZE"" method." 4
+.el .IP "1. \f(CWallow_tags\fR is enabled and the object has a \f(CWFREEZE\fR method." 4
+.IX Item "1. allow_tags is enabled and the object has a FREEZE method."
+In this case, \f(CW\*(C`JSON::PP\*(C'\fR creates a tagged JSON value, using a nonstandard
+extension to the JSON syntax.
+.Sp
+This works by invoking the \f(CW\*(C`FREEZE\*(C'\fR method on the object, with the first
+argument being the object to serialise, and the second argument being the
+constant string \f(CW\*(C`JSON\*(C'\fR to distinguish it from other serialisers.
+.Sp
+The \f(CW\*(C`FREEZE\*(C'\fR 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:
+.Sp
+.Vb 1
+\&   ("classname")[FREEZE return values...]
+.Ve
+.Sp
+e.g.:
+.Sp
+.Vb 3
+\&   ("URI")["http://www.google.com/"]
+\&   ("MyDate")[2013,10,29]
+\&   ("ImageData::JPEG")["Z3...VlCg=="]
+.Ve
+.Sp
+For example, the hypothetical \f(CW\*(C`My::Object\*(C'\fR \f(CW\*(C`FREEZE\*(C'\fR method might use the
+objects \f(CW\*(C`type\*(C'\fR and \f(CW\*(C`id\*(C'\fR members to encode the object:
+.Sp
+.Vb 2
+\&   sub My::Object::FREEZE {
+\&      my ($self, $serialiser) = @_;
+\&
+\&      ($self\->{type}, $self\->{id})
+\&   }
+.Ve
+.ie n .IP "2. ""convert_blessed"" is enabled and the object has a ""TO_JSON"" method." 4
+.el .IP "2. \f(CWconvert_blessed\fR is enabled and the object has a \f(CWTO_JSON\fR method." 4
+.IX Item "2. convert_blessed is enabled and the object has a TO_JSON method."
+In this case, the \f(CW\*(C`TO_JSON\*(C'\fR 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.
+.Sp
+For example, the following \f(CW\*(C`TO_JSON\*(C'\fR method will convert all URI
+objects to JSON strings when serialised. The fact that these values
+originally were URI objects is lost.
+.Sp
+.Vb 4
+\&   sub URI::TO_JSON {
+\&      my ($uri) = @_;
+\&      $uri\->as_string
+\&   }
+.Ve
+.ie n .IP "3. ""allow_bignum"" is enabled and the object is a ""Math::BigInt"" or ""Math::BigFloat""." 4
+.el .IP "3. \f(CWallow_bignum\fR is enabled and the object is a \f(CWMath::BigInt\fR or \f(CWMath::BigFloat\fR." 4
+.IX Item "3. allow_bignum is enabled and the object is a Math::BigInt or Math::BigFloat."
+The object will be serialised as a JSON number value.
+.ie n .IP "4. ""allow_blessed"" is enabled." 4
+.el .IP "4. \f(CWallow_blessed\fR is enabled." 4
+.IX Item "4. allow_blessed is enabled."
+The object will be serialised as a JSON null value.
+.IP "5. none of the above" 4
+.IX Item "5. none of the above"
+If none of the settings are enabled or the respective methods are missing,
+\&\f(CW\*(C`JSON::PP\*(C'\fR throws an exception.
+.PP
+\fIDESERIALISATION\fR
+.IX Subsection "DESERIALISATION"
+.PP
+For deserialisation there are only two cases to consider: either
+nonstandard tagging was used, in which case \f(CW\*(C`allow_tags\*(C'\fR decides,
+or objects cannot be automatically be deserialised, in which
+case you can use postprocessing or the \f(CW\*(C`filter_json_object\*(C'\fR or
+\&\f(CW\*(C`filter_json_single_key_object\*(C'\fR callbacks to get some real objects our of
+your JSON.
+.PP
+This section only considers the tagged value case: a tagged JSON object
+is encountered during decoding and \f(CW\*(C`allow_tags\*(C'\fR is disabled, a parse
+error will result (as if tagged values were not part of the grammar).
+.PP
+If \f(CW\*(C`allow_tags\*(C'\fR is enabled, \f(CW\*(C`JSON::PP\*(C'\fR will look up the \f(CW\*(C`THAW\*(C'\fR method
+of the package/classname used during serialisation (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.
+.PP
+Otherwise, the \f(CW\*(C`THAW\*(C'\fR method is invoked with the classname as first
+argument, the constant string \f(CW\*(C`JSON\*(C'\fR as second argument, and all the
+values from the JSON array (the values originally returned by the
+\&\f(CW\*(C`FREEZE\*(C'\fR method) as remaining arguments.
+.PP
+The method must then return the object. While technically you can return
+any Perl scalar, you might have to enable the \f(CW\*(C`allow_nonref\*(C'\fR setting to
+make that work in all cases, so better return an actual blessed reference.
+.PP
+As an example, let's implement a \f(CW\*(C`THAW\*(C'\fR function that regenerates the
+\&\f(CW\*(C`My::Object\*(C'\fR from the \f(CW\*(C`FREEZE\*(C'\fR example earlier:
+.PP
+.Vb 2
+\&   sub My::Object::THAW {
+\&      my ($class, $serialiser, $type, $id) = @_;
+\&
+\&      $class\->new (type => $type, id => $id)
+\&   }
+.Ve
+.SH "ENCODING/CODESET FLAG NOTES"
+.IX Header "ENCODING/CODESET FLAG NOTES"
+This section is taken from JSON::XS.
+.PP
+The interested reader might have seen a number of flags that signify
+encodings or codesets \- \f(CW\*(C`utf8\*(C'\fR, \f(CW\*(C`latin1\*(C'\fR and \f(CW\*(C`ascii\*(C'\fR. There seems to be
+some confusion on what these do, so here is a short comparison:
+.PP
+\&\f(CW\*(C`utf8\*(C'\fR controls whether the JSON text created by \f(CW\*(C`encode\*(C'\fR (and expected
+by \f(CW\*(C`decode\*(C'\fR) is UTF\-8 encoded or not, while \f(CW\*(C`latin1\*(C'\fR and \f(CW\*(C`ascii\*(C'\fR only
+control whether \f(CW\*(C`encode\*(C'\fR escapes character values outside their respective
+codeset range. Neither of these flags conflict with each other, although
+some combinations make less sense than others.
+.PP
+Care has been taken to make all flags symmetrical with respect to
+\&\f(CW\*(C`encode\*(C'\fR and \f(CW\*(C`decode\*(C'\fR, 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.
+.PP
+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 \fIencodes\fR 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 \fIand\fR encodings at
+the same time, which can be confusing.
+.ie n .IP """utf8"" flag disabled" 4
+.el .IP "\f(CWutf8\fR flag disabled" 4
+.IX Item "utf8 flag disabled"
+When \f(CW\*(C`utf8\*(C'\fR is disabled (the default), then \f(CW\*(C`encode\*(C'\fR/\f(CW\*(C`decode\*(C'\fR 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).
+.Sp
+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).
+.ie n .IP """utf8"" flag enabled" 4
+.el .IP "\f(CWutf8\fR flag enabled" 4
+.IX Item "utf8 flag enabled"
+If the \f(CW\*(C`utf8\*(C'\fR\-flag is enabled, \f(CW\*(C`encode\*(C'\fR/\f(CW\*(C`decode\*(C'\fR 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.
+.Sp
+The \f(CW\*(C`utf8\*(C'\fR 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.
+.ie n .IP """latin1"" or ""ascii"" flags enabled" 4
+.el .IP "\f(CWlatin1\fR or \f(CWascii\fR flags enabled" 4
+.IX Item "latin1 or ascii flags enabled"
+With \f(CW\*(C`latin1\*(C'\fR (or \f(CW\*(C`ascii\*(C'\fR) enabled, \f(CW\*(C`encode\*(C'\fR will escape characters
+with ordinal values > 255 (> 127 with \f(CW\*(C`ascii\*(C'\fR) and encode the remaining
+characters as specified by the \f(CW\*(C`utf8\*(C'\fR flag.
+.Sp
+If \f(CW\*(C`utf8\*(C'\fR 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).
+.Sp
+If \f(CW\*(C`utf8\*(C'\fR is enabled, you still get a correct UTF\-8\-encoded string,
+regardless of these flags, just some more characters will be escaped using
+\&\f(CW\*(C`\euXXXX\*(C'\fR then before.
+.Sp
+Note that ISO\-8859\-1\-\fIencoded\fR 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 \fIcodeset\fR being
+a subset of Unicode), while ASCII is.
+.Sp
+Surprisingly, \f(CW\*(C`decode\*(C'\fR will ignore these flags and so treat all input
+values as governed by the \f(CW\*(C`utf8\*(C'\fR 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.
+.Sp
+So neither \f(CW\*(C`latin1\*(C'\fR nor \f(CW\*(C`ascii\*(C'\fR are incompatible with the \f(CW\*(C`utf8\*(C'\fR flag \-
+they only govern when the JSON output engine escapes a character or not.
+.Sp
+The main use for \f(CW\*(C`latin1\*(C'\fR is to relatively efficiently store binary data
+as JSON, at the expense of breaking compatibility with most JSON decoders.
+.Sp
+The main use for \f(CW\*(C`ascii\*(C'\fR 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.
+.SH BUGS
+.IX Header "BUGS"
+Please report bugs on a specific behavior of this module to RT or GitHub
+issues (preferred):
+.PP
+<https://github.com/makamaka/JSON\-PP/issues>
+.PP
+<https://rt.cpan.org/Public/Dist/Display.html?Queue=JSON\-PP>
+.PP
+As for new features and requests to change common behaviors, please
+ask the author of JSON::XS (Marc Lehmann, <schmorp[at]schmorp.de>)
+first, by email (important!), to keep compatibility among JSON.pm backends.
+.PP
+Generally speaking, if you need something special for you, you are advised
+to create a new module, maybe based on JSON::Tiny, which is smaller and
+written in a much cleaner way than this module.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+The \fIjson_pp\fR command line utility for quick experiments.
+.PP
+JSON::XS, Cpanel::JSON::XS, and JSON::Tiny for faster alternatives.
+JSON and JSON::MaybeXS for easy migration.
+.PP
+JSON::PP::Compat5005 and JSON::PP::Compat5006 for older perl users.
+.PP
+RFC4627 (<http://www.ietf.org/rfc/rfc4627.txt>)
+.PP
+RFC7159 (<http://www.ietf.org/rfc/rfc7159.txt>)
+.PP
+RFC8259 (<http://www.ietf.org/rfc/rfc8259.txt>)
+.SH AUTHOR
+.IX Header "AUTHOR"
+Makamaka Hannyaharamitu, <makamaka[at]cpan.org>
+.SH "CURRENT MAINTAINER"
+.IX Header "CURRENT MAINTAINER"
+Kenichi Ishigaki, <ishigaki[at]cpan.org>
+.SH "COPYRIGHT AND LICENSE"
+.IX Header "COPYRIGHT AND LICENSE"
+Copyright 2007\-2016 by Makamaka Hannyaharamitu
+.PP
+Most of the documentation is taken from JSON::XS by Marc Lehmann
+.PP
+This library is free software; you can redistribute it and/or modify
+it under the same terms as Perl itself.