correct the deprecation data in Module::CoreList
[perl.git] / lib / feature.pm
1 # -*- buffer-read-only: t -*-
2 # !!!!!!!   DO NOT EDIT THIS FILE   !!!!!!!
3 # This file is built by regen/feature.pl.
4 # Any changes made here will be lost!
5
6 package feature;
7
8 our $VERSION = '1.40';
9
10 our %feature = (
11     fc              => 'feature_fc',
12     say             => 'feature_say',
13     state           => 'feature_state',
14     switch          => 'feature_switch',
15     bitwise         => 'feature_bitwise',
16     evalbytes       => 'feature_evalbytes',
17     postderef       => 'feature_postderef',
18     array_base      => 'feature_arybase',
19     signatures      => 'feature_signatures',
20     current_sub     => 'feature___SUB__',
21     refaliasing     => 'feature_refaliasing',
22     lexical_subs    => 'feature_lexsubs',
23     postderef_qq    => 'feature_postderef_qq',
24     unicode_eval    => 'feature_unieval',
25     unicode_strings => 'feature_unicode',
26 );
27
28 our %feature_bundle = (
29     "5.10"    => [qw(array_base say state switch)],
30     "5.11"    => [qw(array_base say state switch unicode_strings)],
31     "5.15"    => [qw(current_sub evalbytes fc say state switch unicode_eval unicode_strings)],
32     "all"     => [qw(array_base bitwise current_sub evalbytes fc lexical_subs postderef postderef_qq refaliasing say signatures state switch unicode_eval unicode_strings)],
33     "default" => [qw(array_base)],
34 );
35
36 $feature_bundle{"5.12"} = $feature_bundle{"5.11"};
37 $feature_bundle{"5.13"} = $feature_bundle{"5.11"};
38 $feature_bundle{"5.14"} = $feature_bundle{"5.11"};
39 $feature_bundle{"5.16"} = $feature_bundle{"5.15"};
40 $feature_bundle{"5.17"} = $feature_bundle{"5.15"};
41 $feature_bundle{"5.18"} = $feature_bundle{"5.15"};
42 $feature_bundle{"5.19"} = $feature_bundle{"5.15"};
43 $feature_bundle{"5.20"} = $feature_bundle{"5.15"};
44 $feature_bundle{"5.21"} = $feature_bundle{"5.15"};
45 $feature_bundle{"5.22"} = $feature_bundle{"5.15"};
46 $feature_bundle{"5.9.5"} = $feature_bundle{"5.10"};
47
48 our $hint_shift   = 26;
49 our $hint_mask    = 0x1c000000;
50 our @hint_bundles = qw( default 5.10 5.11 5.15 );
51
52 # This gets set (for now) in $^H as well as in %^H,
53 # for runtime speed of the uc/lc/ucfirst/lcfirst functions.
54 # See HINT_UNI_8_BIT in perl.h.
55 our $hint_uni8bit = 0x00000800;
56
57 # TODO:
58 # - think about versioned features (use feature switch => 2)
59
60 =head1 NAME
61
62 feature - Perl pragma to enable new features
63
64 =head1 SYNOPSIS
65
66     use feature qw(say switch);
67     given ($foo) {
68         when (1)          { say "\$foo == 1" }
69         when ([2,3])      { say "\$foo == 2 || \$foo == 3" }
70         when (/^a[bc]d$/) { say "\$foo eq 'abd' || \$foo eq 'acd'" }
71         when ($_ > 100)   { say "\$foo > 100" }
72         default           { say "None of the above" }
73     }
74
75     use feature ':5.10'; # loads all features available in perl 5.10
76
77     use v5.10;           # implicitly loads :5.10 feature bundle
78
79 =head1 DESCRIPTION
80
81 It is usually impossible to add new syntax to Perl without breaking
82 some existing programs.  This pragma provides a way to minimize that
83 risk. New syntactic constructs, or new semantic meanings to older
84 constructs, can be enabled by C<use feature 'foo'>, and will be parsed
85 only when the appropriate feature pragma is in scope.  (Nevertheless, the
86 C<CORE::> prefix provides access to all Perl keywords, regardless of this
87 pragma.)
88
89 =head2 Lexical effect
90
91 Like other pragmas (C<use strict>, for example), features have a lexical
92 effect.  C<use feature qw(foo)> will only make the feature "foo" available
93 from that point to the end of the enclosing block.
94
95     {
96         use feature 'say';
97         say "say is available here";
98     }
99     print "But not here.\n";
100
101 =head2 C<no feature>
102
103 Features can also be turned off by using C<no feature "foo">.  This too
104 has lexical effect.
105
106     use feature 'say';
107     say "say is available here";
108     {
109         no feature 'say';
110         print "But not here.\n";
111     }
112     say "Yet it is here.";
113
114 C<no feature> with no features specified will reset to the default group.  To
115 disable I<all> features (an unusual request!) use C<no feature ':all'>.
116
117 =head1 AVAILABLE FEATURES
118
119 =head2 The 'say' feature
120
121 C<use feature 'say'> tells the compiler to enable the Perl 6 style
122 C<say> function.
123
124 See L<perlfunc/say> for details.
125
126 This feature is available starting with Perl 5.10.
127
128 =head2 The 'state' feature
129
130 C<use feature 'state'> tells the compiler to enable C<state>
131 variables.
132
133 See L<perlsub/"Persistent Private Variables"> for details.
134
135 This feature is available starting with Perl 5.10.
136
137 =head2 The 'switch' feature
138
139 B<WARNING>: Because the L<smartmatch operator|perlop/"Smartmatch Operator"> is
140 experimental, Perl will warn when you use this feature, unless you have
141 explicitly disabled the warning:
142
143     no warnings "experimental::smartmatch";
144
145 C<use feature 'switch'> tells the compiler to enable the Perl 6
146 given/when construct.
147
148 See L<perlsyn/"Switch Statements"> for details.
149
150 This feature is available starting with Perl 5.10.
151
152 =head2 The 'unicode_strings' feature
153
154 C<use feature 'unicode_strings'> tells the compiler to use Unicode rules
155 in all string operations executed within its scope (unless they are also
156 within the scope of either C<use locale> or C<use bytes>).  The same applies
157 to all regular expressions compiled within the scope, even if executed outside
158 it.  It does not change the internal representation of strings, but only how
159 they are interpreted.
160
161 C<no feature 'unicode_strings'> tells the compiler to use the traditional
162 Perl rules wherein the native character set rules is used unless it is
163 clear to Perl that Unicode is desired.  This can lead to some surprises
164 when the behavior suddenly changes.  (See
165 L<perlunicode/The "Unicode Bug"> for details.)  For this reason, if you are
166 potentially using Unicode in your program, the
167 C<use feature 'unicode_strings'> subpragma is B<strongly> recommended.
168
169 This feature is available starting with Perl 5.12; was almost fully
170 implemented in Perl 5.14; and extended in Perl 5.16 to cover C<quotemeta>.
171
172 =head2 The 'unicode_eval' and 'evalbytes' features
173
174 Under the C<unicode_eval> feature, Perl's C<eval> function, when passed a
175 string, will evaluate it as a string of characters, ignoring any
176 C<use utf8> declarations.  C<use utf8> exists to declare the encoding of
177 the script, which only makes sense for a stream of bytes, not a string of
178 characters.  Source filters are forbidden, as they also really only make
179 sense on strings of bytes.  Any attempt to activate a source filter will
180 result in an error.
181
182 The C<evalbytes> feature enables the C<evalbytes> keyword, which evaluates
183 the argument passed to it as a string of bytes.  It dies if the string
184 contains any characters outside the 8-bit range.  Source filters work
185 within C<evalbytes>: they apply to the contents of the string being
186 evaluated.
187
188 Together, these two features are intended to replace the historical C<eval>
189 function, which has (at least) two bugs in it, that cannot easily be fixed
190 without breaking existing programs:
191
192 =over
193
194 =item *
195
196 C<eval> behaves differently depending on the internal encoding of the
197 string, sometimes treating its argument as a string of bytes, and sometimes
198 as a string of characters.
199
200 =item *
201
202 Source filters activated within C<eval> leak out into whichever I<file>
203 scope is currently being compiled.  To give an example with the CPAN module
204 L<Semi::Semicolons>:
205
206     BEGIN { eval "use Semi::Semicolons;  # not filtered here " }
207     # filtered here!
208
209 C<evalbytes> fixes that to work the way one would expect:
210
211     use feature "evalbytes";
212     BEGIN { evalbytes "use Semi::Semicolons;  # filtered " }
213     # not filtered
214
215 =back
216
217 These two features are available starting with Perl 5.16.
218
219 =head2 The 'current_sub' feature
220
221 This provides the C<__SUB__> token that returns a reference to the current
222 subroutine or C<undef> outside of a subroutine.
223
224 This feature is available starting with Perl 5.16.
225
226 =head2 The 'array_base' feature
227
228 This feature supports the legacy C<$[> variable.  See L<perlvar/$[> and
229 L<arybase>.  It is on by default but disabled under C<use v5.16> (see
230 L</IMPLICIT LOADING>, below).
231
232 This feature is available under this name starting with Perl 5.16.  In
233 previous versions, it was simply on all the time, and this pragma knew
234 nothing about it.
235
236 =head2 The 'fc' feature
237
238 C<use feature 'fc'> tells the compiler to enable the C<fc> function,
239 which implements Unicode casefolding.
240
241 See L<perlfunc/fc> for details.
242
243 This feature is available from Perl 5.16 onwards.
244
245 =head2 The 'lexical_subs' feature
246
247 B<WARNING>: This feature is still experimental and the implementation may
248 change in future versions of Perl.  For this reason, Perl will
249 warn when you use the feature, unless you have explicitly disabled the
250 warning:
251
252     no warnings "experimental::lexical_subs";
253
254 This enables declaration of subroutines via C<my sub foo>, C<state sub foo>
255 and C<our sub foo> syntax.  See L<perlsub/Lexical Subroutines> for details.
256
257 This feature is available from Perl 5.18 onwards.
258
259 =head2 The 'postderef' and 'postderef_qq' features
260
261 B<WARNING>: This feature is still experimental and the implementation may
262 change in future versions of Perl.  For this reason, Perl will
263 warn when you use the feature, unless you have explicitly disabled the
264 warning:
265
266   no warnings "experimental::postderef";
267
268 The 'postderef' feature allows the use of L<postfix dereference
269 syntax|perlref/Postfix Dereference Syntax>.  For example, it will make the
270 following two statements equivalent:
271
272   my @x = @{ $h->{a} };
273   my @x = $h->{a}->@*;
274
275 The 'postderef_qq' feature extends this, for array and scalar dereference, to
276 working inside of double-quotish interpolations.
277
278 This feature is available from Perl 5.20 onwards.
279
280 =head2 The 'signatures' feature
281
282 B<WARNING>: This feature is still experimental and the implementation may
283 change in future versions of Perl.  For this reason, Perl will
284 warn when you use the feature, unless you have explicitly disabled the
285 warning:
286
287     no warnings "experimental::signatures";
288
289 This enables unpacking of subroutine arguments into lexical variables
290 by syntax such as
291
292     sub foo ($left, $right) {
293         return $left + $right;
294     }
295
296 See L<perlsub/Signatures> for details.
297
298 This feature is available from Perl 5.20 onwards.
299
300 =head2 The 'refaliasing' feature
301
302 B<WARNING>: This feature is still experimental and the implementation may
303 change in future versions of Perl.  For this reason, Perl will
304 warn when you use the feature, unless you have explicitly disabled the
305 warning:
306
307     no warnings "experimental::refaliasing";
308
309 This enables aliasing via assignment to references:
310
311     \$a = \$b; # $a and $b now point to the same scalar
312     \@a = \@b; #                     to the same array
313     \%a = \%b;
314     \&a = \&b;
315     foreach \%hash (@array_of_hash_refs) {
316         ...
317     }
318
319 See L<perlref/Assigning to References> for details.
320
321 This feature is available from Perl 5.22 onwards.
322
323 =head2 The 'bitwise' feature
324
325 B<WARNING>: This feature is still experimental and the implementation may
326 change in future versions of Perl.  For this reason, Perl will
327 warn when you use the feature, unless you have explicitly disabled the
328 warning:
329
330     no warnings "experimental::bitwise";
331
332 This makes the four standard bitwise operators (C<& | ^ ~>) treat their
333 operands consistently as numbers, and introduces four new dotted operators
334 (C<&. |. ^. ~.>) that treat their operands consistently as strings.  The
335 same applies to the assignment variants (C<&= |= ^= &.= |.= ^.=>).
336
337 See L<perlop/Bitwise String Operators> for details.
338
339 This feature is available from Perl 5.22 onwards.
340
341 =head1 FEATURE BUNDLES
342
343 It's possible to load multiple features together, using
344 a I<feature bundle>.  The name of a feature bundle is prefixed with
345 a colon, to distinguish it from an actual feature.
346
347   use feature ":5.10";
348
349 The following feature bundles are available:
350
351   bundle    features included
352   --------- -----------------
353   :default  array_base
354
355   :5.10     say state switch array_base
356
357   :5.12     say state switch unicode_strings array_base
358
359   :5.14     say state switch unicode_strings array_base
360
361   :5.16     say state switch unicode_strings
362             unicode_eval evalbytes current_sub fc
363
364   :5.18     say state switch unicode_strings
365             unicode_eval evalbytes current_sub fc
366
367   :5.20     say state switch unicode_strings
368             unicode_eval evalbytes current_sub fc
369
370   :5.22     say state switch unicode_strings
371             unicode_eval evalbytes current_sub fc
372
373 The C<:default> bundle represents the feature set that is enabled before
374 any C<use feature> or C<no feature> declaration.
375
376 Specifying sub-versions such as the C<0> in C<5.14.0> in feature bundles has
377 no effect.  Feature bundles are guaranteed to be the same for all sub-versions.
378
379   use feature ":5.14.0";    # same as ":5.14"
380   use feature ":5.14.1";    # same as ":5.14"
381
382 =head1 IMPLICIT LOADING
383
384 Instead of loading feature bundles by name, it is easier to let Perl do
385 implicit loading of a feature bundle for you.
386
387 There are two ways to load the C<feature> pragma implicitly:
388
389 =over 4
390
391 =item *
392
393 By using the C<-E> switch on the Perl command-line instead of C<-e>.
394 That will enable the feature bundle for that version of Perl in the
395 main compilation unit (that is, the one-liner that follows C<-E>).
396
397 =item *
398
399 By explicitly requiring a minimum Perl version number for your program, with
400 the C<use VERSION> construct.  That is,
401
402     use v5.10.0;
403
404 will do an implicit
405
406     no feature ':all';
407     use feature ':5.10';
408
409 and so on.  Note how the trailing sub-version
410 is automatically stripped from the
411 version.
412
413 But to avoid portability warnings (see L<perlfunc/use>), you may prefer:
414
415     use 5.010;
416
417 with the same effect.
418
419 If the required version is older than Perl 5.10, the ":default" feature
420 bundle is automatically loaded instead.
421
422 =back
423
424 =cut
425
426 sub import {
427     my $class = shift;
428
429     if (!@_) {
430         croak("No features specified");
431     }
432
433     __common(1, @_);
434 }
435
436 sub unimport {
437     my $class = shift;
438
439     # A bare C<no feature> should reset to the default bundle
440     if (!@_) {
441         $^H &= ~($hint_uni8bit|$hint_mask);
442         return;
443     }
444
445     __common(0, @_);
446 }
447
448
449 sub __common {
450     my $import = shift;
451     my $bundle_number = $^H & $hint_mask;
452     my $features = $bundle_number != $hint_mask
453         && $feature_bundle{$hint_bundles[$bundle_number >> $hint_shift]};
454     if ($features) {
455         # Features are enabled implicitly via bundle hints.
456         # Delete any keys that may be left over from last time.
457         delete @^H{ values(%feature) };
458         $^H |= $hint_mask;
459         for (@$features) {
460             $^H{$feature{$_}} = 1;
461             $^H |= $hint_uni8bit if $_ eq 'unicode_strings';
462         }
463     }
464     while (@_) {
465         my $name = shift;
466         if (substr($name, 0, 1) eq ":") {
467             my $v = substr($name, 1);
468             if (!exists $feature_bundle{$v}) {
469                 $v =~ s/^([0-9]+)\.([0-9]+).[0-9]+$/$1.$2/;
470                 if (!exists $feature_bundle{$v}) {
471                     unknown_feature_bundle(substr($name, 1));
472                 }
473             }
474             unshift @_, @{$feature_bundle{$v}};
475             next;
476         }
477         if (!exists $feature{$name}) {
478             unknown_feature($name);
479         }
480         if ($import) {
481             $^H{$feature{$name}} = 1;
482             $^H |= $hint_uni8bit if $name eq 'unicode_strings';
483         } else {
484             delete $^H{$feature{$name}};
485             $^H &= ~ $hint_uni8bit if $name eq 'unicode_strings';
486         }
487     }
488 }
489
490 sub unknown_feature {
491     my $feature = shift;
492     croak(sprintf('Feature "%s" is not supported by Perl %vd',
493             $feature, $^V));
494 }
495
496 sub unknown_feature_bundle {
497     my $feature = shift;
498     croak(sprintf('Feature bundle "%s" is not supported by Perl %vd',
499             $feature, $^V));
500 }
501
502 sub croak {
503     require Carp;
504     Carp::croak(@_);
505 }
506
507 1;
508
509 # ex: set ro: