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