"Fossies" - the Fresh Open Source Software Archive

Member "install-tl-20200916/tlpkg/tlperl/lib/experimental.pm" (7 Mar 2020, 7064 Bytes) of package /windows/misc/install-tl.zip:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) Perl source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file.

    1 package experimental;
    2 $experimental::VERSION = '0.020';
    3 use strict;
    4 use warnings;
    5 use version ();
    6 
    7 BEGIN { eval { require feature } };
    8 use Carp qw/croak carp/;
    9 
   10 my %warnings = map { $_ => 1 } grep { /^experimental::/ } keys %warnings::Offsets;
   11 my %features = map { $_ => 1 } $] > 5.015006 ? keys %feature::feature : do {
   12     my @features;
   13     if ($] >= 5.010) {
   14         push @features, qw/switch say state/;
   15         push @features, 'unicode_strings' if $] > 5.011002;
   16     }
   17     @features;
   18 };
   19 
   20 my %min_version = (
   21     array_base      => '5',
   22     autoderef       => '5.14.0',
   23     bitwise         => '5.22.0',
   24     const_attr      => '5.22.0',
   25     current_sub     => '5.16.0',
   26     declared_refs   => '5.26.0',
   27     evalbytes       => '5.16.0',
   28     fc              => '5.16.0',
   29     lexical_topic   => '5.10.0',
   30     lexical_subs    => '5.18.0',
   31     postderef       => '5.20.0',
   32     postderef_qq    => '5.20.0',
   33     refaliasing     => '5.22.0',
   34     regex_sets      => '5.18.0',
   35     say             => '5.10.0',
   36     smartmatch      => '5.10.0',
   37     signatures      => '5.20.0',
   38     state           => '5.10.0',
   39     switch          => '5.10.0',
   40     unicode_eval    => '5.16.0',
   41     unicode_strings => '5.12.0',
   42 );
   43 my %max_version = (
   44     autoderef       => '5.23.1',
   45     lexical_topic   => '5.23.4',
   46 );
   47 
   48 $_ = version->new($_) for values %min_version;
   49 $_ = version->new($_) for values %max_version;
   50 
   51 my %additional = (
   52     postderef     => ['postderef_qq'],
   53     switch        => ['smartmatch'],
   54     declared_refs => ['refaliasing'],
   55 );
   56 
   57 sub _enable {
   58     my $pragma = shift;
   59     if ($warnings{"experimental::$pragma"}) {
   60         warnings->unimport("experimental::$pragma");
   61         feature->import($pragma) if exists $features{$pragma};
   62         _enable(@{ $additional{$pragma} }) if $additional{$pragma};
   63     }
   64     elsif ($features{$pragma}) {
   65         feature->import($pragma);
   66         _enable(@{ $additional{$pragma} }) if $additional{$pragma};
   67     }
   68     elsif (not exists $min_version{$pragma}) {
   69         croak "Can't enable unknown feature $pragma";
   70     }
   71     elsif ($] < $min_version{$pragma}) {
   72         my $stable = $min_version{$pragma};
   73         if ($stable->{version}[1] % 2) {
   74             $stable = version->new(
   75                 "5.".($stable->{version}[1]+1).'.0'
   76             );
   77         }
   78         croak "Need perl $stable or later for feature $pragma";
   79     }
   80     elsif ($] >= ($max_version{$pragma} || 7)) {
   81         croak "Experimental feature $pragma has been removed from perl in version $max_version{$pragma}";
   82     }
   83 }
   84 
   85 sub import {
   86     my ($self, @pragmas) = @_;
   87 
   88     for my $pragma (@pragmas) {
   89         _enable($pragma);
   90     }
   91     return;
   92 }
   93 
   94 sub _disable {
   95     my $pragma = shift;
   96     if ($warnings{"experimental::$pragma"}) {
   97         warnings->import("experimental::$pragma");
   98         feature->unimport($pragma) if exists $features{$pragma};
   99         _disable(@{ $additional{$pragma} }) if $additional{$pragma};
  100     }
  101     elsif ($features{$pragma}) {
  102         feature->unimport($pragma);
  103         _disable(@{ $additional{$pragma} }) if $additional{$pragma};
  104     }
  105     elsif (not exists $min_version{$pragma}) {
  106         carp "Can't disable unknown feature $pragma, ignoring";
  107     }
  108 }
  109 
  110 sub unimport {
  111     my ($self, @pragmas) = @_;
  112 
  113     for my $pragma (@pragmas) {
  114         _disable($pragma);
  115     }
  116     return;
  117 }
  118 
  119 1;
  120 
  121 #ABSTRACT: Experimental features made easy
  122 
  123 __END__
  124 
  125 =pod
  126 
  127 =encoding UTF-8
  128 
  129 =head1 NAME
  130 
  131 experimental - Experimental features made easy
  132 
  133 =head1 VERSION
  134 
  135 version 0.020
  136 
  137 =head1 SYNOPSIS
  138 
  139  use experimental 'lexical_subs', 'smartmatch';
  140  my sub foo { $_[0] ~~ 1 }
  141 
  142 =head1 DESCRIPTION
  143 
  144 This pragma provides an easy and convenient way to enable or disable
  145 experimental features.
  146 
  147 Every version of perl has some number of features present but considered
  148 "experimental."  For much of the life of Perl 5, this was only a designation
  149 found in the documentation.  Starting in Perl v5.10.0, and more aggressively in
  150 v5.18.0, experimental features were placed behind pragmata used to enable the
  151 feature and disable associated warnings.
  152 
  153 The C<experimental> pragma exists to combine the required incantations into a
  154 single interface stable across releases of perl.  For every experimental
  155 feature, this should enable the feature and silence warnings for the enclosing
  156 lexical scope:
  157 
  158   use experimental 'feature-name';
  159 
  160 To disable the feature and, if applicable, re-enable any warnings, use:
  161 
  162   no experimental 'feature-name';
  163 
  164 The supported features, documented further below, are:
  165 
  166 =over 4
  167 
  168 =item * C<array_base> - allow the use of C<$[> to change the starting index of C<@array>.
  169 
  170 This is supported on all versions of perl.
  171 
  172 =item * C<autoderef> - allow push, each, keys, and other built-ins on references.
  173 
  174 This was added in perl 5.14.0 and removed in perl 5.23.1.
  175 
  176 =item * C<bitwise> - allow the new stringwise bit operators
  177 
  178 This was added in perl 5.22.0.
  179 
  180 =item * C<const_attr> - allow the :const attribute on subs
  181 
  182 This was added in perl 5.22.0.
  183 
  184 =item * C<lexical_topic> - allow the use of lexical C<$_> via C<my $_>.
  185 
  186 This was added in perl 5.10.0 and removed in perl 5.23.4.
  187 
  188 =item * C<lexical_subs> - allow the use of lexical subroutines.
  189 
  190 This was added in 5.18.0.
  191 
  192 =item * C<postderef> - allow the use of postfix dereferencing expressions,
  193 including in interpolating strings
  194 
  195 This was added in perl 5.20.0.
  196 
  197 =item * C<re_strict> - enables strict mode in regular expressions
  198 
  199 This was added in perl 5.22.0.
  200 
  201 =item * C<refaliasing> - allow aliasing via C<\$x = \$y>
  202 
  203 This was added in perl 5.22.0.
  204 
  205 =item * C<regex_sets> - allow extended bracketed character classes in regexps
  206 
  207 This was added in perl 5.18.0.
  208 
  209 =item * C<signatures> - allow subroutine signatures (for named arguments)
  210 
  211 This was added in perl 5.20.0.
  212 
  213 =item * C<smartmatch> - allow the use of C<~~>
  214 
  215 This was added in perl 5.10.0, but it should be noted there are significant
  216 incompatibilities between 5.10.0 and 5.10.1.
  217 
  218 =item * C<switch> - allow the use of C<~~>, given, and when
  219 
  220 This was added in perl 5.10.0.
  221 
  222 =item * C<win32_perlio> - allows the use of the :win32 IO layer.
  223 
  224 This was added on perl 5.22.0.
  225 
  226 =back
  227 
  228 =head2 Ordering matters
  229 
  230 Using this pragma to 'enable an experimental feature' is another way of saying
  231 that this pragma will disable the warnings which would result from using that
  232 feature.  Therefore, the order in which pragmas are applied is important.  In
  233 particular, you probably want to enable experimental features I<after> you
  234 enable warnings:
  235 
  236   use warnings;
  237   use experimental 'smartmatch';
  238 
  239 You also need to take care with modules that enable warnings for you.  A common
  240 example being Moose.  In this example, warnings for the 'smartmatch' feature are
  241 first turned on by the warnings pragma, off by the experimental pragma and back
  242 on again by the Moose module (fix is to switch the last two lines):
  243 
  244   use warnings;
  245   use experimental 'smartmatch';
  246   use Moose;
  247 
  248 =head2 Disclaimer
  249 
  250 Because of the nature of the features it enables, forward compatibility can not
  251 be guaranteed in any way.
  252 
  253 =head1 SEE ALSO
  254 
  255 L<perlexperimental|perlexperimental> contains more information about experimental features.
  256 
  257 =head1 AUTHOR
  258 
  259 Leon Timmermans <leont@cpan.org>
  260 
  261 =head1 COPYRIGHT AND LICENSE
  262 
  263 This software is copyright (c) 2013 by Leon Timmermans.
  264 
  265 This is free software; you can redistribute it and/or modify it under
  266 the same terms as the Perl 5 programming language system itself.
  267 
  268 =cut