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