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