This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Faster feature checks
[perl5.git] / regen / feature.pl
CommitLineData
69bcf1d3
FC
1#!/usr/bin/perl
2#
3# Regenerate (overwriting only if changed):
4#
5# lib/feature.pm
f2c01b15 6# feature.h
69bcf1d3 7#
3489ea76 8# from information hardcoded into this script and from two #defines
d73d634c 9# in perl.h.
69bcf1d3
FC
10#
11# This script is normally invoked from regen.pl.
12
13BEGIN {
3d7c117d 14 require './regen/regen_lib.pl';
69bcf1d3
FC
15 push @INC, './lib';
16}
17use strict ;
18
c452a42f
FC
19
20###########################################################################
21# Hand-editable data
22
c6b36e45 23# (feature name) => (internal name, used in %^H and macro names)
69bcf1d3 24my %feature = (
67bdaa9e
FC
25 say => 'say',
26 state => 'state',
27 switch => 'switch',
cec892e7 28 bitwise => 'bitwise',
67bdaa9e
FC
29 evalbytes => 'evalbytes',
30 current_sub => '__SUB__',
baabe3fb 31 refaliasing => 'refaliasing',
158becca 32 postderef_qq => 'postderef_qq',
67bdaa9e 33 unicode_eval => 'unieval',
82d83da3 34 declared_refs => 'myref',
67bdaa9e 35 unicode_strings => 'unicode',
2a4315f8 36 fc => 'fc',
30d9c59b 37 signatures => 'signatures',
69bcf1d3
FC
38);
39
40e4d872
FC
40# NOTE: If a feature is ever enabled in a non-contiguous range of Perl
41# versions, any code below that uses %BundleRanges will have to
42# be changed to account.
43
52fc5c56 44# 5.odd implies the next 5.even, but an explicit 5.even can override it.
69bcf1d3 45my %feature_bundle = (
39ec54a5 46 all => [ keys %feature ],
c22e17d0
DIM
47 default => [qw()],
48 "5.9.5" => [qw(say state switch)],
49 "5.10" => [qw(say state switch)],
50 "5.11" => [qw(say state switch unicode_strings)],
51 "5.13" => [qw(say state switch unicode_strings)],
69bcf1d3 52 "5.15" => [qw(say state switch unicode_strings unicode_eval
2a4315f8 53 evalbytes current_sub fc)],
d6402ebe
RS
54 "5.17" => [qw(say state switch unicode_strings unicode_eval
55 evalbytes current_sub fc)],
d09258e7
RS
56 "5.19" => [qw(say state switch unicode_strings unicode_eval
57 evalbytes current_sub fc)],
b530a4ea
RS
58 "5.21" => [qw(say state switch unicode_strings unicode_eval
59 evalbytes current_sub fc)],
6031f0d2 60 "5.23" => [qw(say state switch unicode_strings unicode_eval
1c2511e0 61 evalbytes current_sub fc postderef_qq)],
2c5484a6
RS
62 "5.25" => [qw(say state switch unicode_strings unicode_eval
63 evalbytes current_sub fc postderef_qq)],
c35a148e 64 "5.27" => [qw(say state switch unicode_strings unicode_eval
401d2aaa 65 evalbytes current_sub fc postderef_qq bitwise)],
d361a1e6
S
66 "5.29" => [qw(say state switch unicode_strings unicode_eval
67 evalbytes current_sub fc postderef_qq bitwise)],
b85fe491
S
68 "5.31" => [qw(say state switch unicode_strings unicode_eval
69 evalbytes current_sub fc postderef_qq bitwise)],
69bcf1d3
FC
70);
71
db629560 72my @noops = qw( postderef lexical_subs );
c22e17d0 73my @removed = qw( array_base );
db629560 74
c452a42f 75
69bcf1d3 76###########################################################################
c452a42f 77# More data generated from the above
69bcf1d3 78
9f601cf3
TC
79if (keys %feature > 32) {
80 die "cop_features only has room for 32 features";
81}
82
83my %feature_bits;
84my $mask = 1;
85for my $feature (sort keys %feature) {
86 $feature_bits{$feature} = $mask;
87 $mask <<= 1;
88}
89
52fc5c56
FC
90for (keys %feature_bundle) {
91 next unless /^5\.(\d*[13579])\z/;
92 $feature_bundle{"5.".($1+1)} ||= $feature_bundle{$_};
93}
94
f2c01b15
FC
95my %UniqueBundles; # "say state switch" => 5.10
96my %Aliases; # 5.12 => 5.11
97for( sort keys %feature_bundle ) {
98 my $value = join(' ', sort @{$feature_bundle{$_}});
99 if (exists $UniqueBundles{$value}) {
100 $Aliases{$_} = $UniqueBundles{$value};
101 }
102 else {
103 $UniqueBundles{$value} = $_;
104 }
105}
40e4d872
FC
106 # start end
107my %BundleRanges; # say => ['5.10', '5.15'] # unique bundles for values
108for my $bund (
109 sort { $a eq 'default' ? -1 : $b eq 'default' ? 1 : $a cmp $b }
110 values %UniqueBundles
111) {
03222170 112 next if $bund =~ /[^\d.]/ and $bund ne 'default';
40e4d872
FC
113 for (@{$feature_bundle{$bund}}) {
114 if (@{$BundleRanges{$_} ||= []} == 2) {
115 $BundleRanges{$_}[1] = $bund
116 }
117 else {
118 push @{$BundleRanges{$_}}, $bund;
119 }
120 }
121}
69bcf1d3 122
47222a2d 123my $HintShift;
ada44f8c 124my $HintMask;
3489ea76 125my $Uni8Bit;
47222a2d 126
1ae6ead9 127open "perl.h", "<", "perl.h" or die "$0 cannot open perl.h: $!";
3489ea76
FC
128while (readline "perl.h") {
129 next unless /#\s*define\s+(HINT_FEATURE_MASK|HINT_UNI_8_BIT)/;
130 my $is_u8b = $1 =~ 8;
131 /(0x[A-Fa-f0-9]+)/ or die "No hex number in:\n\n$_\n ";
132 if ($is_u8b) {
133 $Uni8Bit = $1;
134 }
135 else {
ada44f8c 136 my $hex = $HintMask = $1;
47222a2d
FC
137 my $bits = sprintf "%b", oct $1;
138 $bits =~ /^0*1+(0*)\z/
139 or die "Non-contiguous bits in $bits (binary for $hex):\n\n$_\n ";
140 $HintShift = length $1;
141 my $bits_needed =
142 length sprintf "%b", scalar keys %UniqueBundles;
143 $bits =~ /1{$bits_needed}/
144 or die "Not enough bits (need $bits_needed)"
5d826eae 145 . " in $bits (binary for $hex):\n\n$_\n ";
47222a2d 146 }
3489ea76 147 if ($Uni8Bit && $HintMask) { last }
47222a2d 148}
3489ea76
FC
149die "No HINT_FEATURE_MASK defined in perl.h" unless $HintMask;
150die "No HINT_UNI_8_BIT defined in perl.h" unless $Uni8Bit;
151
47222a2d
FC
152close "perl.h";
153
ada44f8c
FC
154my @HintedBundles =
155 ('default', grep !/[^\d.]/, sort values %UniqueBundles);
156
47222a2d 157
f2c01b15 158###########################################################################
c452a42f 159# Open files to be generated
f2c01b15
FC
160
161my ($pm, $h) = map {
69bcf1d3 162 open_new($_, '>', { by => 'regen/feature.pl' });
f2c01b15 163} 'lib/feature.pm', 'feature.h';
69bcf1d3
FC
164
165
c452a42f
FC
166###########################################################################
167# Generate lib/feature.pm
168
69bcf1d3
FC
169while (<DATA>) {
170 last if /^FEATURES$/ ;
171 print $pm $_ ;
172}
173
174sub longest {
175 my $long;
176 for(@_) {
177 if (!defined $long or length $long < length) {
178 $long = $_;
179 }
180 }
181 $long;
182}
183
0bb01b05 184print $pm "our %feature = (\n";
69bcf1d3 185my $width = length longest keys %feature;
ebd25686 186for(sort { length $a <=> length $b || $a cmp $b } keys %feature) {
67bdaa9e
FC
187 print $pm " $_" . " "x($width-length)
188 . " => 'feature_$feature{$_}',\n";
69bcf1d3
FC
189}
190print $pm ");\n\n";
191
9f601cf3
TC
192print $pm "\nmy %feature_bits = (\n";
193for (sort keys %feature_bits) {
194 printf $pm " %-*s => %#06x,\n", $width, $_, $feature_bits{$_};
195}
196print $pm ");\n\n";
197
69bcf1d3 198print $pm "our %feature_bundle = (\n";
9f601cf3 199my $bund_width = length longest values %UniqueBundles;
88da30d7
FC
200for( sort { $UniqueBundles{$a} cmp $UniqueBundles{$b} }
201 keys %UniqueBundles ) {
202 my $bund = $UniqueBundles{$_};
9f601cf3 203 print $pm qq' "$bund"' . " "x($bund_width-length $bund)
88da30d7 204 . qq' => [qw($_)],\n';
69bcf1d3
FC
205}
206print $pm ");\n\n";
207
88da30d7
FC
208for (sort keys %Aliases) {
209 print $pm
210 qq'\$feature_bundle{"$_"} = \$feature_bundle{"$Aliases{$_}"};\n';
211};
69bcf1d3 212
db629560
FC
213print $pm "my \%noops = (\n";
214print $pm " $_ => 1,\n", for @noops;
215print $pm ");\n";
216
c22e17d0
DIM
217print $pm "my \%removed = (\n";
218print $pm " $_ => 1,\n", for @removed;
219print $pm ");\n";
220
ada44f8c
FC
221print $pm <<EOPM;
222
0bb01b05
FC
223our \$hint_shift = $HintShift;
224our \$hint_mask = $HintMask;
225our \@hint_bundles = qw( @HintedBundles );
3489ea76
FC
226
227# This gets set (for now) in \$^H as well as in %^H,
228# for runtime speed of the uc/lc/ucfirst/lcfirst functions.
229# See HINT_UNI_8_BIT in perl.h.
230our \$hint_uni8bit = $Uni8Bit;
ada44f8c
FC
231EOPM
232
69bcf1d3
FC
233
234while (<DATA>) {
2b3fe414
FC
235 last if /^PODTURES$/ ;
236 print $pm $_ ;
237}
238
239select +(select($pm), $~ = 'PODTURES')[0];
240format PODTURES =
241 ^<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<~~
242$::bundle, $::feature
243.
244
245for ('default', sort grep /\.\d[02468]/, keys %feature_bundle) {
246 $::bundle = ":$_";
247 $::feature = join ' ', @{$feature_bundle{$_}};
248 write $pm;
249 print $pm "\n";
250}
251
252while (<DATA>) {
69bcf1d3
FC
253 print $pm $_ ;
254}
255
256read_only_bottom_close_and_rename($pm);
257
c452a42f
FC
258
259###########################################################################
260# Generate feature.h
261
f2c01b15
FC
262print $h <<EOH;
263
3dd7db29
JK
264#ifndef PERL_FEATURE_H_
265#define PERL_FEATURE_H_
266
f2c01b15
FC
267#if defined(PERL_CORE) || defined (PERL_EXT)
268
269#define HINT_FEATURE_SHIFT $HintShift
270
f2c01b15
FC
271EOH
272
9f601cf3
TC
273for (sort keys %feature_bits) {
274 printf $h "#define FEATURE_%s_BIT%*s %#06x\n", uc($feature{$_}),
275 $width-length($feature{$_}), "", $feature_bits{$_};
276}
277print $h "\n";
278
f2c01b15 279my $count;
016d11cb
FC
280for (@HintedBundles) {
281 (my $key = uc) =~ y/.//d;
282 print $h "#define FEATURE_BUNDLE_$key ", $count++, "\n";
f2c01b15
FC
283}
284
7d058bc9 285print $h <<'EOH';
2b9e0ab7 286#define FEATURE_BUNDLE_CUSTOM (HINT_FEATURE_MASK >> HINT_FEATURE_SHIFT)
f2c01b15 287
7d058bc9 288#define CURRENT_HINTS \
d1fd0100 289 (PL_curcop == &PL_compiling ? PL_hints : PL_curcop->cop_hints)
035b6821
FC
290#define CURRENT_FEATURE_BUNDLE \
291 ((CURRENT_HINTS & HINT_FEATURE_MASK) >> HINT_FEATURE_SHIFT)
d1fd0100 292
fc4b5f72
NC
293/* Avoid using ... && Perl_feature_is_enabled(...) as that triggers a bug in
294 the HP-UX cc on PA-RISC */
7d058bc9 295#define FEATURE_IS_ENABLED(name) \
ef744b29 296 ((CURRENT_HINTS \
7d058bc9 297 & HINT_LOCALIZE_HH) \
fc4b5f72 298 ? Perl_feature_is_enabled(aTHX_ STR_WITH_LEN(name)) : FALSE)
9f601cf3
TC
299
300#define FEATURE_IS_ENABLED_MASK(mask) \
301 ((CURRENT_HINTS & HINT_LOCALIZE_HH) \
302 ? (PL_curcop->cop_features & (mask)) : FALSE)
303
7d058bc9 304/* The longest string we pass in. */
03222170
FC
305EOH
306
1b6e8741
FC
307my $longest_internal_feature_name = longest values %feature;
308print $h <<EOL;
309#define MAX_FEATURE_LEN (sizeof("$longest_internal_feature_name")-1)
310
311EOL
312
03222170 313for (
ebd25686 314 sort { length $a <=> length $b || $a cmp $b } keys %feature
03222170
FC
315) {
316 my($first,$last) =
317 map { (my $__ = uc) =~ y/.//d; $__ } @{$BundleRanges{$_}};
3fff3427 318 my $name = $feature{$_};
03222170 319 my $NAME = uc $name;
f298f061 320 if ($last && $first eq 'DEFAULT') { # '>= DEFAULT' warns
beda0318
FC
321 print $h <<EOI;
322#define FEATURE_$NAME\_IS_ENABLED \\
323 ( \\
324 CURRENT_FEATURE_BUNDLE <= FEATURE_BUNDLE_$last \\
325 || (CURRENT_FEATURE_BUNDLE == FEATURE_BUNDLE_CUSTOM && \\
9f601cf3 326 FEATURE_ENABLED_MASK(FEATURE_\L$name\E_BIT)) \\
beda0318
FC
327 )
328
329EOI
330 }
331 elsif ($last) {
03222170
FC
332 print $h <<EOH3;
333#define FEATURE_$NAME\_IS_ENABLED \\
334 ( \\
335 (CURRENT_FEATURE_BUNDLE >= FEATURE_BUNDLE_$first && \\
336 CURRENT_FEATURE_BUNDLE <= FEATURE_BUNDLE_$last) \\
337 || (CURRENT_FEATURE_BUNDLE == FEATURE_BUNDLE_CUSTOM && \\
9f601cf3 338 FEATURE_IS_ENABLED_MASK(FEATURE_\U$name\E_BIT)) \\
03222170
FC
339 )
340
341EOH3
342 }
ebd25686 343 elsif ($first) {
03222170
FC
344 print $h <<EOH4;
345#define FEATURE_$NAME\_IS_ENABLED \\
346 ( \\
347 CURRENT_FEATURE_BUNDLE == FEATURE_BUNDLE_$first \\
348 || (CURRENT_FEATURE_BUNDLE == FEATURE_BUNDLE_CUSTOM && \\
9f601cf3 349 FEATURE_IS_ENABLED_MASK(FEATURE_\U$name\E_BIT)) \\
03222170
FC
350 )
351
352EOH4
353 }
ebd25686
FC
354 else {
355 print $h <<EOH5;
356#define FEATURE_$NAME\_IS_ENABLED \\
357 ( \\
358 CURRENT_FEATURE_BUNDLE == FEATURE_BUNDLE_CUSTOM && \\
9f601cf3 359 FEATURE_IS_ENABLED_MASK(FEATURE_\U$name\E_BIT) \\
ebd25686
FC
360 )
361
362EOH5
363 }
03222170
FC
364}
365
366print $h <<EOH;
367
9f601cf3
TC
368#define SAVEFEATUREBITS() SAVEI32(PL_compiling.cop_features)
369
370#define CLEARFEATUREBITS() (PL_compiling.cop_features = 0)
371
372#define STOREFEATUREBITSHH(hh) \\
373 (hv_stores((hh), "feature/bits", newSVuv(PL_compiling.cop_features)))
374
375#define FETCHFEATUREBITSHH(hh) \\
376 STMT_START { \\
377 SV **fbsv = hv_fetchs((hh), "feature/bits", FALSE); \\
378 PL_compiling.cop_features = fbsv ? SvUV(*fbsv) : 0; \\
379 } STMT_END
380
f2c01b15 381#endif /* PERL_CORE or PERL_EXT */
4160ddbd
FC
382
383#ifdef PERL_IN_OP_C
384PERL_STATIC_INLINE void
385S_enable_feature_bundle(pTHX_ SV *ver)
386{
387 SV *comp_ver = sv_newmortal();
388 PL_hints = (PL_hints &~ HINT_FEATURE_MASK)
389 | (
f2c01b15
FC
390EOH
391
4160ddbd
FC
392for (reverse @HintedBundles[1..$#HintedBundles]) { # skip default
393 my $numver = $_;
394 if ($numver eq '5.10') { $numver = '5.009005' } # special case
395 else { $numver =~ s/\./.0/ } # 5.11 => 5.011
396 (my $macrover = $_) =~ y/.//d;
397 print $h <<" EOK";
398 (sv_setnv(comp_ver, $numver),
399 vcmp(ver, upg_version(comp_ver, FALSE)) >= 0)
400 ? FEATURE_BUNDLE_$macrover :
401 EOK
402}
403
404print $h <<EOJ;
405 FEATURE_BUNDLE_DEFAULT
406 ) << HINT_FEATURE_SHIFT;
6389c777
FC
407 /* special case */
408 assert(PL_curcop == &PL_compiling);
409 if (FEATURE_UNICODE_IS_ENABLED) PL_hints |= HINT_UNI_8_BIT;
410 else PL_hints &= ~HINT_UNI_8_BIT;
4160ddbd
FC
411}
412#endif /* PERL_IN_OP_C */
3dd7db29
JK
413
414#endif /* PERL_FEATURE_H_ */
4160ddbd
FC
415EOJ
416
f2c01b15
FC
417read_only_bottom_close_and_rename($h);
418
c452a42f
FC
419
420###########################################################################
421# Template for feature.pm
422
69bcf1d3
FC
423__END__
424package feature;
425
9f601cf3 426our $VERSION = '1.56';
69bcf1d3
FC
427
428FEATURES
429
69bcf1d3
FC
430# TODO:
431# - think about versioned features (use feature switch => 2)
432
433=head1 NAME
434
435feature - Perl pragma to enable new features
436
437=head1 SYNOPSIS
438
439 use feature qw(say switch);
440 given ($foo) {
441 when (1) { say "\$foo == 1" }
442 when ([2,3]) { say "\$foo == 2 || \$foo == 3" }
443 when (/^a[bc]d$/) { say "\$foo eq 'abd' || \$foo eq 'acd'" }
444 when ($_ > 100) { say "\$foo > 100" }
445 default { say "None of the above" }
446 }
447
448 use feature ':5.10'; # loads all features available in perl 5.10
449
450 use v5.10; # implicitly loads :5.10 feature bundle
451
452=head1 DESCRIPTION
453
454It is usually impossible to add new syntax to Perl without breaking
455some existing programs. This pragma provides a way to minimize that
456risk. New syntactic constructs, or new semantic meanings to older
457constructs, can be enabled by C<use feature 'foo'>, and will be parsed
458only when the appropriate feature pragma is in scope. (Nevertheless, the
459C<CORE::> prefix provides access to all Perl keywords, regardless of this
460pragma.)
461
462=head2 Lexical effect
463
464Like other pragmas (C<use strict>, for example), features have a lexical
301381dc 465effect. C<use feature qw(foo)> will only make the feature "foo" available
69bcf1d3
FC
466from that point to the end of the enclosing block.
467
468 {
469 use feature 'say';
470 say "say is available here";
471 }
472 print "But not here.\n";
473
474=head2 C<no feature>
475
476Features can also be turned off by using C<no feature "foo">. This too
477has lexical effect.
478
479 use feature 'say';
480 say "say is available here";
481 {
482 no feature 'say';
483 print "But not here.\n";
484 }
485 say "Yet it is here.";
486
39ec54a5
RS
487C<no feature> with no features specified will reset to the default group. To
488disable I<all> features (an unusual request!) use C<no feature ':all'>.
69bcf1d3
FC
489
490=head1 AVAILABLE FEATURES
491
492=head2 The 'say' feature
493
494C<use feature 'say'> tells the compiler to enable the Perl 6 style
495C<say> function.
496
497See L<perlfunc/say> for details.
498
499This feature is available starting with Perl 5.10.
500
501=head2 The 'state' feature
502
503C<use feature 'state'> tells the compiler to enable C<state>
504variables.
505
506See L<perlsub/"Persistent Private Variables"> for details.
507
508This feature is available starting with Perl 5.10.
509
510=head2 The 'switch' feature
511
7caca87c
DB
512B<WARNING>: Because the L<smartmatch operator|perlop/"Smartmatch Operator"> is
513experimental, Perl will warn when you use this feature, unless you have
514explicitly disabled the warning:
515
516 no warnings "experimental::smartmatch";
517
7896dde7 518C<use feature 'switch'> tells the compiler to enable the Perl 6
69bcf1d3
FC
519given/when construct.
520
48238296 521See L<perlsyn/"Switch Statements"> for details.
69bcf1d3
FC
522
523This feature is available starting with Perl 5.10.
524
525=head2 The 'unicode_strings' feature
526
850b7ec9 527C<use feature 'unicode_strings'> tells the compiler to use Unicode rules
69bcf1d3
FC
528in all string operations executed within its scope (unless they are also
529within the scope of either C<use locale> or C<use bytes>). The same applies
530to all regular expressions compiled within the scope, even if executed outside
2269d15c
KW
531it. It does not change the internal representation of strings, but only how
532they are interpreted.
69bcf1d3
FC
533
534C<no feature 'unicode_strings'> tells the compiler to use the traditional
850b7ec9 535Perl rules wherein the native character set rules is used unless it is
69bcf1d3
FC
536clear to Perl that Unicode is desired. This can lead to some surprises
537when the behavior suddenly changes. (See
538L<perlunicode/The "Unicode Bug"> for details.) For this reason, if you are
539potentially using Unicode in your program, the
540C<use feature 'unicode_strings'> subpragma is B<strongly> recommended.
541
2e2b2571 542This feature is available starting with Perl 5.12; was almost fully
d6c970c7 543implemented in Perl 5.14; and extended in Perl 5.16 to cover C<quotemeta>;
20ae58f7
AC
544was extended further in Perl 5.26 to cover L<the range
545operator|perlop/Range Operators>; and was extended again in Perl 5.28 to
546cover L<special-cased whitespace splitting|perlfunc/split>.
69bcf1d3
FC
547
548=head2 The 'unicode_eval' and 'evalbytes' features
549
9891e9b7
KW
550Together, these two features are intended to replace the legacy string
551C<eval> function, which behaves problematically in some instances. They are
552available starting with Perl 5.16, and are enabled by default by a
553S<C<use 5.16>> or higher declaration.
554
555C<unicode_eval> changes the behavior of plain string C<eval> to work more
556consistently, especially in the Unicode world. Certain (mis)behaviors
557couldn't be changed without breaking some things that had come to rely on
558them, so the feature can be enabled and disabled. Details are at
559L<perlfunc/Under the "unicode_eval" feature>.
560
561C<evalbytes> is like string C<eval>, but operating on a byte stream that is
562not UTF-8 encoded. Details are at L<perlfunc/evalbytes EXPR>. Without a
563S<C<use feature 'evalbytes'>> nor a S<C<use v5.16>> (or higher) declaration in
564the current scope, you can still access it by instead writing
565C<CORE::evalbytes>.
69bcf1d3
FC
566
567=head2 The 'current_sub' feature
568
569This provides the C<__SUB__> token that returns a reference to the current
570subroutine or C<undef> outside of a subroutine.
571
572This feature is available starting with Perl 5.16.
573
574=head2 The 'array_base' feature
575
c22e17d0
DIM
576This feature supported the legacy C<$[> variable. See L<perlvar/$[>.
577It was on by default but disabled under C<use v5.16> (see
578L</IMPLICIT LOADING>, below) and unavailable since perl 5.30.
69bcf1d3
FC
579
580This feature is available under this name starting with Perl 5.16. In
581previous versions, it was simply on all the time, and this pragma knew
582nothing about it.
583
2a4315f8
BF
584=head2 The 'fc' feature
585
586C<use feature 'fc'> tells the compiler to enable the C<fc> function,
587which implements Unicode casefolding.
588
589See L<perlfunc/fc> for details.
590
591This feature is available from Perl 5.16 onwards.
592
ca40957e
FC
593=head2 The 'lexical_subs' feature
594
8f7d85af
FC
595In Perl versions prior to 5.26, this feature enabled
596declaration of subroutines via C<my sub foo>, C<state sub foo>
597and C<our sub foo> syntax. See L<perlsub/Lexical Subroutines> for details.
ca40957e 598
8f7d85af
FC
599This feature is available from Perl 5.18 onwards. From Perl 5.18 to 5.24,
600it was classed as experimental, and Perl emitted a warning for its
601usage, except when explicitly disabled:
ca40957e 602
8f7d85af 603 no warnings "experimental::lexical_subs";
ca40957e 604
8f7d85af
FC
605As of Perl 5.26, use of this feature no longer triggers a warning, though
606the C<experimental::lexical_subs> warning category still exists (for
607compatibility with code that disables it). In addition, this syntax is
608not only no longer experimental, but it is enabled for all Perl code,
609regardless of what feature declarations are in scope.
ca40957e 610
f86d720e
RS
611=head2 The 'postderef' and 'postderef_qq' features
612
1c2511e0
AC
613The 'postderef_qq' feature extends the applicability of L<postfix
614dereference syntax|perlref/Postfix Dereference Syntax> so that postfix array
615and scalar dereference are available in double-quotish interpolations. For
616example, it makes the following two statements equivalent:
f86d720e 617
1c2511e0
AC
618 my $s = "[@{ $h->{a} }]";
619 my $s = "[$h->{a}->@*]";
f86d720e 620
1c2511e0
AC
621This feature is available from Perl 5.20 onwards. In Perl 5.20 and 5.22, it
622was classed as experimental, and Perl emitted a warning for its
2ad792cd
AC
623usage, except when explicitly disabled:
624
625 no warnings "experimental::postderef";
626
1c2511e0 627As of Perl 5.24, use of this feature no longer triggers a warning, though
2ad792cd
AC
628the C<experimental::postderef> warning category still exists (for
629compatibility with code that disables it).
f86d720e 630
1c2511e0
AC
631The 'postderef' feature was used in Perl 5.20 and Perl 5.22 to enable
632postfix dereference syntax outside double-quotish interpolations. In those
633versions, using it triggered the C<experimental::postderef> warning in the
634same way as the 'postderef_qq' feature did. As of Perl 5.24, this syntax is
635not only no longer experimental, but it is enabled for all Perl code,
636regardless of what feature declarations are in scope.
637
30d9c59b
Z
638=head2 The 'signatures' feature
639
640B<WARNING>: This feature is still experimental and the implementation may
641change in future versions of Perl. For this reason, Perl will
642warn when you use the feature, unless you have explicitly disabled the
643warning:
644
645 no warnings "experimental::signatures";
646
647This enables unpacking of subroutine arguments into lexical variables
648by syntax such as
649
650 sub foo ($left, $right) {
651 return $left + $right;
652 }
653
654See L<perlsub/Signatures> for details.
655
656This feature is available from Perl 5.20 onwards.
657
baabe3fb 658=head2 The 'refaliasing' feature
82848c10
FC
659
660B<WARNING>: This feature is still experimental and the implementation may
661change in future versions of Perl. For this reason, Perl will
662warn when you use the feature, unless you have explicitly disabled the
663warning:
664
baabe3fb 665 no warnings "experimental::refaliasing";
82848c10
FC
666
667This enables aliasing via assignment to references:
668
669 \$a = \$b; # $a and $b now point to the same scalar
670 \@a = \@b; # to the same array
671 \%a = \%b;
672 \&a = \&b;
673 foreach \%hash (@array_of_hash_refs) {
674 ...
675 }
676
677See L<perlref/Assigning to References> for details.
678
679This feature is available from Perl 5.22 onwards.
680
70ea8edf
FC
681=head2 The 'bitwise' feature
682
70ea8edf
FC
683This makes the four standard bitwise operators (C<& | ^ ~>) treat their
684operands consistently as numbers, and introduces four new dotted operators
685(C<&. |. ^. ~.>) that treat their operands consistently as strings. The
686same applies to the assignment variants (C<&= |= ^= &.= |.= ^.=>).
687
688See L<perlop/Bitwise String Operators> for details.
689
193789ac
FC
690This feature is available from Perl 5.22 onwards. Starting in Perl 5.28,
691C<use v5.28> will enable the feature. Before 5.28, it was still
692experimental and would emit a warning in the "experimental::bitwise"
693category.
70ea8edf 694
5c703779
FC
695=head2 The 'declared_refs' feature
696
697B<WARNING>: This feature is still experimental and the implementation may
698change in future versions of Perl. For this reason, Perl will
699warn when you use the feature, unless you have explicitly disabled the
700warning:
701
702 no warnings "experimental::declared_refs";
703
704This allows a reference to a variable to be declared with C<my>, C<state>,
705our C<our>, or localized with C<local>. It is intended mainly for use in
706conjunction with the "refaliasing" feature. See L<perlref/Declaring a
707Reference to a Variable> for examples.
708
709This feature is available from Perl 5.26 onwards.
710
69bcf1d3
FC
711=head1 FEATURE BUNDLES
712
713It's possible to load multiple features together, using
714a I<feature bundle>. The name of a feature bundle is prefixed with
715a colon, to distinguish it from an actual feature.
716
717 use feature ":5.10";
718
719The following feature bundles are available:
720
721 bundle features included
722 --------- -----------------
2b3fe414 723PODTURES
69bcf1d3
FC
724The C<:default> bundle represents the feature set that is enabled before
725any C<use feature> or C<no feature> declaration.
726
727Specifying sub-versions such as the C<0> in C<5.14.0> in feature bundles has
728no effect. Feature bundles are guaranteed to be the same for all sub-versions.
729
730 use feature ":5.14.0"; # same as ":5.14"
731 use feature ":5.14.1"; # same as ":5.14"
732
733=head1 IMPLICIT LOADING
734
735Instead of loading feature bundles by name, it is easier to let Perl do
736implicit loading of a feature bundle for you.
737
738There are two ways to load the C<feature> pragma implicitly:
739
740=over 4
741
742=item *
743
744By using the C<-E> switch on the Perl command-line instead of C<-e>.
745That will enable the feature bundle for that version of Perl in the
746main compilation unit (that is, the one-liner that follows C<-E>).
747
748=item *
749
750By explicitly requiring a minimum Perl version number for your program, with
751the C<use VERSION> construct. That is,
752
753 use v5.10.0;
754
755will do an implicit
756
39ec54a5 757 no feature ':all';
69bcf1d3
FC
758 use feature ':5.10';
759
760and so on. Note how the trailing sub-version
761is automatically stripped from the
762version.
763
764But to avoid portability warnings (see L<perlfunc/use>), you may prefer:
765
766 use 5.010;
767
768with the same effect.
769
770If the required version is older than Perl 5.10, the ":default" feature
771bundle is automatically loaded instead.
772
affe54fa
AC
773Unlike C<use feature ":5.12">, saying C<use v5.12> (or any higher version)
774also does the equivalent of C<use strict>; see L<perlfunc/use> for details.
775
69bcf1d3
FC
776=back
777
778=cut
779
780sub import {
22055af9 781 shift;
36143a0c
NC
782
783 if (!@_) {
69bcf1d3
FC
784 croak("No features specified");
785 }
36143a0c 786
d3757264 787 __common(1, @_);
69bcf1d3
FC
788}
789
790sub unimport {
22055af9 791 shift;
69bcf1d3 792
39ec54a5 793 # A bare C<no feature> should reset to the default bundle
69bcf1d3 794 if (!@_) {
39ec54a5
RS
795 $^H &= ~($hint_uni8bit|$hint_mask);
796 return;
69bcf1d3
FC
797 }
798
d3757264
NC
799 __common(0, @_);
800}
801
802
803sub __common {
804 my $import = shift;
0c8d5017
NC
805 my $bundle_number = $^H & $hint_mask;
806 my $features = $bundle_number != $hint_mask
9f601cf3
TC
807 && $feature_bundle{$hint_bundles[$bundle_number >> $hint_shift]};
808 my $bits = ${^FEATURE_BITS};
0c8d5017 809 if ($features) {
da5b5421 810 # Features are enabled implicitly via bundle hints.
d9ee6ccb
NC
811 # Delete any keys that may be left over from last time.
812 delete @^H{ values(%feature) };
9f601cf3 813 $bits = 0;
d9ee6ccb
NC
814 $^H |= $hint_mask;
815 for (@$features) {
816 $^H{$feature{$_}} = 1;
9f601cf3 817 $bits |= $feature_bits{$_};
d9ee6ccb
NC
818 $^H |= $hint_uni8bit if $_ eq 'unicode_strings';
819 }
da5b5421 820 }
69bcf1d3
FC
821 while (@_) {
822 my $name = shift;
823 if (substr($name, 0, 1) eq ":") {
824 my $v = substr($name, 1);
825 if (!exists $feature_bundle{$v}) {
826 $v =~ s/^([0-9]+)\.([0-9]+).[0-9]+$/$1.$2/;
827 if (!exists $feature_bundle{$v}) {
828 unknown_feature_bundle(substr($name, 1));
829 }
830 }
831 unshift @_, @{$feature_bundle{$v}};
832 next;
833 }
36143a0c 834 if (!exists $feature{$name}) {
db629560
FC
835 if (exists $noops{$name}) {
836 next;
837 }
c22e17d0
DIM
838 if (!$import && exists $removed{$name}) {
839 next;
840 }
69bcf1d3 841 unknown_feature($name);
69bcf1d3 842 }
d3757264
NC
843 if ($import) {
844 $^H{$feature{$name}} = 1;
9f601cf3 845 $bits |= $feature_bits{$name};
d3757264
NC
846 $^H |= $hint_uni8bit if $name eq 'unicode_strings';
847 } else {
69bcf1d3 848 delete $^H{$feature{$name}};
9f601cf3 849 $bits &= ~$feature_bits{$name};
69bcf1d3
FC
850 $^H &= ~ $hint_uni8bit if $name eq 'unicode_strings';
851 }
852 }
9f601cf3 853 ${^FEATURE_BITS} = $bits;
69bcf1d3
FC
854}
855
856sub unknown_feature {
857 my $feature = shift;
858 croak(sprintf('Feature "%s" is not supported by Perl %vd',
859 $feature, $^V));
860}
861
862sub unknown_feature_bundle {
863 my $feature = shift;
864 croak(sprintf('Feature bundle "%s" is not supported by Perl %vd',
865 $feature, $^V));
866}
867
868sub croak {
869 require Carp;
870 Carp::croak(@_);
871}
872
8731;