1package experimental;
2$experimental::VERSION = '0.020';
3use strict;
4use warnings;
5use version ();
6
7BEGIN { eval { require feature } };
8use Carp qw/croak carp/;
9
10my %warnings = map { $_ => 1 } grep { /^experimental::/ } keys %warnings::Offsets;
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};
19
20my %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);
43my %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
51my %additional = (
52	postderef     => ['postderef_qq'],
53	switch        => ['smartmatch'],
54	declared_refs => ['refaliasing'],
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	}
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
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
135version 0.020
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
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
227
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
248=head2 Disclaimer
249
250Because of the nature of the features it enables, forward compatibility can not
251be guaranteed in any way.
252
253=head1 SEE ALSO
254
255L<perlexperimental|perlexperimental> contains more information about experimental features.
256
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
269