This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Faster feature checks
[perl5.git] / lib / feature.pm
CommitLineData
69bcf1d3
FC
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
0d863452
RH
6package feature;
7
9f601cf3 8our $VERSION = '1.56';
0d863452 9
0bb01b05 10our %feature = (
2a4315f8 11 fc => 'feature_fc',
47e9d84a
EB
12 say => 'feature_say',
13 state => 'feature_state',
1863b879 14 switch => 'feature_switch',
cec892e7 15 bitwise => 'feature_bitwise',
7d789282 16 evalbytes => 'feature_evalbytes',
30d9c59b 17 signatures => 'feature_signatures',
84ed0108 18 current_sub => 'feature___SUB__',
baabe3fb 19 refaliasing => 'feature_refaliasing',
158becca 20 postderef_qq => 'feature_postderef_qq',
cda6b701 21 unicode_eval => 'feature_unieval',
82d83da3 22 declared_refs => 'feature_myref',
47e9d84a 23 unicode_strings => 'feature_unicode',
bc9b29db
RH
24);
25
9f601cf3
TC
26
27my %feature_bits = (
28 bitwise => 0x0001,
29 current_sub => 0x0002,
30 declared_refs => 0x0004,
31 evalbytes => 0x0008,
32 fc => 0x0010,
33 postderef_qq => 0x0020,
34 refaliasing => 0x0040,
35 say => 0x0080,
36 signatures => 0x0100,
37 state => 0x0200,
38 switch => 0x0400,
39 unicode_eval => 0x0800,
40 unicode_strings => 0x1000,
41);
42
0d2bd2aa 43our %feature_bundle = (
c22e17d0
DIM
44 "5.10" => [qw(say state switch)],
45 "5.11" => [qw(say state switch unicode_strings)],
2a4315f8 46 "5.15" => [qw(current_sub evalbytes fc say state switch unicode_eval unicode_strings)],
1c2511e0 47 "5.23" => [qw(current_sub evalbytes fc postderef_qq say state switch unicode_eval unicode_strings)],
401d2aaa 48 "5.27" => [qw(bitwise current_sub evalbytes fc postderef_qq say state switch unicode_eval unicode_strings)],
c22e17d0
DIM
49 "all" => [qw(bitwise current_sub declared_refs evalbytes fc postderef_qq refaliasing say signatures state switch unicode_eval unicode_strings)],
50 "default" => [qw()],
0d863452 51);
d052521a 52
88da30d7
FC
53$feature_bundle{"5.12"} = $feature_bundle{"5.11"};
54$feature_bundle{"5.13"} = $feature_bundle{"5.11"};
55$feature_bundle{"5.14"} = $feature_bundle{"5.11"};
56$feature_bundle{"5.16"} = $feature_bundle{"5.15"};
d6402ebe 57$feature_bundle{"5.17"} = $feature_bundle{"5.15"};
52fc5c56 58$feature_bundle{"5.18"} = $feature_bundle{"5.15"};
d09258e7
RS
59$feature_bundle{"5.19"} = $feature_bundle{"5.15"};
60$feature_bundle{"5.20"} = $feature_bundle{"5.15"};
b530a4ea
RS
61$feature_bundle{"5.21"} = $feature_bundle{"5.15"};
62$feature_bundle{"5.22"} = $feature_bundle{"5.15"};
2ad792cd 63$feature_bundle{"5.24"} = $feature_bundle{"5.23"};
2c5484a6
RS
64$feature_bundle{"5.25"} = $feature_bundle{"5.23"};
65$feature_bundle{"5.26"} = $feature_bundle{"5.23"};
401d2aaa 66$feature_bundle{"5.28"} = $feature_bundle{"5.27"};
d361a1e6
S
67$feature_bundle{"5.29"} = $feature_bundle{"5.27"};
68$feature_bundle{"5.30"} = $feature_bundle{"5.27"};
1f8153bd
S
69$feature_bundle{"5.31"} = $feature_bundle{"5.27"};
70$feature_bundle{"5.32"} = $feature_bundle{"5.27"};
88da30d7 71$feature_bundle{"5.9.5"} = $feature_bundle{"5.10"};
db629560
FC
72my %noops = (
73 postderef => 1,
74 lexical_subs => 1,
75);
c22e17d0
DIM
76my %removed = (
77 array_base => 1,
78);
69bcf1d3 79
0bb01b05
FC
80our $hint_shift = 26;
81our $hint_mask = 0x1c000000;
401d2aaa 82our @hint_bundles = qw( default 5.10 5.11 5.15 5.23 5.27 );
ada44f8c 83
69bcf1d3
FC
84# This gets set (for now) in $^H as well as in %^H,
85# for runtime speed of the uc/lc/ucfirst/lcfirst functions.
86# See HINT_UNI_8_BIT in perl.h.
87our $hint_uni8bit = 0x00000800;
7dfde25d 88
0d863452 89# TODO:
1c321dc6 90# - think about versioned features (use feature switch => 2)
0d863452
RH
91
92=head1 NAME
93
e1b711da 94feature - Perl pragma to enable new features
0d863452
RH
95
96=head1 SYNOPSIS
97
47e9d84a 98 use feature qw(say switch);
0d863452 99 given ($foo) {
0b25e784
DG
100 when (1) { say "\$foo == 1" }
101 when ([2,3]) { say "\$foo == 2 || \$foo == 3" }
102 when (/^a[bc]d$/) { say "\$foo eq 'abd' || \$foo eq 'acd'" }
103 when ($_ > 100) { say "\$foo > 100" }
104 default { say "None of the above" }
0d863452
RH
105 }
106
ec488c7f
RGS
107 use feature ':5.10'; # loads all features available in perl 5.10
108
0b25e784
DG
109 use v5.10; # implicitly loads :5.10 feature bundle
110
0d863452
RH
111=head1 DESCRIPTION
112
113It is usually impossible to add new syntax to Perl without breaking
b22bbcf0 114some existing programs. This pragma provides a way to minimize that
1863b879
RGS
115risk. New syntactic constructs, or new semantic meanings to older
116constructs, can be enabled by C<use feature 'foo'>, and will be parsed
b22bbcf0 117only when the appropriate feature pragma is in scope. (Nevertheless, the
4a904372
FC
118C<CORE::> prefix provides access to all Perl keywords, regardless of this
119pragma.)
0d863452 120
9eb27be9
RGS
121=head2 Lexical effect
122
123Like other pragmas (C<use strict>, for example), features have a lexical
301381dc 124effect. C<use feature qw(foo)> will only make the feature "foo" available
9eb27be9
RGS
125from that point to the end of the enclosing block.
126
127 {
128 use feature 'say';
129 say "say is available here";
130 }
131 print "But not here.\n";
132
5e36ed56
RGS
133=head2 C<no feature>
134
b22bbcf0 135Features can also be turned off by using C<no feature "foo">. This too
5e36ed56
RGS
136has lexical effect.
137
138 use feature 'say';
139 say "say is available here";
140 {
141 no feature 'say';
142 print "But not here.\n";
143 }
144 say "Yet it is here.";
145
39ec54a5
RS
146C<no feature> with no features specified will reset to the default group. To
147disable I<all> features (an unusual request!) use C<no feature ':all'>.
5e36ed56 148
0b25e784
DG
149=head1 AVAILABLE FEATURES
150
0d863452
RH
151=head2 The 'say' feature
152
0b25e784 153C<use feature 'say'> tells the compiler to enable the Perl 6 style
9eb27be9 154C<say> function.
0d863452
RH
155
156See L<perlfunc/say> for details.
157
0b25e784
DG
158This feature is available starting with Perl 5.10.
159
160=head2 The 'state' feature
712d05cf
RGS
161
162C<use feature 'state'> tells the compiler to enable C<state>
9eb27be9 163variables.
712d05cf 164
e60bcc8b
RGS
165See L<perlsub/"Persistent Private Variables"> for details.
166
0b25e784
DG
167This feature is available starting with Perl 5.10.
168
47e9d84a
EB
169=head2 The 'switch' feature
170
7caca87c
DB
171B<WARNING>: Because the L<smartmatch operator|perlop/"Smartmatch Operator"> is
172experimental, Perl will warn when you use this feature, unless you have
173explicitly disabled the warning:
174
175 no warnings "experimental::smartmatch";
176
7896dde7 177C<use feature 'switch'> tells the compiler to enable the Perl 6
47e9d84a
EB
178given/when construct.
179
48238296 180See L<perlsyn/"Switch Statements"> for details.
47e9d84a 181
0b25e784
DG
182This feature is available starting with Perl 5.10.
183
184=head2 The 'unicode_strings' feature
1863b879 185
850b7ec9 186C<use feature 'unicode_strings'> tells the compiler to use Unicode rules
20db7501
KW
187in all string operations executed within its scope (unless they are also
188within the scope of either C<use locale> or C<use bytes>). The same applies
189to all regular expressions compiled within the scope, even if executed outside
2269d15c
KW
190it. It does not change the internal representation of strings, but only how
191they are interpreted.
20db7501
KW
192
193C<no feature 'unicode_strings'> tells the compiler to use the traditional
850b7ec9 194Perl rules wherein the native character set rules is used unless it is
20db7501
KW
195clear to Perl that Unicode is desired. This can lead to some surprises
196when the behavior suddenly changes. (See
197L<perlunicode/The "Unicode Bug"> for details.) For this reason, if you are
198potentially using Unicode in your program, the
199C<use feature 'unicode_strings'> subpragma is B<strongly> recommended.
200
2e2b2571 201This feature is available starting with Perl 5.12; was almost fully
d6c970c7 202implemented in Perl 5.14; and extended in Perl 5.16 to cover C<quotemeta>;
20ae58f7
AC
203was extended further in Perl 5.26 to cover L<the range
204operator|perlop/Range Operators>; and was extended again in Perl 5.28 to
205cover L<special-cased whitespace splitting|perlfunc/split>.
1863b879 206
0b25e784 207=head2 The 'unicode_eval' and 'evalbytes' features
7289c5e6 208
9891e9b7
KW
209Together, these two features are intended to replace the legacy string
210C<eval> function, which behaves problematically in some instances. They are
211available starting with Perl 5.16, and are enabled by default by a
212S<C<use 5.16>> or higher declaration.
213
214C<unicode_eval> changes the behavior of plain string C<eval> to work more
215consistently, especially in the Unicode world. Certain (mis)behaviors
216couldn't be changed without breaking some things that had come to rely on
217them, so the feature can be enabled and disabled. Details are at
218L<perlfunc/Under the "unicode_eval" feature>.
219
220C<evalbytes> is like string C<eval>, but operating on a byte stream that is
221not UTF-8 encoded. Details are at L<perlfunc/evalbytes EXPR>. Without a
222S<C<use feature 'evalbytes'>> nor a S<C<use v5.16>> (or higher) declaration in
223the current scope, you can still access it by instead writing
224C<CORE::evalbytes>.
7289c5e6 225
84ed0108
FC
226=head2 The 'current_sub' feature
227
228This provides the C<__SUB__> token that returns a reference to the current
229subroutine or C<undef> outside of a subroutine.
230
231This feature is available starting with Perl 5.16.
232
01868d00
FC
233=head2 The 'array_base' feature
234
c22e17d0
DIM
235This feature supported the legacy C<$[> variable. See L<perlvar/$[>.
236It was on by default but disabled under C<use v5.16> (see
237L</IMPLICIT LOADING>, below) and unavailable since perl 5.30.
01868d00
FC
238
239This feature is available under this name starting with Perl 5.16. In
240previous versions, it was simply on all the time, and this pragma knew
241nothing about it.
242
2a4315f8
BF
243=head2 The 'fc' feature
244
245C<use feature 'fc'> tells the compiler to enable the C<fc> function,
246which implements Unicode casefolding.
247
248See L<perlfunc/fc> for details.
249
250This feature is available from Perl 5.16 onwards.
251
ca40957e
FC
252=head2 The 'lexical_subs' feature
253
8f7d85af
FC
254In Perl versions prior to 5.26, this feature enabled
255declaration of subroutines via C<my sub foo>, C<state sub foo>
256and C<our sub foo> syntax. See L<perlsub/Lexical Subroutines> for details.
ca40957e 257
8f7d85af
FC
258This feature is available from Perl 5.18 onwards. From Perl 5.18 to 5.24,
259it was classed as experimental, and Perl emitted a warning for its
260usage, except when explicitly disabled:
ca40957e 261
8f7d85af 262 no warnings "experimental::lexical_subs";
ca40957e 263
8f7d85af
FC
264As of Perl 5.26, use of this feature no longer triggers a warning, though
265the C<experimental::lexical_subs> warning category still exists (for
266compatibility with code that disables it). In addition, this syntax is
267not only no longer experimental, but it is enabled for all Perl code,
268regardless of what feature declarations are in scope.
ca40957e 269
f86d720e
RS
270=head2 The 'postderef' and 'postderef_qq' features
271
1c2511e0
AC
272The 'postderef_qq' feature extends the applicability of L<postfix
273dereference syntax|perlref/Postfix Dereference Syntax> so that postfix array
274and scalar dereference are available in double-quotish interpolations. For
275example, it makes the following two statements equivalent:
f86d720e 276
1c2511e0
AC
277 my $s = "[@{ $h->{a} }]";
278 my $s = "[$h->{a}->@*]";
f86d720e 279
1c2511e0
AC
280This feature is available from Perl 5.20 onwards. In Perl 5.20 and 5.22, it
281was classed as experimental, and Perl emitted a warning for its
2ad792cd
AC
282usage, except when explicitly disabled:
283
284 no warnings "experimental::postderef";
285
1c2511e0 286As of Perl 5.24, use of this feature no longer triggers a warning, though
2ad792cd
AC
287the C<experimental::postderef> warning category still exists (for
288compatibility with code that disables it).
f86d720e 289
1c2511e0
AC
290The 'postderef' feature was used in Perl 5.20 and Perl 5.22 to enable
291postfix dereference syntax outside double-quotish interpolations. In those
292versions, using it triggered the C<experimental::postderef> warning in the
293same way as the 'postderef_qq' feature did. As of Perl 5.24, this syntax is
294not only no longer experimental, but it is enabled for all Perl code,
295regardless of what feature declarations are in scope.
296
30d9c59b
Z
297=head2 The 'signatures' feature
298
299B<WARNING>: This feature is still experimental and the implementation may
300change in future versions of Perl. For this reason, Perl will
301warn when you use the feature, unless you have explicitly disabled the
302warning:
303
304 no warnings "experimental::signatures";
305
306This enables unpacking of subroutine arguments into lexical variables
307by syntax such as
308
309 sub foo ($left, $right) {
310 return $left + $right;
311 }
312
313See L<perlsub/Signatures> for details.
314
315This feature is available from Perl 5.20 onwards.
316
baabe3fb 317=head2 The 'refaliasing' feature
82848c10
FC
318
319B<WARNING>: This feature is still experimental and the implementation may
320change in future versions of Perl. For this reason, Perl will
321warn when you use the feature, unless you have explicitly disabled the
322warning:
323
baabe3fb 324 no warnings "experimental::refaliasing";
82848c10
FC
325
326This enables aliasing via assignment to references:
327
328 \$a = \$b; # $a and $b now point to the same scalar
329 \@a = \@b; # to the same array
330 \%a = \%b;
331 \&a = \&b;
332 foreach \%hash (@array_of_hash_refs) {
333 ...
334 }
335
336See L<perlref/Assigning to References> for details.
337
338This feature is available from Perl 5.22 onwards.
339
70ea8edf
FC
340=head2 The 'bitwise' feature
341
70ea8edf
FC
342This makes the four standard bitwise operators (C<& | ^ ~>) treat their
343operands consistently as numbers, and introduces four new dotted operators
344(C<&. |. ^. ~.>) that treat their operands consistently as strings. The
345same applies to the assignment variants (C<&= |= ^= &.= |.= ^.=>).
346
347See L<perlop/Bitwise String Operators> for details.
348
193789ac
FC
349This feature is available from Perl 5.22 onwards. Starting in Perl 5.28,
350C<use v5.28> will enable the feature. Before 5.28, it was still
351experimental and would emit a warning in the "experimental::bitwise"
352category.
70ea8edf 353
5c703779
FC
354=head2 The 'declared_refs' feature
355
356B<WARNING>: This feature is still experimental and the implementation may
357change in future versions of Perl. For this reason, Perl will
358warn when you use the feature, unless you have explicitly disabled the
359warning:
360
361 no warnings "experimental::declared_refs";
362
363This allows a reference to a variable to be declared with C<my>, C<state>,
364our C<our>, or localized with C<local>. It is intended mainly for use in
365conjunction with the "refaliasing" feature. See L<perlref/Declaring a
366Reference to a Variable> for examples.
367
368This feature is available from Perl 5.26 onwards.
369
bc9b29db
RH
370=head1 FEATURE BUNDLES
371
0b25e784 372It's possible to load multiple features together, using
b22bbcf0 373a I<feature bundle>. The name of a feature bundle is prefixed with
0b25e784
DG
374a colon, to distinguish it from an actual feature.
375
376 use feature ":5.10";
377
378The following feature bundles are available:
379
380 bundle features included
381 --------- -----------------
c22e17d0 382 :default
0b25e784 383
c22e17d0 384 :5.10 say state switch
0b25e784 385
c22e17d0 386 :5.12 say state switch unicode_strings
0b25e784 387
c22e17d0 388 :5.14 say state switch unicode_strings
0b25e784
DG
389
390 :5.16 say state switch unicode_strings
2a4315f8 391 unicode_eval evalbytes current_sub fc
0b25e784 392
52fc5c56
FC
393 :5.18 say state switch unicode_strings
394 unicode_eval evalbytes current_sub fc
395
d09258e7
RS
396 :5.20 say state switch unicode_strings
397 unicode_eval evalbytes current_sub fc
398
b530a4ea
RS
399 :5.22 say state switch unicode_strings
400 unicode_eval evalbytes current_sub fc
401
6031f0d2
RS
402 :5.24 say state switch unicode_strings
403 unicode_eval evalbytes current_sub fc
1c2511e0 404 postderef_qq
6031f0d2 405
2c5484a6
RS
406 :5.26 say state switch unicode_strings
407 unicode_eval evalbytes current_sub fc
408 postderef_qq
409
c35a148e
S
410 :5.28 say state switch unicode_strings
411 unicode_eval evalbytes current_sub fc
401d2aaa 412 postderef_qq bitwise
c35a148e 413
d361a1e6
S
414 :5.30 say state switch unicode_strings
415 unicode_eval evalbytes current_sub fc
416 postderef_qq bitwise
417
1f8153bd
S
418 :5.32 say state switch unicode_strings
419 unicode_eval evalbytes current_sub fc
420 postderef_qq bitwise
421
01868d00
FC
422The C<:default> bundle represents the feature set that is enabled before
423any C<use feature> or C<no feature> declaration.
a3a91442
JV
424
425Specifying sub-versions such as the C<0> in C<5.14.0> in feature bundles has
b22bbcf0 426no effect. Feature bundles are guaranteed to be the same for all sub-versions.
bc9b29db 427
0b25e784
DG
428 use feature ":5.14.0"; # same as ":5.14"
429 use feature ":5.14.1"; # same as ":5.14"
a3a91442 430
7dfde25d
RGS
431=head1 IMPLICIT LOADING
432
0b25e784
DG
433Instead of loading feature bundles by name, it is easier to let Perl do
434implicit loading of a feature bundle for you.
435
436There are two ways to load the C<feature> pragma implicitly:
7dfde25d
RGS
437
438=over 4
439
440=item *
441
0b25e784
DG
442By using the C<-E> switch on the Perl command-line instead of C<-e>.
443That will enable the feature bundle for that version of Perl in the
444main compilation unit (that is, the one-liner that follows C<-E>).
7dfde25d
RGS
445
446=item *
447
0b25e784 448By explicitly requiring a minimum Perl version number for your program, with
b22bbcf0 449the C<use VERSION> construct. That is,
7dfde25d 450
0b25e784 451 use v5.10.0;
7dfde25d
RGS
452
453will do an implicit
454
39ec54a5 455 no feature ':all';
82cfb3a2 456 use feature ':5.10';
7dfde25d 457
b22bbcf0
FC
458and so on. Note how the trailing sub-version
459is automatically stripped from the
82cfb3a2 460version.
7dfde25d 461
8d115822
RB
462But to avoid portability warnings (see L<perlfunc/use>), you may prefer:
463
464 use 5.010;
465
466with the same effect.
467
0b25e784 468If the required version is older than Perl 5.10, the ":default" feature
01868d00 469bundle is automatically loaded instead.
70397346 470
affe54fa
AC
471Unlike C<use feature ":5.12">, saying C<use v5.12> (or any higher version)
472also does the equivalent of C<use strict>; see L<perlfunc/use> for details.
473
7dfde25d
RGS
474=back
475
0d863452
RH
476=cut
477
478sub import {
22055af9 479 shift;
36143a0c
NC
480
481 if (!@_) {
0b25e784 482 croak("No features specified");
0d863452 483 }
36143a0c 484
d3757264 485 __common(1, @_);
0d863452
RH
486}
487
488sub unimport {
22055af9 489 shift;
0d863452 490
39ec54a5 491 # A bare C<no feature> should reset to the default bundle
bc9b29db 492 if (!@_) {
39ec54a5
RS
493 $^H &= ~($hint_uni8bit|$hint_mask);
494 return;
bc9b29db
RH
495 }
496
d3757264
NC
497 __common(0, @_);
498}
499
500
501sub __common {
502 my $import = shift;
0c8d5017
NC
503 my $bundle_number = $^H & $hint_mask;
504 my $features = $bundle_number != $hint_mask
9f601cf3
TC
505 && $feature_bundle{$hint_bundles[$bundle_number >> $hint_shift]};
506 my $bits = ${^FEATURE_BITS};
0c8d5017 507 if ($features) {
da5b5421 508 # Features are enabled implicitly via bundle hints.
d9ee6ccb
NC
509 # Delete any keys that may be left over from last time.
510 delete @^H{ values(%feature) };
9f601cf3 511 $bits = 0;
d9ee6ccb
NC
512 $^H |= $hint_mask;
513 for (@$features) {
514 $^H{$feature{$_}} = 1;
9f601cf3 515 $bits |= $feature_bits{$_};
d9ee6ccb
NC
516 $^H |= $hint_uni8bit if $_ eq 'unicode_strings';
517 }
da5b5421 518 }
bc9b29db 519 while (@_) {
0b25e784
DG
520 my $name = shift;
521 if (substr($name, 0, 1) eq ":") {
522 my $v = substr($name, 1);
523 if (!exists $feature_bundle{$v}) {
524 $v =~ s/^([0-9]+)\.([0-9]+).[0-9]+$/$1.$2/;
525 if (!exists $feature_bundle{$v}) {
526 unknown_feature_bundle(substr($name, 1));
527 }
528 }
529 unshift @_, @{$feature_bundle{$v}};
530 next;
531 }
36143a0c 532 if (!exists $feature{$name}) {
db629560
FC
533 if (exists $noops{$name}) {
534 next;
535 }
c22e17d0
DIM
536 if (!$import && exists $removed{$name}) {
537 next;
538 }
0b25e784
DG
539 unknown_feature($name);
540 }
d3757264
NC
541 if ($import) {
542 $^H{$feature{$name}} = 1;
9f601cf3 543 $bits |= $feature_bits{$name};
d3757264
NC
544 $^H |= $hint_uni8bit if $name eq 'unicode_strings';
545 } else {
0b25e784 546 delete $^H{$feature{$name}};
9f601cf3 547 $bits &= ~$feature_bits{$name};
1863b879 548 $^H &= ~ $hint_uni8bit if $name eq 'unicode_strings';
0b25e784 549 }
0d863452 550 }
9f601cf3 551 ${^FEATURE_BITS} = $bits;
0d863452
RH
552}
553
b42943c4
RGS
554sub unknown_feature {
555 my $feature = shift;
556 croak(sprintf('Feature "%s" is not supported by Perl %vd',
0b25e784 557 $feature, $^V));
b42943c4
RGS
558}
559
560sub unknown_feature_bundle {
561 my $feature = shift;
562 croak(sprintf('Feature bundle "%s" is not supported by Perl %vd',
0b25e784 563 $feature, $^V));
b42943c4
RGS
564}
565
566sub croak {
567 require Carp;
568 Carp::croak(@_);
569}
570
0d863452 5711;
69bcf1d3
FC
572
573# ex: set ro: