summaryrefslogtreecommitdiff
path: root/systems/texlive/tlnet/tlpkg/tlperl/lib/JSON
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2020-04-11 03:09:12 +0000
committerNorbert Preining <norbert@preining.info>2020-04-11 03:09:12 +0000
commitc2697fc286a1e2c94fd9968b76be6f4a6d2114cd (patch)
tree1dc2cfb07cb032740483dd8be7c74aff66b70352 /systems/texlive/tlnet/tlpkg/tlperl/lib/JSON
parent25111608e6aa05042b0c6f83009262e1973d7a45 (diff)
CTAN sync 202004110309
Diffstat (limited to 'systems/texlive/tlnet/tlpkg/tlperl/lib/JSON')
-rw-r--r--systems/texlive/tlnet/tlpkg/tlperl/lib/JSON/PP.pm412
-rw-r--r--systems/texlive/tlnet/tlpkg/tlperl/lib/JSON/PP/Boolean.pm11
2 files changed, 362 insertions, 61 deletions
diff --git a/systems/texlive/tlnet/tlpkg/tlperl/lib/JSON/PP.pm b/systems/texlive/tlnet/tlpkg/tlperl/lib/JSON/PP.pm
index 714c848d9b..d8b7ab3065 100644
--- a/systems/texlive/tlnet/tlpkg/tlperl/lib/JSON/PP.pm
+++ b/systems/texlive/tlnet/tlpkg/tlperl/lib/JSON/PP.pm
@@ -14,7 +14,7 @@ use JSON::PP::Boolean;
use Carp ();
#use Devel::Peek;
-$JSON::PP::VERSION = '2.97001';
+$JSON::PP::VERSION = '4.02';
@JSON::PP::EXPORT = qw(encode_json decode_json from_json to_json);
@@ -42,20 +42,22 @@ use constant P_ESCAPE_SLASH => 16;
use constant P_AS_NONBLESSED => 17;
use constant P_ALLOW_UNKNOWN => 18;
+use constant P_ALLOW_TAGS => 19;
use constant OLD_PERL => $] < 5.008 ? 1 : 0;
-use constant USE_B => 0;
+use constant USE_B => $ENV{PERL_JSON_PP_USE_B} || 0;
BEGIN {
-if (USE_B) {
- require B;
-}
+ if (USE_B) {
+ require B;
+ }
}
BEGIN {
my @xs_compati_bit_properties = qw(
latin1 ascii utf8 indent canonical space_before space_after allow_nonref shrink
allow_blessed convert_blessed relaxed allow_unknown
+ allow_tags
);
my @pp_bit_properties = qw(
allow_singlequote allow_bignum loose
@@ -132,6 +134,8 @@ sub new {
indent_length => 3,
};
+ $self->{PROPS}[P_ALLOW_NONREF] = 1;
+
bless $self, $class;
}
@@ -191,6 +195,27 @@ sub max_size {
sub get_max_size { $_[0]->{max_size}; }
+sub boolean_values {
+ my $self = shift;
+ if (@_) {
+ my ($false, $true) = @_;
+ $self->{false} = $false;
+ $self->{true} = $true;
+ return ($false, $true);
+ } else {
+ delete $self->{false};
+ delete $self->{true};
+ return;
+ }
+}
+
+sub get_boolean_values {
+ my $self = shift;
+ if (exists $self->{true} and exists $self->{false}) {
+ return @$self{qw/false true/};
+ }
+ return;
+}
sub filter_json_object {
if (defined $_[1] and ref $_[1] eq 'CODE') {
@@ -264,6 +289,7 @@ sub allow_bigint {
my $escape_slash;
my $bignum;
my $as_nonblessed;
+ my $allow_tags;
my $depth;
my $indent_count;
@@ -280,9 +306,9 @@ sub allow_bigint {
my $props = $self->{PROPS};
($ascii, $latin1, $utf8, $indent, $canonical, $space_before, $space_after, $allow_blessed,
- $convert_blessed, $escape_slash, $bignum, $as_nonblessed)
+ $convert_blessed, $escape_slash, $bignum, $as_nonblessed, $allow_tags)
= @{$props}[P_ASCII .. P_SPACE_AFTER, P_ALLOW_BLESSED, P_CONVERT_BLESSED,
- P_ESCAPE_SLASH, P_ALLOW_BIGNUM, P_AS_NONBLESSED];
+ P_ESCAPE_SLASH, P_ALLOW_BIGNUM, P_AS_NONBLESSED, P_ALLOW_TAGS];
($max_depth, $indent_length) = @{$self}{qw/max_depth indent_length/};
@@ -328,6 +354,21 @@ sub allow_bigint {
return $self->value_to_json($obj) if ( $obj->isa('JSON::PP::Boolean') );
+ if ( $allow_tags and $obj->can('FREEZE') ) {
+ my $obj_class = ref $obj || $obj;
+ $obj = bless $obj, $obj_class;
+ my @results = $obj->FREEZE('JSON');
+ if ( @results and ref $results[0] ) {
+ if ( refaddr( $obj ) eq refaddr( $results[0] ) ) {
+ encode_error( sprintf(
+ "%s::FREEZE method returned same object as was passed instead of a new one",
+ ref $obj
+ ) );
+ }
+ }
+ return '("'.$obj_class.'")['.join(',', @results).']';
+ }
+
if ( $convert_blessed and $obj->can('TO_JSON') ) {
my $result = $obj->TO_JSON();
if ( defined $result and ref( $result ) ) {
@@ -348,8 +389,7 @@ sub allow_bigint {
return $self->blessed_to_json($obj) if ($as_nonblessed); # will be removed.
return 'null';
}
- encode_error( sprintf("encountered object '%s', but neither allow_blessed "
- . "nor convert_blessed settings are enabled", $obj)
+ encode_error( sprintf("encountered object '%s', but neither allow_blessed, convert_blessed nor allow_tags settings are enabled (or TO_JSON/FREEZE method missing)", $obj)
);
}
else {
@@ -652,6 +692,10 @@ BEGIN {
my $singlequote; # loosely quoting
my $loose; #
my $allow_barekey; # bareKey
+ my $allow_tags;
+
+ my $alt_true;
+ my $alt_false;
sub _detect_utf_encoding {
my $text = shift;
@@ -678,8 +722,10 @@ BEGIN {
my $props = $self->{PROPS};
- ($utf8, $relaxed, $loose, $allow_bignum, $allow_barekey, $singlequote)
- = @{$props}[P_UTF8, P_RELAXED, P_LOOSE .. P_ALLOW_SINGLEQUOTE];
+ ($utf8, $relaxed, $loose, $allow_bignum, $allow_barekey, $singlequote, $allow_tags)
+ = @{$props}[P_UTF8, P_RELAXED, P_LOOSE .. P_ALLOW_SINGLEQUOTE, P_ALLOW_TAGS];
+
+ ($alt_true, $alt_false) = @$self{qw/true false/};
if ( $utf8 ) {
$encoding = _detect_utf_encoding($text);
@@ -746,6 +792,7 @@ BEGIN {
return if(!defined $ch);
return object() if($ch eq '{');
return array() if($ch eq '[');
+ return tag() if($ch eq '(');
return string() if($ch eq '"' or ($singlequote and $ch eq "'"));
return number() if($ch =~ /[0-9]/ or $ch eq '-');
return word();
@@ -841,8 +888,10 @@ BEGIN {
if (!$loose) {
if ($ch =~ /[\x00-\x1f\x22\x5c]/) { # '/' ok
- $at--;
- decode_error('invalid character encountered while parsing JSON string');
+ if (!$relaxed or $ch ne "\t") {
+ $at--;
+ decode_error('invalid character encountered while parsing JSON string');
+ }
}
}
@@ -955,6 +1004,35 @@ BEGIN {
decode_error(", or ] expected while parsing array");
}
+ sub tag {
+ decode_error('malformed JSON string, neither array, object, number, string or atom') unless $allow_tags;
+
+ next_chr();
+ white();
+
+ my $tag = value();
+ return unless defined $tag;
+ decode_error('malformed JSON string, (tag) must be a string') if ref $tag;
+
+ white();
+
+ if (!defined $ch or $ch ne ')') {
+ decode_error(') expected after tag');
+ }
+
+ next_chr();
+ white();
+
+ my $val = value();
+ return unless defined $val;
+ decode_error('malformed JSON string, tag value must be an array') unless ref $val eq 'ARRAY';
+
+ if (!eval { $tag->can('THAW') }) {
+ decode_error('cannot decode perl-object (package does not exist)') if $@;
+ decode_error('cannot decode perl-object (package does not have a THAW method)');
+ }
+ $tag->THAW('JSON', @$val);
+ }
sub object {
my $o = $_[0] || {}; # you can use this code to use another hash ref object.
@@ -1039,7 +1117,7 @@ BEGIN {
if($word eq 'true'){
$at += 3;
next_chr;
- return $JSON::PP::true;
+ return defined $alt_true ? $alt_true : $JSON::PP::true;
}
elsif($word eq 'null'){
$at += 3;
@@ -1051,7 +1129,7 @@ BEGIN {
if(substr($text,$at,1) eq 'e'){
$at++;
next_chr;
- return $JSON::PP::false;
+ return defined $alt_false ? $alt_false : $JSON::PP::false;
}
}
@@ -1234,18 +1312,27 @@ BEGIN {
if ( $cb_sk_object and @ks == 1 and exists $cb_sk_object->{ $ks[0] } and ref $cb_sk_object->{ $ks[0] } ) {
my @val = $cb_sk_object->{ $ks[0] }->( $o->{$ks[0]} );
- if (@val == 1) {
+ if (@val == 0) {
+ return $o;
+ }
+ elsif (@val == 1) {
return $val[0];
}
+ else {
+ Carp::croak("filter_json_single_key_object callbacks must not return more than one scalar");
+ }
}
my @val = $cb_object->($o) if ($cb_object);
- if (@val == 0 or @val > 1) {
+ if (@val == 0) {
return $o;
}
- else {
+ elsif (@val == 1) {
return $val[0];
}
+ else {
+ Carp::croak("filter_json_object callbacks must not return more than one scalar");
+ }
}
@@ -1407,7 +1494,7 @@ BEGIN {
$JSON::PP::true = do { bless \(my $dummy = 1), "JSON::PP::Boolean" };
$JSON::PP::false = do { bless \(my $dummy = 0), "JSON::PP::Boolean" };
-sub is_bool { blessed $_[0] and $_[0]->isa("JSON::PP::Boolean"); }
+sub is_bool { blessed $_[0] and ( $_[0]->isa("JSON::PP::Boolean") or $_[0]->isa("Types::Serialiser::BooleanBase") or $_[0]->isa("JSON::XS::Boolean") ); }
sub true { $JSON::PP::true }
sub false { $JSON::PP::false }
@@ -1425,6 +1512,8 @@ use constant INCR_M_BS => 2; # inside backslash
use constant INCR_M_JSON => 3; # outside anything, count nesting
use constant INCR_M_C0 => 4;
use constant INCR_M_C1 => 5;
+use constant INCR_M_TFN => 6;
+use constant INCR_M_NUM => 7;
$JSON::PP::IncrParser::VERSION = '1.01';
@@ -1490,7 +1579,7 @@ sub incr_parse {
return @ret;
}
else { # in scalar context
- return $ret[0] ? $ret[0] : undef;
+ return defined $ret[0] ? $ret[0] : undef;
}
}
}
@@ -1538,6 +1627,28 @@ INCR_PARSE:
$p++;
}
next;
+ } elsif ( $mode == INCR_M_TFN ) {
+ while ( $len > $p ) {
+ $s = substr( $text, $p++, 1 );
+ next if defined $s and $s =~ /[rueals]/;
+ last;
+ }
+ $p--;
+ $self->{incr_mode} = INCR_M_JSON;
+
+ last INCR_PARSE unless $self->{incr_nest};
+ redo INCR_PARSE;
+ } elsif ( $mode == INCR_M_NUM ) {
+ while ( $len > $p ) {
+ $s = substr( $text, $p++, 1 );
+ next if defined $s and $s =~ /[0-9eE.+\-]/;
+ last;
+ }
+ $p--;
+ $self->{incr_mode} = INCR_M_JSON;
+
+ last INCR_PARSE unless $self->{incr_nest};
+ redo INCR_PARSE;
} elsif ( $mode == INCR_M_STR ) {
while ( $len > $p ) {
$s = substr( $text, $p, 1 );
@@ -1570,6 +1681,12 @@ INCR_PARSE:
last INCR_PARSE;
}
next;
+ } elsif ( $s eq 't' or $s eq 'f' or $s eq 'n' ) {
+ $self->{incr_mode} = INCR_M_TFN;
+ redo INCR_PARSE;
+ } elsif ( $s =~ /^[0-9\-]$/ ) {
+ $self->{incr_mode} = INCR_M_NUM;
+ redo INCR_PARSE;
} elsif ( $s eq '"' ) {
$self->{incr_mode} = INCR_M_STR;
redo INCR_PARSE;
@@ -1656,20 +1773,18 @@ JSON::PP - JSON::XS compatible pure-Perl module.
=head1 VERSION
- 2.97001
+ 4.02
=head1 DESCRIPTION
-JSON::PP is a pure perl JSON decoder/encoder (as of RFC4627, which
-we know is obsolete but we still stick to; see below for an option
-to support part of RFC7159), and (almost) compatible to much
+JSON::PP is a pure perl JSON decoder/encoder, and (almost) compatible to much
faster L<JSON::XS> written by Marc Lehmann in C. JSON::PP works as
a fallback module when you use L<JSON> module without having
installed JSON::XS.
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 nor support RFC7159/ECMA-404),
+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,
@@ -1734,7 +1849,9 @@ decoding style, within the limits of supported formats.
$json = JSON::PP->new
Creates a new JSON::PP object that can be used to de/encode JSON
-strings. All boolean flags described below are by default I<disabled>.
+strings. All boolean flags described below are by default I<disabled>
+(with the exception of C<allow_nonref>, which defaults to I<enabled> since
+version C<4.0>).
The mutators for flags all return the JSON::PP object again and thus calls can
be chained:
@@ -1963,6 +2080,16 @@ character, after which more white-space and comments are allowed.
// neither this one...
]
+=item * literal ASCII TAB characters in strings
+
+Literal ASCII TAB characters are now allowed in strings (and treated as
+C<\t>).
+
+ [
+ "Hello\tWorld",
+ "Hello<TAB>World", # literal <TAB> would not normally be allowed
+ ]
+
=back
=head2 canonical
@@ -1994,6 +2121,9 @@ This setting has currently no effect on tied hashes.
$enabled = $json->get_allow_nonref
+Unlike other boolean options, this opotion is enabled by default beginning
+with version C<4.0>.
+
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
@@ -2004,15 +2134,15 @@ 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:
+Example, encode a Perl scalar as JSON value without enabled C<allow_nonref>,
+resulting in an error:
- JSON::PP->new->allow_nonref->encode ("Hello, World!")
- => "Hello, World!"
+ JSON::PP->new->allow_nonref(0)->encode ("Hello, World!")
+ => hash- or arrayref expected...
=head2 allow_unknown
- $json = $json->allow_unknown ([$enable])
+ $json = $json->allow_unknown([$enable])
$enabled = $json->get_allow_unknown
@@ -2072,18 +2202,66 @@ this type of conversion.
This setting has no effect on C<decode>.
+=head2 allow_tags
+
+ $json = $json->allow_tags([$enable])
+
+ $enabled = $json->get_allow_tags
+
+See L<OBJECT SERIALISATION> 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 serialise 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 deserialise
+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.
+
+=head2 boolean_values
+
+ $json->boolean_values([$false, $true])
+
+ ($false, $true) = $json->get_boolean_values
+
+By default, JSON booleans will be decoded as overloaded
+C<$JSON::PP::false> and C<$JSON::PP::true> objects.
+
+With this method you can specify your own boolean values for decoding -
+on decode, JSON C<false> will be decoded as a copy of C<$false>, and JSON
+C<true> will be decoded as C<$true> ("copy" here is the same thing as
+assigning a value to another variable, i.e. C<$copy = $false>).
+
+This is useful when you want to pass a decoded data structure directly
+to other serialisers like YAML, Data::MessagePack and so on.
+
+Note that this works only when you C<decode>. You can set incompatible
+boolean objects (like L<boolean>), but when you C<encode> a data structure
+with such boolean objects, you still need to enable C<convert_blessed>
+(and add a C<TO_JSON> method if necessary).
+
+Calling this method without any arguments will reset the booleans
+to their default values.
+
+C<get_boolean_values> will return both C<$false> and C<$true> values, or
+the empty list when they are set to the default.
+
=head2 filter_json_object
$json = $json->filter_json_object([$coderef])
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 deserialised data structure. If it returns
-an empty list (NOTE: I<not> C<undef>, which is a valid scalar), the
-original deserialised hash will be inserted. This setting can slow down
-decoding considerably.
+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: I<not> C<undef>, which is a valid scalar), the original
+deserialised 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 deserialised hash in any
@@ -2091,12 +2269,11 @@ way.
Example, convert all JSON objects into the integer 5:
- my $js = JSON::PP->new->filter_json_object (sub { 5 });
+ my $js = JSON::PP->new->filter_json_object(sub { 5 });
# returns [5]
- $js->decode ('[{}]'); # the given subroutine takes a hash reference.
- # throw an exception because allow_nonref is not enabled
- # so a lone 5 is not allowed.
- $js->decode ('{"a":1, "b":2}');
+ $js->decode('[{}]');
+ # returns 5
+ $js->decode('{"a":1, "b":2}');
=head2 filter_json_single_key_object
@@ -2241,8 +2418,10 @@ and you need to know where the JSON text ends.
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,
-try L<Cpanel::JSON::XS>, a fork of JSON::XS by Reini Urban, which
-supports some of these.
+you might want to try L<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.
=head2 allow_singlequote
@@ -2251,7 +2430,7 @@ supports some of these.
If C<$enable> is true (or missing), then C<decode> will accept
invalid JSON texts that contain strings that begin and end with
-single quotation marks. C<encode> will not be affected in anyway.
+single quotation marks. C<encode> will not be affected in any way.
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
@@ -2272,7 +2451,7 @@ valid JSON texts.
If C<$enable> is true (or missing), then C<decode> will accept
invalid JSON texts that contain JSON objects whose names don't
begin and end with quotation marks. C<encode> will not be affected
-in anyway. I<Be aware that this option makes you accept invalid JSON
+in any way. 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.)
@@ -2307,7 +2486,7 @@ See also L<MAPPING>.
If C<$enable> is true (or missing), then C<decode> will accept
invalid JSON texts that contain unescaped [\x00-\x1f\x22\x5c]
-characters. C<encode> will not be affected in anyway.
+characters. C<encode> will not be affected in any way.
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
@@ -2334,7 +2513,7 @@ 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.
-C<decode> will not be affected in anyway.
+C<decode> will not be affected in any way.
=head2 indent_length
@@ -2577,6 +2756,15 @@ 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 SERIALISATION>, below, for details.
+
=back
@@ -2647,7 +2835,7 @@ before encoding as JSON strings, and anything else as number value:
# undef becomes null
encode_json [undef] # yields [null]
-You can force the type to be a string by stringifying it:
+You can force the type to be a JSON string by stringifying it:
my $x = 3.1; # some variable containing a number
"$x"; # stringified
@@ -2655,13 +2843,23 @@ You can force the type to be a string by stringifying it:
print $x; # perl does it for you, too, quite often
# (but for older perls)
-You can force the type to be a number by numifying it:
+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.
-You cannot currently force the type in other, less obscure, ways.
+You can not currently force the type in other, less obscure, ways.
+
+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
+C<use> JSON::PP (or JSON.pm).
Note that numerical precision has the same meaning as under Perl (so
binary to decimal conversion follows the same rules as in Perl, which
@@ -2688,17 +2886,50 @@ to numify values that may start with values that look like a number
=head2 OBJECT SERIALISATION
-As for Perl objects, JSON::PP only supports a pure JSON representation (without the ability to deserialise the object automatically again).
+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.
=head3 SERIALISATION
What happens when C<JSON::PP> encounters a Perl object depends on the
-C<allow_blessed>, C<convert_blessed> and C<allow_bignum> settings, which are
-used in this order:
+C<allow_blessed>, C<convert_blessed>, C<allow_tags> and C<allow_bignum>
+settings, which are used in this order:
=over 4
-=item 1. C<convert_blessed> is enabled and the object has a C<TO_JSON> method.
+=item 1. C<allow_tags> is enabled and the object has a C<FREEZE> method.
+
+In this case, C<JSON::PP> creates 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 serialise, and the second argument being the
+constant string C<JSON> to distinguish it from other serialisers.
+
+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, $serialiser) = @_;
+
+ ($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
@@ -2713,21 +2944,58 @@ originally were L<URI> objects is lost.
$uri->as_string
}
-=item 2. C<allow_bignum> is enabled and the object is a C<Math::BigInt> or C<Math::BigFloat>.
+=item 3. C<allow_bignum> is enabled and the object is a C<Math::BigInt> or C<Math::BigFloat>.
The object will be serialised as a JSON number value.
-=item 3. C<allow_blessed> is enabled.
+=item 4. C<allow_blessed> is enabled.
The object will be serialised 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<JSON::PP> throws an exception.
=back
+=head3 DESERIALISATION
+
+For deserialisation 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 deserialised, 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: 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<JSON::PP> will look up the C<THAW> 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.
+
+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<allow_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, $serialiser, $type, $id) = @_;
+
+ $class->new (type => $type, id => $id)
+ }
+
+
=head1 ENCODING/CODESET FLAG NOTES
This section is taken from JSON::XS.
@@ -2827,6 +3095,23 @@ proper subset of most 8-bit and multibyte encodings in use in the world.
=back
+=head1 BUGS
+
+Please report bugs on a specific behavior of this module to RT or GitHub
+issues (preferred):
+
+L<https://github.com/makamaka/JSON-PP/issues>
+
+L<https://rt.cpan.org/Public/Dist/Display.html?Queue=JSON-PP>
+
+As for new features and requests to change common behaviors, please
+ask the author of JSON::XS (Marc Lehmann, E<lt>schmorp[at]schmorp.deE<gt>)
+first, by email (important!), to keep compatibility among JSON.pm backends.
+
+Generally speaking, if you need something special for you, you are advised
+to create a new module, maybe based on L<JSON::Tiny>, which is smaller and
+written in a much cleaner way than this module.
+
=head1 SEE ALSO
The F<json_pp> command line utility for quick experiments.
@@ -2838,15 +3123,24 @@ L<JSON::PP::Compat5005> and L<JSON::PP::Compat5006> for older perl users.
RFC4627 (L<http://www.ietf.org/rfc/rfc4627.txt>)
+RFC7159 (L<http://www.ietf.org/rfc/rfc7159.txt>)
+
+RFC8259 (L<http://www.ietf.org/rfc/rfc8259.txt>)
+
=head1 AUTHOR
Makamaka Hannyaharamitu, E<lt>makamaka[at]cpan.orgE<gt>
+=head1 CURRENT MAINTAINER
+
+Kenichi Ishigaki, E<lt>ishigaki[at]cpan.orgE<gt>
=head1 COPYRIGHT AND LICENSE
Copyright 2007-2016 by Makamaka Hannyaharamitu
+Most of the documentation is taken from JSON::XS by Marc Lehmann
+
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
diff --git a/systems/texlive/tlnet/tlpkg/tlperl/lib/JSON/PP/Boolean.pm b/systems/texlive/tlnet/tlpkg/tlperl/lib/JSON/PP/Boolean.pm
index 1d1c5c485c..8b98c95c2f 100644
--- a/systems/texlive/tlnet/tlpkg/tlperl/lib/JSON/PP/Boolean.pm
+++ b/systems/texlive/tlnet/tlpkg/tlperl/lib/JSON/PP/Boolean.pm
@@ -1,14 +1,16 @@
package JSON::PP::Boolean;
use strict;
-use overload (
+require overload;
+local $^W;
+overload::import('overload',
"0+" => sub { ${$_[0]} },
"++" => sub { $_[0] = ${$_[0]} + 1 },
"--" => sub { $_[0] = ${$_[0]} - 1 },
fallback => 1,
);
-$JSON::PP::Boolean::VERSION = '2.97001';
+$JSON::PP::Boolean::VERSION = '4.02';
1;
@@ -31,5 +33,10 @@ L<JSON::PP> for more info about this class.
This idea is from L<JSON::XS::Boolean> written by Marc Lehmann <schmorp[at]schmorp.de>
+=head1 LICENSE
+
+This library is free software; you can redistribute it and/or modify
+it under the same terms as Perl itself.
+
=cut