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!
13 state => 'feature_state',
14 switch => 'feature_switch',
15 bitwise => 'feature_bitwise',
16 evalbytes => 'feature_evalbytes',
17 signatures => 'feature_signatures',
18 current_sub => 'feature___SUB__',
19 refaliasing => 'feature_refaliasing',
20 postderef_qq => 'feature_postderef_qq',
21 unicode_eval => 'feature_unieval',
22 declared_refs => 'feature_myref',
23 unicode_strings => 'feature_unicode',
26 our %feature_bundle = (
27 "5.10" => [qw(say state switch)],
28 "5.11" => [qw(say state switch unicode_strings)],
29 "5.15" => [qw(current_sub evalbytes fc say state switch unicode_eval unicode_strings)],
30 "5.23" => [qw(current_sub evalbytes fc postderef_qq say state switch unicode_eval unicode_strings)],
31 "5.27" => [qw(bitwise current_sub evalbytes fc postderef_qq say state switch unicode_eval unicode_strings)],
32 "all" => [qw(bitwise current_sub declared_refs evalbytes fc postderef_qq refaliasing say signatures state switch unicode_eval unicode_strings)],
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.24"} = $feature_bundle{"5.23"};
47 $feature_bundle{"5.25"} = $feature_bundle{"5.23"};
48 $feature_bundle{"5.26"} = $feature_bundle{"5.23"};
49 $feature_bundle{"5.28"} = $feature_bundle{"5.27"};
50 $feature_bundle{"5.29"} = $feature_bundle{"5.27"};
51 $feature_bundle{"5.30"} = $feature_bundle{"5.27"};
52 $feature_bundle{"5.9.5"} = $feature_bundle{"5.10"};
62 our $hint_mask = 0x1c000000;
63 our @hint_bundles = qw( default 5.10 5.11 5.15 5.23 5.27 );
65 # This gets set (for now) in $^H as well as in %^H,
66 # for runtime speed of the uc/lc/ucfirst/lcfirst functions.
67 # See HINT_UNI_8_BIT in perl.h.
68 our $hint_uni8bit = 0x00000800;
71 # - think about versioned features (use feature switch => 2)
75 feature - Perl pragma to enable new features
79 use feature qw(say switch);
81 when (1) { say "\$foo == 1" }
82 when ([2,3]) { say "\$foo == 2 || \$foo == 3" }
83 when (/^a[bc]d$/) { say "\$foo eq 'abd' || \$foo eq 'acd'" }
84 when ($_ > 100) { say "\$foo > 100" }
85 default { say "None of the above" }
88 use feature ':5.10'; # loads all features available in perl 5.10
90 use v5.10; # implicitly loads :5.10 feature bundle
94 It is usually impossible to add new syntax to Perl without breaking
95 some existing programs. This pragma provides a way to minimize that
96 risk. New syntactic constructs, or new semantic meanings to older
97 constructs, can be enabled by C<use feature 'foo'>, and will be parsed
98 only when the appropriate feature pragma is in scope. (Nevertheless, the
99 C<CORE::> prefix provides access to all Perl keywords, regardless of this
102 =head2 Lexical effect
104 Like other pragmas (C<use strict>, for example), features have a lexical
105 effect. C<use feature qw(foo)> will only make the feature "foo" available
106 from that point to the end of the enclosing block.
110 say "say is available here";
112 print "But not here.\n";
116 Features can also be turned off by using C<no feature "foo">. This too
120 say "say is available here";
123 print "But not here.\n";
125 say "Yet it is here.";
127 C<no feature> with no features specified will reset to the default group. To
128 disable I<all> features (an unusual request!) use C<no feature ':all'>.
130 =head1 AVAILABLE FEATURES
132 =head2 The 'say' feature
134 C<use feature 'say'> tells the compiler to enable the Perl 6 style
137 See L<perlfunc/say> for details.
139 This feature is available starting with Perl 5.10.
141 =head2 The 'state' feature
143 C<use feature 'state'> tells the compiler to enable C<state>
146 See L<perlsub/"Persistent Private Variables"> for details.
148 This feature is available starting with Perl 5.10.
150 =head2 The 'switch' feature
152 B<WARNING>: Because the L<smartmatch operator|perlop/"Smartmatch Operator"> is
153 experimental, Perl will warn when you use this feature, unless you have
154 explicitly disabled the warning:
156 no warnings "experimental::smartmatch";
158 C<use feature 'switch'> tells the compiler to enable the Perl 6
159 given/when construct.
161 See L<perlsyn/"Switch Statements"> for details.
163 This feature is available starting with Perl 5.10.
165 =head2 The 'unicode_strings' feature
167 C<use feature 'unicode_strings'> tells the compiler to use Unicode rules
168 in all string operations executed within its scope (unless they are also
169 within the scope of either C<use locale> or C<use bytes>). The same applies
170 to all regular expressions compiled within the scope, even if executed outside
171 it. It does not change the internal representation of strings, but only how
172 they are interpreted.
174 C<no feature 'unicode_strings'> tells the compiler to use the traditional
175 Perl rules wherein the native character set rules is used unless it is
176 clear to Perl that Unicode is desired. This can lead to some surprises
177 when the behavior suddenly changes. (See
178 L<perlunicode/The "Unicode Bug"> for details.) For this reason, if you are
179 potentially using Unicode in your program, the
180 C<use feature 'unicode_strings'> subpragma is B<strongly> recommended.
182 This feature is available starting with Perl 5.12; was almost fully
183 implemented in Perl 5.14; and extended in Perl 5.16 to cover C<quotemeta>;
184 was extended further in Perl 5.26 to cover L<the range
185 operator|perlop/Range Operators>; and was extended again in Perl 5.28 to
186 cover L<special-cased whitespace splitting|perlfunc/split>.
188 =head2 The 'unicode_eval' and 'evalbytes' features
190 Together, these two features are intended to replace the legacy string
191 C<eval> function, which behaves problematically in some instances. They are
192 available starting with Perl 5.16, and are enabled by default by a
193 S<C<use 5.16>> or higher declaration.
195 C<unicode_eval> changes the behavior of plain string C<eval> to work more
196 consistently, especially in the Unicode world. Certain (mis)behaviors
197 couldn't be changed without breaking some things that had come to rely on
198 them, so the feature can be enabled and disabled. Details are at
199 L<perlfunc/Under the "unicode_eval" feature>.
201 C<evalbytes> is like string C<eval>, but operating on a byte stream that is
202 not UTF-8 encoded. Details are at L<perlfunc/evalbytes EXPR>. Without a
203 S<C<use feature 'evalbytes'>> nor a S<C<use v5.16>> (or higher) declaration in
204 the current scope, you can still access it by instead writing
207 =head2 The 'current_sub' feature
209 This provides the C<__SUB__> token that returns a reference to the current
210 subroutine or C<undef> outside of a subroutine.
212 This feature is available starting with Perl 5.16.
214 =head2 The 'array_base' feature
216 This feature supported the legacy C<$[> variable. See L<perlvar/$[>.
217 It was on by default but disabled under C<use v5.16> (see
218 L</IMPLICIT LOADING>, below) and unavailable since perl 5.30.
220 This feature is available under this name starting with Perl 5.16. In
221 previous versions, it was simply on all the time, and this pragma knew
224 =head2 The 'fc' feature
226 C<use feature 'fc'> tells the compiler to enable the C<fc> function,
227 which implements Unicode casefolding.
229 See L<perlfunc/fc> for details.
231 This feature is available from Perl 5.16 onwards.
233 =head2 The 'lexical_subs' feature
235 In Perl versions prior to 5.26, this feature enabled
236 declaration of subroutines via C<my sub foo>, C<state sub foo>
237 and C<our sub foo> syntax. See L<perlsub/Lexical Subroutines> for details.
239 This feature is available from Perl 5.18 onwards. From Perl 5.18 to 5.24,
240 it was classed as experimental, and Perl emitted a warning for its
241 usage, except when explicitly disabled:
243 no warnings "experimental::lexical_subs";
245 As of Perl 5.26, use of this feature no longer triggers a warning, though
246 the C<experimental::lexical_subs> warning category still exists (for
247 compatibility with code that disables it). In addition, this syntax is
248 not only no longer experimental, but it is enabled for all Perl code,
249 regardless of what feature declarations are in scope.
251 =head2 The 'postderef' and 'postderef_qq' features
253 The 'postderef_qq' feature extends the applicability of L<postfix
254 dereference syntax|perlref/Postfix Dereference Syntax> so that postfix array
255 and scalar dereference are available in double-quotish interpolations. For
256 example, it makes the following two statements equivalent:
258 my $s = "[@{ $h->{a} }]";
259 my $s = "[$h->{a}->@*]";
261 This feature is available from Perl 5.20 onwards. In Perl 5.20 and 5.22, it
262 was classed as experimental, and Perl emitted a warning for its
263 usage, except when explicitly disabled:
265 no warnings "experimental::postderef";
267 As of Perl 5.24, use of this feature no longer triggers a warning, though
268 the C<experimental::postderef> warning category still exists (for
269 compatibility with code that disables it).
271 The 'postderef' feature was used in Perl 5.20 and Perl 5.22 to enable
272 postfix dereference syntax outside double-quotish interpolations. In those
273 versions, using it triggered the C<experimental::postderef> warning in the
274 same way as the 'postderef_qq' feature did. As of Perl 5.24, this syntax is
275 not only no longer experimental, but it is enabled for all Perl code,
276 regardless of what feature declarations are in scope.
278 =head2 The 'signatures' feature
280 B<WARNING>: This feature is still experimental and the implementation may
281 change in future versions of Perl. For this reason, Perl will
282 warn when you use the feature, unless you have explicitly disabled the
285 no warnings "experimental::signatures";
287 This enables unpacking of subroutine arguments into lexical variables
290 sub foo ($left, $right) {
291 return $left + $right;
294 See L<perlsub/Signatures> for details.
296 This feature is available from Perl 5.20 onwards.
298 =head2 The 'refaliasing' feature
300 B<WARNING>: This feature is still experimental and the implementation may
301 change in future versions of Perl. For this reason, Perl will
302 warn when you use the feature, unless you have explicitly disabled the
305 no warnings "experimental::refaliasing";
307 This enables aliasing via assignment to references:
309 \$a = \$b; # $a and $b now point to the same scalar
310 \@a = \@b; # to the same array
313 foreach \%hash (@array_of_hash_refs) {
317 See L<perlref/Assigning to References> for details.
319 This feature is available from Perl 5.22 onwards.
321 =head2 The 'bitwise' feature
323 This makes the four standard bitwise operators (C<& | ^ ~>) treat their
324 operands consistently as numbers, and introduces four new dotted operators
325 (C<&. |. ^. ~.>) that treat their operands consistently as strings. The
326 same applies to the assignment variants (C<&= |= ^= &.= |.= ^.=>).
328 See L<perlop/Bitwise String Operators> for details.
330 This feature is available from Perl 5.22 onwards. Starting in Perl 5.28,
331 C<use v5.28> will enable the feature. Before 5.28, it was still
332 experimental and would emit a warning in the "experimental::bitwise"
335 =head2 The 'declared_refs' feature
337 B<WARNING>: This feature is still experimental and the implementation may
338 change in future versions of Perl. For this reason, Perl will
339 warn when you use the feature, unless you have explicitly disabled the
342 no warnings "experimental::declared_refs";
344 This allows a reference to a variable to be declared with C<my>, C<state>,
345 our C<our>, or localized with C<local>. It is intended mainly for use in
346 conjunction with the "refaliasing" feature. See L<perlref/Declaring a
347 Reference to a Variable> for examples.
349 This feature is available from Perl 5.26 onwards.
351 =head1 FEATURE BUNDLES
353 It's possible to load multiple features together, using
354 a I<feature bundle>. The name of a feature bundle is prefixed with
355 a colon, to distinguish it from an actual feature.
359 The following feature bundles are available:
361 bundle features included
362 --------- -----------------
365 :5.10 say state switch
367 :5.12 say state switch unicode_strings
369 :5.14 say state switch unicode_strings
371 :5.16 say state switch unicode_strings
372 unicode_eval evalbytes current_sub fc
374 :5.18 say state switch unicode_strings
375 unicode_eval evalbytes current_sub fc
377 :5.20 say state switch unicode_strings
378 unicode_eval evalbytes current_sub fc
380 :5.22 say state switch unicode_strings
381 unicode_eval evalbytes current_sub fc
383 :5.24 say state switch unicode_strings
384 unicode_eval evalbytes current_sub fc
387 :5.26 say state switch unicode_strings
388 unicode_eval evalbytes current_sub fc
391 :5.28 say state switch unicode_strings
392 unicode_eval evalbytes current_sub fc
395 :5.30 say state switch unicode_strings
396 unicode_eval evalbytes current_sub fc
399 The C<:default> bundle represents the feature set that is enabled before
400 any C<use feature> or C<no feature> declaration.
402 Specifying sub-versions such as the C<0> in C<5.14.0> in feature bundles has
403 no effect. Feature bundles are guaranteed to be the same for all sub-versions.
405 use feature ":5.14.0"; # same as ":5.14"
406 use feature ":5.14.1"; # same as ":5.14"
408 =head1 IMPLICIT LOADING
410 Instead of loading feature bundles by name, it is easier to let Perl do
411 implicit loading of a feature bundle for you.
413 There are two ways to load the C<feature> pragma implicitly:
419 By using the C<-E> switch on the Perl command-line instead of C<-e>.
420 That will enable the feature bundle for that version of Perl in the
421 main compilation unit (that is, the one-liner that follows C<-E>).
425 By explicitly requiring a minimum Perl version number for your program, with
426 the C<use VERSION> construct. That is,
435 and so on. Note how the trailing sub-version
436 is automatically stripped from the
439 But to avoid portability warnings (see L<perlfunc/use>), you may prefer:
443 with the same effect.
445 If the required version is older than Perl 5.10, the ":default" feature
446 bundle is automatically loaded instead.
448 Unlike C<use feature ":5.12">, saying C<use v5.12> (or any higher version)
449 also does the equivalent of C<use strict>; see L<perlfunc/use> for details.
459 croak("No features specified");
468 # A bare C<no feature> should reset to the default bundle
470 $^H &= ~($hint_uni8bit|$hint_mask);
480 my $bundle_number = $^H & $hint_mask;
481 my $features = $bundle_number != $hint_mask
482 && $feature_bundle{$hint_bundles[$bundle_number >> $hint_shift]};
484 # Features are enabled implicitly via bundle hints.
485 # Delete any keys that may be left over from last time.
486 delete @^H{ values(%feature) };
489 $^H{$feature{$_}} = 1;
490 $^H |= $hint_uni8bit if $_ eq 'unicode_strings';
495 if (substr($name, 0, 1) eq ":") {
496 my $v = substr($name, 1);
497 if (!exists $feature_bundle{$v}) {
498 $v =~ s/^([0-9]+)\.([0-9]+).[0-9]+$/$1.$2/;
499 if (!exists $feature_bundle{$v}) {
500 unknown_feature_bundle(substr($name, 1));
503 unshift @_, @{$feature_bundle{$v}};
506 if (!exists $feature{$name}) {
507 if (exists $noops{$name}) {
510 if (!$import && exists $removed{$name}) {
513 unknown_feature($name);
516 $^H{$feature{$name}} = 1;
517 $^H |= $hint_uni8bit if $name eq 'unicode_strings';
519 delete $^H{$feature{$name}};
520 $^H &= ~ $hint_uni8bit if $name eq 'unicode_strings';
525 sub unknown_feature {
527 croak(sprintf('Feature "%s" is not supported by Perl %vd',
531 sub unknown_feature_bundle {
533 croak(sprintf('Feature bundle "%s" is not supported by Perl %vd',