1package experimental;
2$experimental::VERSION = '0.028';
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	args_array_with_signatures => '5.20.0',
22	array_base      => '5',
23	autoderef       => '5.14.0',
24	bitwise         => '5.22.0',
25	builtin         => '5.35.7',
26	const_attr      => '5.22.0',
27	current_sub     => '5.16.0',
28	declared_refs   => '5.26.0',
29	defer           => '5.35.4',
30	evalbytes       => '5.16.0',
31        extra_paired_delims => '5.35.9',
32	fc              => '5.16.0',
33	for_list        => '5.35.5',
34	isa             => '5.31.7',
35	lexical_topic   => '5.10.0',
36	lexical_subs    => '5.18.0',
37	postderef       => '5.20.0',
38	postderef_qq    => '5.20.0',
39	refaliasing     => '5.22.0',
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',
46	try             => '5.34.0',
47	unicode_eval    => '5.16.0',
48	unicode_strings => '5.12.0',
49);
50my %removed_in_version = (
51	array_base      => '5.30.0',
52	autoderef       => '5.24.0',
53	lexical_topic   => '5.24.0',
54);
55
56$_ = version->new($_) for values %min_version;
57$_ = version->new($_) for values %removed_in_version;
58
59my %additional = (
60	postderef     => ['postderef_qq'],
61	switch        => ['smartmatch'],
62	declared_refs => ['refaliasing'],
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	}
79	elsif ($] < $min_version{$pragma}) {
80		my $stable = $min_version{$pragma}->stringify;
81		$stable =~ s/^ 5\. ([0-9]?[13579]) \. \d+ $/"5." . ($1 + 1) . ".0"/xe;
82		croak "Need perl $stable or later for feature $pragma";
83	}
84	elsif ($] >= ($removed_in_version{$pragma} || 7)) {
85		croak "Experimental feature $pragma has been removed from perl in version $removed_in_version{$pragma}";
86	}
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
139version 0.027
140
141=head1 SYNOPSIS
142
143 use experimental 'lexical_subs', 'signatures';
144 my sub plus_one($value) { $value + 1 }
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
170=over 4
171
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
176=item * C<array_base> - allow the use of C<$[> to change the starting index of C<@array>.
177
178This was removed in perl 5.30.0.
179
180=item * C<autoderef> - allow push, each, keys, and other built-ins on references.
181
182This was added in perl 5.14.0 and removed in perl 5.24.0.
183
184=item * C<bitwise> - allow the new stringwise bit operators
185
186This was added in perl 5.22.0.
187
188=item * C<builtin> - allow the use of the functions in the builtin:: namespace
189
190This was added in perl 5.36.0
191
192=item * C<const_attr> - allow the :const attribute on subs
193
194This was added in perl 5.22.0.
195
196=item * C<declared_refs> - enables aliasing via assignment to references
197
198This was added in perl 5.26.0.
199
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
208=item * C<isa> - allow the use of the C<isa> infix operator
209
210This was added in perl 5.32.0.
211
212=item * C<lexical_topic> - allow the use of lexical C<$_> via C<my $_>.
213
214This was added in perl 5.10.0 and removed in perl 5.24.0.
215
216=item * C<lexical_subs> - allow the use of lexical subroutines.
217
218This was added in 5.18.0.
219
220=item * C<postderef> - allow the use of postfix dereferencing expressions
221
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.
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
253=item * C<try> - allow the use of C<try> and C<catch>
254
255This was added in perl 5.34.0
256
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
262
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
283=head2 Disclaimer
284
285Because of the nature of the features it enables, forward compatibility can not
286be guaranteed in any way.
287
288=head1 SEE ALSO
289
290L<perlexperiment|perlexperiment> contains more information about experimental features.
291
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
304