experimental: sync with CPAN version 0.031

From Changes:

- Fix the name of the extra_paired_delimiters feature (previously
  mis-documented as extra_paired_delims)

- Added "stable.pm", which acts like experimental.pm only for features which
  have been marked non-experimental in their current form, in later version of
perl.

5 files changed, 167 insertions, 6 deletions

diff --git a/MANIFEST b/MANIFEST
index d3a0655072..8d3a39b94c 100644
--- a/MANIFEST
+++ b/MANIFEST
@@ -794,6 +794,7 @@ cpan/Encode/Unicode/Makefile.PL		Encode extension
 cpan/Encode/Unicode/Unicode.pm		Encode extension
 cpan/Encode/Unicode/Unicode.xs		Encode extension
 cpan/experimental/lib/experimental.pm
+cpan/experimental/lib/stable.pm
 cpan/experimental/t/basic.t
 cpan/ExtUtils-Constant/lib/ExtUtils/Constant.pm			generate XS code to import C header constants
 cpan/ExtUtils-Constant/lib/ExtUtils/Constant/Base.pm		generate XS code to import C header constants
diff --git a/Porting/Maintainers.pl b/Porting/Maintainers.pl
index 180506c41a..9150918977 100755
--- a/Porting/Maintainers.pl
+++ b/Porting/Maintainers.pl
@@ -413,7 +413,7 @@ use File::Glob qw(:case);
     },
 
     'experimental' => {
-        'DISTRIBUTION' => 'LEONT/experimental-0.030.tar.gz',
+        'DISTRIBUTION' => 'LEONT/experimental-0.031.tar.gz',
         'FILES'        => q[cpan/experimental],
         'EXCLUDED'     => [qr{^xt/}],
     },
diff --git a/cpan/experimental/lib/experimental.pm b/cpan/experimental/lib/experimental.pm
index 608b02e7a1..3d89cbd5b1 100644
--- a/cpan/experimental/lib/experimental.pm
+++ b/cpan/experimental/lib/experimental.pm
@@ -1,5 +1,5 @@
 package experimental;
-$experimental::VERSION = '0.030';
+$experimental::VERSION = '0.031';
 use strict;
 use warnings;
 use version ();
@@ -29,7 +29,7 @@ my %min_version = (
 	declared_refs   => '5.26.0',
 	defer           => '5.35.4',
 	evalbytes       => '5.16.0',
-	extra_paired_delims => '5.35.9',
+	extra_paired_delimiters => '5.35.9',
 	fc              => '5.16.0',
 	for_list        => '5.35.5',
 	isa             => '5.31.7',
@@ -140,7 +140,7 @@ experimental - Experimental features made easy
 
 =head1 VERSION
 
-version 0.030
+version 0.031
 
 =head1 SYNOPSIS
 
@@ -205,7 +205,7 @@ This was added in perl 5.26.0.
 
 This was added in perl 5.36.0
 
-=item * C<extra_paired_delims> - enables the use of more paired string delimiters than the
+=item * C<extra_paired_delimiters> - enables the use of more paired string delimiters than the
 traditional four, S<C<< <  > >>>, S<C<( )>>, S<C<{ }>>, and S<C<[ ]>>.
 
 This was added in perl 5.36.
@@ -224,7 +224,7 @@ This was added in perl 5.10.0 and removed in perl 5.24.0.
 
 =item * C<lexical_subs> - allow the use of lexical subroutines.
 
-This was added in 5.18.0.
+This was added in 5.18.0, and became non-experimental (and always enabled) in 5.26.0.
 
 =item * C<postderef> - allow the use of postfix dereferencing expressions
 
diff --git a/cpan/experimental/lib/stable.pm b/cpan/experimental/lib/stable.pm
new file mode 100644
index 0000000000..7922a2e91b
--- /dev/null
+++ b/cpan/experimental/lib/stable.pm
@@ -0,0 +1,159 @@
+package stable;
+$stable::VERSION = '0.031';
+use strict;
+use warnings;
+use version ();
+
+use experimental ();
+use Carp qw/croak carp/;
+
+my %allow_at = (
+	bitwise       => 5.022000,
+	isa           => 5.032000,
+	lexical_subs  => 5.022000,
+	postderef     => 5.020000,
+);
+
+sub import {
+	my ($self, @pragmas) = @_;
+
+	for my $pragma (@pragmas) {
+		my $min_ver = $allow_at{$pragma};
+		croak "unknown stablized experiment $pragma" unless defined $min_ver;
+		croak "requested stablized experiment $pragma, which is stable at $min_ver but this is $]"
+			unless $] >= $min_ver;
+	}
+
+	experimental->import(@pragmas);
+	return;
+}
+
+sub unimport {
+	my ($self, @pragmas) = @_;
+
+	# Look, we could say "You can't unimport stable experiment 'bitwise' on
+	# 5.20" but it just seems weird. -- rjbs, 2022-03-05
+	experimental->unimport(@pragmas);
+	return;
+}
+
+1;
+
+#ABSTRACT: Experimental features made easy, once we know they're stable
+
+__END__
+
+=pod
+
+=encoding UTF-8
+
+=head1 NAME
+
+stable - Experimental features made easy, once we know they're stable
+
+=head1 VERSION
+
+version 0.031
+
+=head1 SYNOPSIS
+
+	use stable 'lexical_subs', 'bitwise';
+	my sub is_odd($value) { $value & 1 }
+
+=head1 DESCRIPTION
+
+The L<experimental> pragma makes it easy to turn on experimental while turning
+off associated warnings.  You should read about it, if you don't already know
+what it does.
+
+Seeing C<use experimental> in code might be scary.  In fact, it probably should
+be!  Code that uses experimental features might break in the future if the perl
+development team decides that the experiment needs to be altered.  When
+experiments become stable, because the developers decide they're a success, the
+warnings associated with them go away.  When that happens, they can generally
+be turned on with C<use feature>.
+
+This is great, if you are using a version of perl where the feature you want is
+already stable.  If you're using an older perl, though, it might be the case
+that you want to use an experimental feature that still warns, even though
+there's no risk in using it, because subsequent versions of perl have that
+feature unchanged and now stable.
+
+Here's an example:  The C<postderef> feature was added in perl 5.20.0.  In perl
+5.24.0, it was marked stable.  Using it would no longer trigger a warning.  The
+behavior of the feature didn't change between 5.20.0 and 5.24.0.  That means
+that it's perfectly safe to use the feature on 5.20 or 5.22, even though
+there's a warning.
+
+In that case, you could very justifiably add C<use experimental 'postderef'>
+but the casual reader may still be worried at seeing that.  The C<stable>
+pragma exists to turn on experimental features only when it's known that
+their behavior in the running perl is their stable behavior.
+
+If you try to use an experimental feature that isn't stable or available on
+the running version of perl, an exception will be thrown.  You should also take
+care that you've required the version of C<stable> that you need!
+
+If it's not immediately obvious why, here's a bit of explanation:
+
+=over 4
+
+=item *
+
+C<stable> comes with perl, starting with perl v5.38.
+
+=item *
+
+Imagine that v5.38 adds a feature called "florps".  It will stop being
+experimental in v5.42.
+
+=item *
+
+The version of C<stable> that comes with perl v5.38 can't know that the
+I<florps> experiment will succeed, so you can't C<use stable 'florps'> on the
+version of stable ships with v5.38, because it can't see the future!
+
+=item *
+
+You'll need to write C<use stable 1.234 'florps'> to say that you need version
+1.234 of stable, which is when I<florps> became known to stable.
+
+=back
+
+Sure, it's a little weird, but it's worth it!  The documentation of this pragma
+will tell you what version of C<stable> you need to require in order to use
+various features.  See below.
+
+At present there are only a few "stable" features:
+
+=over 4
+
+=item * C<bitwise> - stable as of perl 5.22, available via stable 0.031
+
+=item * C<isa> - stable as of perl 5.32, available via stable 0.031
+
+=item * C<lexical_subs> - stable as of perl 5.22, available via stable 0.031
+
+Lexical subroutines were actually added in 5.18, and their design did not
+change, but significant bugs makes them unsafe to use before 5.22.
+
+=item * C<postderef> - stable as of perl 5.20, available via stable 0.031
+
+=back
+
+=head1 SEE ALSO
+
+L<perlexperiment|perlexperiment> contains more information about experimental features.
+
+=head1 AUTHOR
+
+Leon Timmermans <leont@cpan.org>
+
+=head1 COPYRIGHT AND LICENSE
+
+This software is copyright (c) 2013 by Leon Timmermans.
+
+This is free software; you can redistribute it and/or modify it under
+the same terms as the Perl 5 programming language system itself.
+
+=cut
diff --git a/lib/.gitignore b/lib/.gitignore
index cb6a26cfcc..7feacc5ceb 100644
--- a/lib/.gitignore
+++ b/lib/.gitignore
@@ -222,6 +222,7 @@
 /perlxstut.pod
 /perlxstypemap.pod
 /re.pm
+/stable.pm
 /threads.pm
 /threads/
 /version.pm