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.pm104
1 files changed, 81 insertions, 23 deletions
diff --git a/Master/tlpkg/tlperl/site/lib/Cpanel/JSON/XS.pm b/Master/tlpkg/tlperl/site/lib/Cpanel/JSON/XS.pm
index 6154f649ff8..47df6b4ea71 100755
--- a/Master/tlpkg/tlperl/site/lib/Cpanel/JSON/XS.pm
+++ b/Master/tlpkg/tlperl/site/lib/Cpanel/JSON/XS.pm
@@ -1,5 +1,5 @@
package Cpanel::JSON::XS;
-our $VERSION = '4.09';
+our $VERSION = '4.19';
our $XS_VERSION = $VERSION;
# $VERSION = eval $VERSION;
@@ -36,6 +36,9 @@ Cpanel::JSON::XS - cPanel fork of JSON::XS, fast and correct serializing
# and do the same things, except that you have a pure-perl fallback now.
+ Note that this module will be replaced by a new JSON::Safe module soon,
+ with the same API just guaranteed safe defaults.
+
=head1 DESCRIPTION
This module converts Perl data structures to JSON and vice versa. Its
@@ -118,7 +121,7 @@ B<Changes to JSON::XS>
strings. Cpanel::JSON::XS is a bit slower, but preserves numeric
types better.
-- numbers ending with .0 stay numbers, are not converted to
+- numbers ending with .0 stray 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
@@ -173,6 +176,8 @@ B<Changes to JSON::XS>
- #96 locale-insensitive numeric conversion
+ - #154 numeric conversion fixed since 5.22, using the same strtold as perl5.
+
- public maintenance and bugtracker
- use ppport.h, sanify XS.xs comment styles, harness C coding style
@@ -191,7 +196,7 @@ B<Changes to JSON::XS>
decode_json(, allow_nonref) arg.
relaxed implements allow_dupkeys.
-- support all 5 unicode BOM's: UTF-8, UTF-16LE, UTF-16BE, UTF-32LE,
+- support all 5 unicode L<BOM|/BOM>'s: UTF-8, UTF-16LE, UTF-16BE, UTF-32LE,
UTF-32BE, encoding internally to UTF-8.
=cut
@@ -238,13 +243,13 @@ Converts the given Perl data structure to a UTF-8 encoded, binary string
This function call is functionally identical to:
- $json_text = Cpanel::JSON::XS->new->utf8->encode ($perl_scalar)
+ $json_text = Cpanel::JSON::XS->new->utf8->encode ($perl_scalar, $json_type)
Except being faster.
For the type argument see L<Cpanel::JSON::XS::Type>.
-=item $perl_scalar = decode_json $json_text [, $allow_nonref ]
+=item $perl_scalar = decode_json $json_text [, $allow_nonref [, my $json_type ] ]
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,
@@ -252,7 +257,7 @@ returning the resulting reference. Croaks on error.
This function call is functionally identical to:
- $perl_scalar = Cpanel::JSON::XS->new->utf8->decode ($json_text)
+ $perl_scalar = Cpanel::JSON::XS->new->utf8->decode ($json_text, $json_type)
except being faster.
@@ -265,6 +270,8 @@ 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".
+For the type argument see L<Cpanel::JSON::XS::Type>.
+
=item $is_boolean = Cpanel::JSON::XS::is_bool $scalar
Returns true if the passed scalar represents either C<JSON::XS::true>
@@ -825,6 +832,35 @@ 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->require_types ([$enable])
+
+=item $enable = $json->get_require_types
+
+ $json = $json->require_types([$enable])
+
+If C<$enable> is true (or missing), then C<encode> will require
+either enabled C<type_all_string> or second argument with supplied JSON types.
+See L<Cpanel::JSON::XS::Type>. When C<type_all_string> is not enabled or
+second argument is not provided (or is undef), then C<encode>
+croaks. It also croaks when the type for provided structure in
+C<encode> is incomplete.
+
+=item $json = $json->type_all_string ([$enable])
+
+=item $enable = $json->get_type_all_string
+
+ $json = $json->type_all_string([$enable])
+
+If C<$enable> is true (or missing), then C<encode> will always
+produce stable deterministic JSON string types in resulted output.
+
+When C<$enable> is false, then result of encoded JSON output may be
+different for different Perl versions and may depends on loaded modules.
+
+This is useful it you need deterministic JSON types, independently of used
+Perl version and other modules, but do not want to write complicated type
+definitions for L<Cpanel::JSON::XS::Type>.
+
=item $json = $json->allow_dupkeys ([$enable])
=item $enabled = $json->get_allow_dupkeys
@@ -871,11 +907,13 @@ 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.
+way. C<TO_JSON> must take care of not causing an endless recursion
+cycle (== crash) in this case. The same care must be taken with
+calling encode in stringify overloads (even if this works by luck in
+older perls) or other callbacks. 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.
@@ -1066,7 +1104,7 @@ sprintf(%g), but without double quotes.
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)
+=item $json_text = $json->encode ($perl_scalar, $json_type)
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
@@ -1075,7 +1113,9 @@ 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)
+For the type argument see L<Cpanel::JSON::XS::Type>.
+
+=item $perl_scalar = $json->decode ($json_text, my $json_type)
The opposite of C<encode>: expects a JSON text and tries to parse it,
returning the resulting simple scalar or reference. Croaks on error.
@@ -1084,6 +1124,8 @@ 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>.
+For the type argument see L<Cpanel::JSON::XS::Type>.
+
=item ($perl_scalar, $characters) = $json->decode_prefix ($json_text)
This works like the C<decode> method, but instead of raising an exception
@@ -1358,6 +1400,9 @@ the above example :).
Detect all unicode B<Byte Order Marks> on decode.
Which are UTF-8, UTF-16LE, UTF-16BE, UTF-32LE and UTF-32BE.
+The BOM encoding is set only for one specific decode call, it does not
+change the state of the JSON object.
+
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.
@@ -1437,7 +1482,10 @@ up to but not including the least significant bit.
=item true, false
-These JSON atoms become C<Cpanel::JSON::XS::true> and
+When C<unblessed_bool> is set to true, then JSON C<true> becomes C<1> and
+JSON C<false> becomes C<0>.
+
+Otherwise 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
@@ -1525,13 +1573,13 @@ 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]
+ encode_json [Cpanel::JSON::XS::false, Cpanel::JSON::XS::true] # yields [false,true]
+ encode_json [!1, !0], [JSON_TYPE_BOOL, JSON_TYPE_BOOL] # yields [false,true]
eq/ne comparisons with true, false:
false is eq to the empty string or the string 'false' or the special
-empty string C<!!0>, i.e. C<SV_NO>, or the numbers 0 or 0.0.
+empty string C<!!0> or C<!1>, i.e. C<SV_NO>, or the numbers 0 or 0.0.
true is eq to the string 'true' or to the special string C<!0>
(i.e. C<SV_YES>) or to the numbers 1 or 1.0.
@@ -1552,7 +1600,17 @@ your own serializer method.
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
+scalars or inf/nan as JSON C<null> values and other scalars to either
+number or string in non-deterministic way which may be affected or
+changed by Perl version or any other loaded Perl module.
+
+If you want to have stable and deterministic types in JSON encoder then
+use L<Cpanel::JSON::XS::Type>.
+
+Alternative way for deterministic types is to use C<type_all_string>
+method when all perl scalars are encoded to JSON strings.
+
+Non-deterministic behavior is following: scalars that have last been
used in a string context before encoding as JSON strings, and anything
else as number value:
@@ -1661,7 +1719,7 @@ originally were L<URI> objects is lost.
$uri->as_string
}
-=item 2. C<convert_blessed> is enabled and the object has a stringification overload.
+=item 3. 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
@@ -1674,11 +1732,11 @@ originally were L<URI> objects is lost.
package URI;
use overload '""' => sub { shift->as_string };
-=item 3. C<allow_blessed> is enabled.
+=item 4. C<allow_blessed> is enabled.
The object will be serialized as a JSON null value.
-=item 4. none of the above
+=item 5. none of the above
If none of the settings are enabled or the respective methods are missing,
C<Cpanel::JSON::XS> throws an exception.
@@ -2220,14 +2278,14 @@ 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
+prefers private emails, we use the tracker at B<github>, 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>
+L<https://github.com/rurban/Cpanel-JSON-XS/issues>
=head1 LICENSE