This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
autodoc.pl: Properly handle a single column
[perl5.git] / cpan / experimental / lib / experimental.pm
1 package experimental;
2 $experimental::VERSION = '0.028';
3 use strict;
4 use warnings;
5 use version ();
6
7 BEGIN { eval { require feature } };
8 use Carp qw/croak carp/;
9
10 my %warnings = map { $_ => 1 } grep { /^experimental::/ } keys %warnings::Offsets;
11 my %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
20 my %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 );
50 my %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
59 my %additional = (
60         postderef     => ['postderef_qq'],
61         switch        => ['smartmatch'],
62         declared_refs => ['refaliasing'],
63 );
64
65 sub _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
89 sub import {
90         my ($self, @pragmas) = @_;
91
92         for my $pragma (@pragmas) {
93                 _enable($pragma);
94         }
95         return;
96 }
97
98 sub _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
114 sub unimport {
115         my ($self, @pragmas) = @_;
116
117         for my $pragma (@pragmas) {
118                 _disable($pragma);
119         }
120         return;
121 }
122
123 1;
124
125 #ABSTRACT: Experimental features made easy
126
127 __END__
128
129 =pod
130
131 =encoding UTF-8
132
133 =head1 NAME
134
135 experimental - Experimental features made easy
136
137 =head1 VERSION
138
139 version 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
148 This pragma provides an easy and convenient way to enable or disable
149 experimental features.
150
151 Every 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
153 found in the documentation.  Starting in Perl v5.10.0, and more aggressively in
154 v5.18.0, experimental features were placed behind pragmata used to enable the
155 feature and disable associated warnings.
156
157 The C<experimental> pragma exists to combine the required incantations into a
158 single interface stable across releases of perl.  For every experimental
159 feature, this should enable the feature and silence warnings for the enclosing
160 lexical scope:
161
162   use experimental 'feature-name';
163
164 To disable the feature and, if applicable, re-enable any warnings, use:
165
166   no experimental 'feature-name';
167
168 The 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
174 This 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
178 This was removed in perl 5.30.0.
179
180 =item * C<autoderef> - allow push, each, keys, and other built-ins on references.
181
182 This 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
186 This was added in perl 5.22.0.
187
188 =item * C<builtin> - allow the use of the functions in the builtin:: namespace
189
190 This was added in perl 5.36.0
191
192 =item * C<const_attr> - allow the :const attribute on subs
193
194 This was added in perl 5.22.0.
195
196 =item * C<declared_refs> - enables aliasing via assignment to references
197
198 This was added in perl 5.26.0.
199
200 =item * C<defer> - enables the use of defer blocks
201
202 This 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
206 This was added in perl 5.36.0
207
208 =item * C<isa> - allow the use of the C<isa> infix operator
209
210 This was added in perl 5.32.0.
211
212 =item * C<lexical_topic> - allow the use of lexical C<$_> via C<my $_>.
213
214 This 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
218 This was added in 5.18.0.
219
220 =item * C<postderef> - allow the use of postfix dereferencing expressions
221
222 This 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
226 This 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
230 This was added in perl 5.22.0.
231
232 =item * C<refaliasing> - allow aliasing via C<\$x = \$y>
233
234 This was added in perl 5.22.0.
235
236 =item * C<regex_sets> - allow extended bracketed character classes in regexps
237
238 This was added in perl 5.18.0.
239
240 =item * C<signatures> - allow subroutine signatures (for named arguments)
241
242 This was added in perl 5.20.0.
243
244 =item * C<smartmatch> - allow the use of C<~~>
245
246 This was added in perl 5.10.0, but it should be noted there are significant
247 incompatibilities between 5.10.0 and 5.10.1.
248
249 =item * C<switch> - allow the use of C<~~>, given, and when
250
251 This was added in perl 5.10.0.
252
253 =item * C<try> - allow the use of C<try> and C<catch>
254
255 This was added in perl 5.34.0
256
257 =item * C<win32_perlio> - allows the use of the :win32 IO layer.
258
259 This was added on perl 5.22.0.
260
261 =back
262
263 =head2 Ordering matters
264
265 Using this pragma to 'enable an experimental feature' is another way of saying
266 that this pragma will disable the warnings which would result from using that
267 feature.  Therefore, the order in which pragmas are applied is important.  In
268 particular, you probably want to enable experimental features I<after> you
269 enable warnings:
270
271   use warnings;
272   use experimental 'smartmatch';
273
274 You also need to take care with modules that enable warnings for you.  A common
275 example being Moose.  In this example, warnings for the 'smartmatch' feature are
276 first turned on by the warnings pragma, off by the experimental pragma and back
277 on 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
285 Because of the nature of the features it enables, forward compatibility can not
286 be guaranteed in any way.
287
288 =head1 SEE ALSO
289
290 L<perlexperiment|perlexperiment> contains more information about experimental features.
291
292 =head1 AUTHOR
293
294 Leon Timmermans <leont@cpan.org>
295
296 =head1 COPYRIGHT AND LICENSE
297
298 This software is copyright (c) 2013 by Leon Timmermans.
299
300 This is free software; you can redistribute it and/or modify it under
301 the same terms as the Perl 5 programming language system itself.
302
303 =cut