This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Update Encode from version 3.06 to 3.07
[perl5.git] / cpan / experimental / lib / experimental.pm
CommitLineData
de84ff2b 1package experimental;
b4d728a5 2$experimental::VERSION = '0.020';
de84ff2b
RS
3use strict;
4use warnings;
edd0583e 5use version ();
de84ff2b 6
62805098 7BEGIN { eval { require feature } };
de84ff2b
RS
8use Carp qw/croak carp/;
9
10my %warnings = map { $_ => 1 } grep { /^experimental::/ } keys %warnings::Offsets;
f8c3bb9c
CBW
11my %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};
de84ff2b
RS
19
20my %min_version = (
f8c3bb9c
CBW
21 array_base => '5',
22 autoderef => '5.14.0',
af9caa01 23 bitwise => '5.22.0',
b065a895 24 const_attr => '5.22.0',
f8c3bb9c 25 current_sub => '5.16.0',
b4d728a5 26 declared_refs => '5.26.0',
f8c3bb9c
CBW
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',
af9caa01 33 refaliasing => '5.22.0',
f8c3bb9c
CBW
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',
de84ff2b 42);
61030386 43my %max_version = (
b065a895 44 autoderef => '5.23.1',
61030386
CBW
45 lexical_topic => '5.23.4',
46);
47
f8c3bb9c 48$_ = version->new($_) for values %min_version;
4fdcb09b 49$_ = version->new($_) for values %max_version;
de84ff2b
RS
50
51my %additional = (
b4d728a5
SH
52 postderef => ['postderef_qq'],
53 switch => ['smartmatch'],
54 declared_refs => ['refaliasing'],
de84ff2b
RS
55);
56
57sub _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 }
61030386 71 elsif ($] < $min_version{$pragma}) {
9c71c2c5
CBW
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";
de84ff2b 79 }
4fdcb09b
SH
80 elsif ($] >= ($max_version{$pragma} || 7)) {
81 croak "Experimental feature $pragma has been removed from perl in version $max_version{$pragma}";
82 }
de84ff2b
RS
83}
84
85sub import {
86 my ($self, @pragmas) = @_;
87
88 for my $pragma (@pragmas) {
89 _enable($pragma);
90 }
91 return;
92}
93
94sub _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
110sub unimport {
111 my ($self, @pragmas) = @_;
112
113 for my $pragma (@pragmas) {
114 _disable($pragma);
115 }
116 return;
117}
118
1191;
120
121#ABSTRACT: Experimental features made easy
122
123__END__
124
125=pod
126
127=encoding UTF-8
128
129=head1 NAME
130
131experimental - Experimental features made easy
132
133=head1 VERSION
134
b4d728a5 135version 0.020
de84ff2b
RS
136
137=head1 SYNOPSIS
138
139 use experimental 'lexical_subs', 'smartmatch';
140 my sub foo { $_[0] ~~ 1 }
141
142=head1 DESCRIPTION
143
144This pragma provides an easy and convenient way to enable or disable
145experimental features.
146
147Every 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
149found in the documentation. Starting in Perl v5.10.0, and more aggressively in
150v5.18.0, experimental features were placed behind pragmata used to enable the
151feature and disable associated warnings.
152
153The C<experimental> pragma exists to combine the required incantations into a
154single interface stable across releases of perl. For every experimental
155feature, this should enable the feature and silence warnings for the enclosing
156lexical scope:
157
158 use experimental 'feature-name';
159
160To disable the feature and, if applicable, re-enable any warnings, use:
161
162 no experimental 'feature-name';
163
164The supported features, documented further below, are:
165
b065a895
S
166=over 4
167
168=item * C<array_base> - allow the use of C<$[> to change the starting index of C<@array>.
169
170This is supported on all versions of perl.
171
172=item * C<autoderef> - allow push, each, keys, and other built-ins on references.
173
174This 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
178This was added in perl 5.22.0.
179
180=item * C<const_attr> - allow the :const attribute on subs
181
182This was added in perl 5.22.0.
183
184=item * C<lexical_topic> - allow the use of lexical C<$_> via C<my $_>.
185
186This 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
190This was added in 5.18.0.
191
192=item * C<postderef> - allow the use of postfix dereferencing expressions,
193including in interpolating strings
194
195This was added in perl 5.20.0.
196
197=item * C<re_strict> - enables strict mode in regular expressions
198
199This was added in perl 5.22.0.
200
201=item * C<refaliasing> - allow aliasing via C<\$x = \$y>
202
203This was added in perl 5.22.0.
204
205=item * C<regex_sets> - allow extended bracketed character classes in regexps
206
207This was added in perl 5.18.0.
208
209=item * C<signatures> - allow subroutine signatures (for named arguments)
210
211This was added in perl 5.20.0.
212
213=item * C<smartmatch> - allow the use of C<~~>
214
215This was added in perl 5.10.0, but it should be noted there are significant
216incompatibilities between 5.10.0 and 5.10.1.
217
218=item * C<switch> - allow the use of C<~~>, given, and when
219
220This was added in perl 5.10.0.
221
222=item * C<win32_perlio> - allows the use of the :win32 IO layer.
223
224This was added on perl 5.22.0.
225
226=back
de84ff2b 227
4177cbce
CBW
228=head2 Ordering matters
229
230Using this pragma to 'enable an experimental feature' is another way of saying
231that this pragma will disable the warnings which would result from using that
232feature. Therefore, the order in which pragmas are applied is important. In
233particular, you probably want to enable experimental features I<after> you
234enable warnings:
235
236 use warnings;
237 use experimental 'smartmatch';
238
239You also need to take care with modules that enable warnings for you. A common
240example being Moose. In this example, warnings for the 'smartmatch' feature are
241first turned on by the warnings pragma, off by the experimental pragma and back
242on 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
de84ff2b
RS
248=head2 Disclaimer
249
250Because of the nature of the features it enables, forward compatibility can not
251be guaranteed in any way.
252
b065a895
S
253=head1 SEE ALSO
254
255L<perlexperimental|perlexperimental> contains more information about experimental features.
256
de84ff2b
RS
257=head1 AUTHOR
258
259Leon Timmermans <leont@cpan.org>
260
261=head1 COPYRIGHT AND LICENSE
262
263This software is copyright (c) 2013 by Leon Timmermans.
264
265This is free software; you can redistribute it and/or modify it under
266the same terms as the Perl 5 programming language system itself.
267
268=cut