This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Update experimental to CPAN version 0.019
[perl5.git] / cpan / experimental / lib / experimental.pm
index 10a6a10..6c0b49e 100644 (file)
@@ -1,10 +1,10 @@
 package experimental;
-$experimental::VERSION = '0.010';
+$experimental::VERSION = '0.019';
 use strict;
 use warnings;
 use version ();
 
-use feature ();
+BEGIN { eval { require feature } };
 use Carp qw/croak carp/;
 
 my %warnings = map { $_ => 1 } grep { /^experimental::/ } keys %warnings::Offsets;
@@ -20,6 +20,8 @@ my %features = map { $_ => 1 } $] > 5.015006 ? keys %feature::feature : do {
 my %min_version = (
        array_base      => '5',
        autoderef       => '5.14.0',
+       bitwise         => '5.22.0',
+       const_attr      => '5.22.0',
        current_sub     => '5.16.0',
        evalbytes       => '5.16.0',
        fc              => '5.16.0',
@@ -27,6 +29,7 @@ my %min_version = (
        lexical_subs    => '5.18.0',
        postderef       => '5.20.0',
        postderef_qq    => '5.20.0',
+       refaliasing     => '5.22.0',
        regex_sets      => '5.18.0',
        say             => '5.10.0',
        smartmatch      => '5.10.0',
@@ -36,7 +39,13 @@ my %min_version = (
        unicode_eval    => '5.16.0',
        unicode_strings => '5.12.0',
 );
+my %max_version = (
+       autoderef       => '5.23.1',
+       lexical_topic   => '5.23.4',
+);
+
 $_ = version->new($_) for values %min_version;
+$_ = version->new($_) for values %max_version;
 
 my %additional = (
        postderef  => ['postderef_qq'],
@@ -57,8 +66,17 @@ sub _enable {
        elsif (not exists $min_version{$pragma}) {
                croak "Can't enable unknown feature $pragma";
        }
-       elsif ($min_version{$pragma} > $]) {
-               croak "Need perl $min_version{$pragma} or later for feature $pragma";
+       elsif ($] < $min_version{$pragma}) {
+               my $stable = $min_version{$pragma};
+               if ($stable->{version}[1] % 2) {
+                       $stable = version->new(
+                               "5.".($stable->{version}[1]+1).'.0'
+                       );
+               }
+               croak "Need perl $stable or later for feature $pragma";
+       }
+       elsif ($] >= ($max_version{$pragma} || 7)) {
+               croak "Experimental feature $pragma has been removed from perl in version $max_version{$pragma}";
        }
 }
 
@@ -112,7 +130,7 @@ experimental - Experimental features made easy
 
 =head1 VERSION
 
-version 0.010
+version 0.019
 
 =head1 SYNOPSIS
 
@@ -143,21 +161,97 @@ To disable the feature and, if applicable, re-enable any warnings, use:
 
 The supported features, documented further below, are:
 
-       array_base    - allow the use of $[ to change the starting index of @array
-       autoderef     - allow push, each, keys, and other built-ins on references
-       lexical_topic - allow the use of lexical $_ via "my $_"
-       postderef     - allow the use of postfix dereferencing expressions, including
-                       in interpolating strings
-       regex_sets    - allow extended bracketed character classes in regexps
-       signatures    - allow subroutine signatures (for named arguments)
-       smartmatch    - allow the use of ~~
-       switch        - allow the use of ~~, given, and when
+=over 4
+
+=item * C<array_base> - allow the use of C<$[> to change the starting index of C<@array>.
+
+This is supported on all versions of perl.
+
+=item * C<autoderef> - allow push, each, keys, and other built-ins on references.
+
+This was added in perl 5.14.0 and removed in perl 5.23.1.
+
+=item * C<bitwise> - allow the new stringwise bit operators
+
+This was added in perl 5.22.0.
+
+=item * C<const_attr> - allow the :const attribute on subs
+
+This was added in perl 5.22.0.
+
+=item * C<lexical_topic> - allow the use of lexical C<$_> via C<my $_>.
+
+This was added in perl 5.10.0 and removed in perl 5.23.4.
+
+=item * C<lexical_subs> - allow the use of lexical subroutines.
+
+This was added in 5.18.0.
+
+=item * C<postderef> - allow the use of postfix dereferencing expressions,
+including in interpolating strings
+
+This was added in perl 5.20.0.
+
+=item * C<re_strict> - enables strict mode in regular expressions
+
+This was added in perl 5.22.0.
+
+=item * C<refaliasing> - allow aliasing via C<\$x = \$y>
+
+This was added in perl 5.22.0.
+
+=item * C<regex_sets> - allow extended bracketed character classes in regexps
+
+This was added in perl 5.18.0.
+
+=item * C<signatures> - allow subroutine signatures (for named arguments)
+
+This was added in perl 5.20.0.
+
+=item * C<smartmatch> - allow the use of C<~~>
+
+This was added in perl 5.10.0, but it should be noted there are significant
+incompatibilities between 5.10.0 and 5.10.1.
+
+=item * C<switch> - allow the use of C<~~>, given, and when
+
+This was added in perl 5.10.0.
+
+=item * C<win32_perlio> - allows the use of the :win32 IO layer.
+
+This was added on perl 5.22.0.
+
+=back
+
+=head2 Ordering matters
+
+Using this pragma to 'enable an experimental feature' is another way of saying
+that this pragma will disable the warnings which would result from using that
+feature.  Therefore, the order in which pragmas are applied is important.  In
+particular, you probably want to enable experimental features I<after> you
+enable warnings:
+
+  use warnings;
+  use experimental 'smartmatch';
+
+You also need to take care with modules that enable warnings for you.  A common
+example being Moose.  In this example, warnings for the 'smartmatch' feature are
+first turned on by the warnings pragma, off by the experimental pragma and back
+on again by the Moose module (fix is to switch the last two lines):
+
+  use warnings;
+  use experimental 'smartmatch';
+  use Moose;
 
 =head2 Disclaimer
 
 Because of the nature of the features it enables, forward compatibility can not
 be guaranteed in any way.
 
+=head1 SEE ALSO
+
+L<perlexperimental|perlexperimental> contains more information about experimental features.
+
 =head1 AUTHOR
 
 Leon Timmermans <leont@cpan.org>