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!
15 state => 'feature_state',
16 switch => 'feature_switch',
17 bitwise => 'feature_bitwise',
18 indirect => 'feature_indirect',
19 evalbytes => 'feature_evalbytes',
20 signatures => 'feature_signatures',
21 current_sub => 'feature___SUB__',
22 refaliasing => 'feature_refaliasing',
23 postderef_qq => 'feature_postderef_qq',
24 unicode_eval => 'feature_unieval',
25 declared_refs => 'feature_myref',
26 unicode_strings => 'feature_unicode',
27 multidimensional => 'feature_multidimensional',
28 bareword_filehandles => 'feature_bareword_filehandles',
31 our %feature_bundle = (
32 "5.10" => [qw(bareword_filehandles indirect multidimensional say state switch)],
33 "5.11" => [qw(bareword_filehandles indirect multidimensional say state switch unicode_strings)],
34 "5.15" => [qw(bareword_filehandles current_sub evalbytes fc indirect multidimensional say state switch unicode_eval unicode_strings)],
35 "5.23" => [qw(bareword_filehandles current_sub evalbytes fc indirect multidimensional postderef_qq say state switch unicode_eval unicode_strings)],
36 "5.27" => [qw(bareword_filehandles bitwise current_sub evalbytes fc indirect multidimensional postderef_qq say state switch unicode_eval unicode_strings)],
37 "5.35" => [qw(bareword_filehandles bitwise current_sub evalbytes fc indirect multidimensional postderef_qq say state unicode_eval unicode_strings)],
38 "all" => [qw(bareword_filehandles bitwise current_sub declared_refs evalbytes fc indirect isa multidimensional postderef_qq refaliasing say signatures state switch try unicode_eval unicode_strings)],
39 "default" => [qw(bareword_filehandles indirect multidimensional)],
42 $feature_bundle{"5.12"} = $feature_bundle{"5.11"};
43 $feature_bundle{"5.13"} = $feature_bundle{"5.11"};
44 $feature_bundle{"5.14"} = $feature_bundle{"5.11"};
45 $feature_bundle{"5.16"} = $feature_bundle{"5.15"};
46 $feature_bundle{"5.17"} = $feature_bundle{"5.15"};
47 $feature_bundle{"5.18"} = $feature_bundle{"5.15"};
48 $feature_bundle{"5.19"} = $feature_bundle{"5.15"};
49 $feature_bundle{"5.20"} = $feature_bundle{"5.15"};
50 $feature_bundle{"5.21"} = $feature_bundle{"5.15"};
51 $feature_bundle{"5.22"} = $feature_bundle{"5.15"};
52 $feature_bundle{"5.24"} = $feature_bundle{"5.23"};
53 $feature_bundle{"5.25"} = $feature_bundle{"5.23"};
54 $feature_bundle{"5.26"} = $feature_bundle{"5.23"};
55 $feature_bundle{"5.28"} = $feature_bundle{"5.27"};
56 $feature_bundle{"5.29"} = $feature_bundle{"5.27"};
57 $feature_bundle{"5.30"} = $feature_bundle{"5.27"};
58 $feature_bundle{"5.31"} = $feature_bundle{"5.27"};
59 $feature_bundle{"5.32"} = $feature_bundle{"5.27"};
60 $feature_bundle{"5.33"} = $feature_bundle{"5.27"};
61 $feature_bundle{"5.34"} = $feature_bundle{"5.27"};
62 $feature_bundle{"5.36"} = $feature_bundle{"5.35"};
63 $feature_bundle{"5.9.5"} = $feature_bundle{"5.10"};
73 our $hint_mask = 0x3c000000;
74 our @hint_bundles = qw( default 5.10 5.11 5.15 5.23 5.27 5.35 );
76 # This gets set (for now) in $^H as well as in %^H,
77 # for runtime speed of the uc/lc/ucfirst/lcfirst functions.
78 # See HINT_UNI_8_BIT in perl.h.
79 our $hint_uni8bit = 0x00000800;
82 # - think about versioned features (use feature switch => 2)
86 feature - Perl pragma to enable new features
90 use feature qw(fc say);
92 # Without the "use feature" above, this code would not be able to find
93 # the built-ins "say" or "fc":
94 say "The case-folded version of $x is: " . fc $x;
97 # set features to match the :5.10 bundle, which may turn off or on
98 # multiple features (see below)
102 # implicitly loads :5.10 feature bundle
107 It is usually impossible to add new syntax to Perl without breaking
108 some existing programs. This pragma provides a way to minimize that
109 risk. New syntactic constructs, or new semantic meanings to older
110 constructs, can be enabled by C<use feature 'foo'>, and will be parsed
111 only when the appropriate feature pragma is in scope. (Nevertheless, the
112 C<CORE::> prefix provides access to all Perl keywords, regardless of this
115 =head2 Lexical effect
117 Like other pragmas (C<use strict>, for example), features have a lexical
118 effect. C<use feature qw(foo)> will only make the feature "foo" available
119 from that point to the end of the enclosing block.
123 say "say is available here";
125 print "But not here.\n";
129 Features can also be turned off by using C<no feature "foo">. This too
133 say "say is available here";
136 print "But not here.\n";
138 say "Yet it is here.";
140 C<no feature> with no features specified will reset to the default group. To
141 disable I<all> features (an unusual request!) use C<no feature ':all'>.
143 =head1 AVAILABLE FEATURES
145 =head2 The 'say' feature
147 C<use feature 'say'> tells the compiler to enable the Raku-inspired
150 See L<perlfunc/say> for details.
152 This feature is available starting with Perl 5.10.
154 =head2 The 'state' feature
156 C<use feature 'state'> tells the compiler to enable C<state>
159 See L<perlsub/"Persistent Private Variables"> for details.
161 This feature is available starting with Perl 5.10.
163 =head2 The 'switch' feature
165 B<WARNING>: This feature is still experimental and the implementation may
166 change or be removed in future versions of Perl. For this reason, Perl will
167 warn when you use the feature, unless you have explicitly disabled the warning:
169 no warnings "experimental::smartmatch";
171 C<use feature 'switch'> tells the compiler to enable the Raku
172 given/when construct.
174 See L<perlsyn/"Switch Statements"> for details.
176 This feature is available starting with Perl 5.10.
178 =head2 The 'unicode_strings' feature
180 C<use feature 'unicode_strings'> tells the compiler to use Unicode rules
181 in all string operations executed within its scope (unless they are also
182 within the scope of either C<use locale> or C<use bytes>). The same applies
183 to all regular expressions compiled within the scope, even if executed outside
184 it. It does not change the internal representation of strings, but only how
185 they are interpreted.
187 C<no feature 'unicode_strings'> tells the compiler to use the traditional
188 Perl rules wherein the native character set rules is used unless it is
189 clear to Perl that Unicode is desired. This can lead to some surprises
190 when the behavior suddenly changes. (See
191 L<perlunicode/The "Unicode Bug"> for details.) For this reason, if you are
192 potentially using Unicode in your program, the
193 C<use feature 'unicode_strings'> subpragma is B<strongly> recommended.
195 This feature is available starting with Perl 5.12; was almost fully
196 implemented in Perl 5.14; and extended in Perl 5.16 to cover C<quotemeta>;
197 was extended further in Perl 5.26 to cover L<the range
198 operator|perlop/Range Operators>; and was extended again in Perl 5.28 to
199 cover L<special-cased whitespace splitting|perlfunc/split>.
201 =head2 The 'unicode_eval' and 'evalbytes' features
203 Together, these two features are intended to replace the legacy string
204 C<eval> function, which behaves problematically in some instances. They are
205 available starting with Perl 5.16, and are enabled by default by a
206 S<C<use 5.16>> or higher declaration.
208 C<unicode_eval> changes the behavior of plain string C<eval> to work more
209 consistently, especially in the Unicode world. Certain (mis)behaviors
210 couldn't be changed without breaking some things that had come to rely on
211 them, so the feature can be enabled and disabled. Details are at
212 L<perlfunc/Under the "unicode_eval" feature>.
214 C<evalbytes> is like string C<eval>, but it treats its argument as a byte
215 string. Details are at L<perlfunc/evalbytes EXPR>. Without a
216 S<C<use feature 'evalbytes'>> nor a S<C<use v5.16>> (or higher) declaration in
217 the current scope, you can still access it by instead writing
220 =head2 The 'current_sub' feature
222 This provides the C<__SUB__> token that returns a reference to the current
223 subroutine or C<undef> outside of a subroutine.
225 This feature is available starting with Perl 5.16.
227 =head2 The 'array_base' feature
229 This feature supported the legacy C<$[> variable. See L<perlvar/$[>.
230 It was on by default but disabled under C<use v5.16> (see
231 L</IMPLICIT LOADING>, below) and unavailable since perl 5.30.
233 This feature is available under this name starting with Perl 5.16. In
234 previous versions, it was simply on all the time, and this pragma knew
237 =head2 The 'fc' feature
239 C<use feature 'fc'> tells the compiler to enable the C<fc> function,
240 which implements Unicode casefolding.
242 See L<perlfunc/fc> for details.
244 This feature is available from Perl 5.16 onwards.
246 =head2 The 'lexical_subs' feature
248 In Perl versions prior to 5.26, this feature enabled
249 declaration of subroutines via C<my sub foo>, C<state sub foo>
250 and C<our sub foo> syntax. See L<perlsub/Lexical Subroutines> for details.
252 This feature is available from Perl 5.18 onwards. From Perl 5.18 to 5.24,
253 it was classed as experimental, and Perl emitted a warning for its
254 usage, except when explicitly disabled:
256 no warnings "experimental::lexical_subs";
258 As of Perl 5.26, use of this feature no longer triggers a warning, though
259 the C<experimental::lexical_subs> warning category still exists (for
260 compatibility with code that disables it). In addition, this syntax is
261 not only no longer experimental, but it is enabled for all Perl code,
262 regardless of what feature declarations are in scope.
264 =head2 The 'postderef' and 'postderef_qq' features
266 The 'postderef_qq' feature extends the applicability of L<postfix
267 dereference syntax|perlref/Postfix Dereference Syntax> so that postfix array
268 and scalar dereference are available in double-quotish interpolations. For
269 example, it makes the following two statements equivalent:
271 my $s = "[@{ $h->{a} }]";
272 my $s = "[$h->{a}->@*]";
274 This feature is available from Perl 5.20 onwards. In Perl 5.20 and 5.22, it
275 was classed as experimental, and Perl emitted a warning for its
276 usage, except when explicitly disabled:
278 no warnings "experimental::postderef";
280 As of Perl 5.24, use of this feature no longer triggers a warning, though
281 the C<experimental::postderef> warning category still exists (for
282 compatibility with code that disables it).
284 The 'postderef' feature was used in Perl 5.20 and Perl 5.22 to enable
285 postfix dereference syntax outside double-quotish interpolations. In those
286 versions, using it triggered the C<experimental::postderef> warning in the
287 same way as the 'postderef_qq' feature did. As of Perl 5.24, this syntax is
288 not only no longer experimental, but it is enabled for all Perl code,
289 regardless of what feature declarations are in scope.
291 =head2 The 'signatures' feature
293 B<WARNING>: This feature is still experimental and the implementation may
294 change or be removed in future versions of Perl. For this reason, Perl will
295 warn when you use the feature, unless you have explicitly disabled the warning:
297 no warnings "experimental::signatures";
299 This enables unpacking of subroutine arguments into lexical variables
302 sub foo ($left, $right) {
303 return $left + $right;
306 See L<perlsub/Signatures> for details.
308 This feature is available from Perl 5.20 onwards.
310 =head2 The 'refaliasing' feature
312 B<WARNING>: This feature is still experimental and the implementation may
313 change or be removed in future versions of Perl. For this reason, Perl will
314 warn when you use the feature, unless you have explicitly disabled the warning:
316 no warnings "experimental::refaliasing";
318 This enables aliasing via assignment to references:
320 \$a = \$b; # $a and $b now point to the same scalar
321 \@a = \@b; # to the same array
324 foreach \%hash (@array_of_hash_refs) {
328 See L<perlref/Assigning to References> for details.
330 This feature is available from Perl 5.22 onwards.
332 =head2 The 'bitwise' feature
334 This makes the four standard bitwise operators (C<& | ^ ~>) treat their
335 operands consistently as numbers, and introduces four new dotted operators
336 (C<&. |. ^. ~.>) that treat their operands consistently as strings. The
337 same applies to the assignment variants (C<&= |= ^= &.= |.= ^.=>).
339 See L<perlop/Bitwise String Operators> for details.
341 This feature is available from Perl 5.22 onwards. Starting in Perl 5.28,
342 C<use v5.28> will enable the feature. Before 5.28, it was still
343 experimental and would emit a warning in the "experimental::bitwise"
346 =head2 The 'declared_refs' feature
348 B<WARNING>: This feature is still experimental and the implementation may
349 change or be removed in future versions of Perl. For this reason, Perl will
350 warn when you use the feature, unless you have explicitly disabled the warning:
352 no warnings "experimental::declared_refs";
354 This allows a reference to a variable to be declared with C<my>, C<state>,
355 our C<our>, or localized with C<local>. It is intended mainly for use in
356 conjunction with the "refaliasing" feature. See L<perlref/Declaring a
357 Reference to a Variable> for examples.
359 This feature is available from Perl 5.26 onwards.
361 =head2 The 'isa' feature
363 B<WARNING>: This feature is still experimental and the implementation may
364 change or be removed in future versions of Perl. For this reason, Perl will
365 warn when you use the feature, unless you have explicitly disabled the warning:
367 no warnings "experimental::isa";
369 This allows the use of the C<isa> infix operator, which tests whether the
370 scalar given by the left operand is an object of the class given by the
371 right operand. See L<perlop/Class Instance Operator> for more details.
373 This feature is available from Perl 5.32 onwards.
375 =head2 The 'indirect' feature
377 This feature allows the use of L<indirect object
378 syntax|perlobj/Indirect Object Syntax> for method calls, e.g. C<new
379 Foo 1, 2;>. It is enabled by default, but can be turned off to
380 disallow indirect object syntax.
382 This feature is available under this name from Perl 5.32 onwards. In
383 previous versions, it was simply on all the time. To disallow (or
384 warn on) indirect object syntax on older Perls, see the L<indirect>
387 =head2 The 'multidimensional' feature
389 This feature enables multidimensional array emulation, a perl 4 (or
390 earlier) feature that was used to emulate multidimensional arrays with
391 hashes. This works by converting code like C<< $foo{$x, $y} >> into
392 C<< $foo{join($;, $x, $y)} >>. It is enabled by default, but can be
393 turned off to disable multidimensional array emulation.
395 When this feature is disabled the syntax that is normally replaced
396 will report a compilation error.
398 This feature is available under this name from Perl 5.34 onwards. In
399 previous versions, it was simply on all the time.
401 You can use the L<multidimensional> module on CPAN to disable
402 multidimensional array emulation for older versions of Perl.
404 =head2 The 'bareword_filehandles' feature.
406 This feature enables bareword filehandles for builtin functions
407 operations, a generally discouraged practice. It is enabled by
408 default, but can be turned off to disable bareword filehandles, except
409 for the exceptions listed below.
411 The perl built-in filehandles C<STDIN>, C<STDOUT>, C<STDERR>, C<DATA>,
412 C<ARGV>, C<ARGVOUT> and the special C<_> are always enabled.
414 This feature is enabled under this name from Perl 5.34 onwards. In
415 previous versions it was simply on all the time.
417 You can use the L<bareword::filehandles> module on CPAN to disable
418 bareword filehandles for older versions of perl.
420 =head2 The 'try' feature.
422 B<WARNING>: This feature is still experimental and the implementation may
423 change or be removed in future versions of Perl. For this reason, Perl will
424 warn when you use the feature, unless you have explicitly disabled the warning:
426 no warnings "experimental::try";
428 This feature enables the C<try> and C<catch> syntax, which allows exception
429 handling, where exceptions thrown from the body of the block introduced with
430 C<try> are caught by executing the body of the C<catch> block.
432 For more information, see L<perlsyn/"Try Catch Exception Handling">.
434 =head1 FEATURE BUNDLES
436 It's possible to load multiple features together, using
437 a I<feature bundle>. The name of a feature bundle is prefixed with
438 a colon, to distinguish it from an actual feature.
442 The following feature bundles are available:
444 bundle features included
445 --------- -----------------
446 :default indirect multidimensional
449 :5.10 bareword_filehandles indirect
450 multidimensional say state switch
452 :5.12 bareword_filehandles indirect
453 multidimensional say state switch
456 :5.14 bareword_filehandles indirect
457 multidimensional say state switch
460 :5.16 bareword_filehandles current_sub evalbytes
461 fc indirect multidimensional say state
462 switch unicode_eval unicode_strings
464 :5.18 bareword_filehandles current_sub evalbytes
465 fc indirect multidimensional say state
466 switch unicode_eval unicode_strings
468 :5.20 bareword_filehandles current_sub evalbytes
469 fc indirect multidimensional say state
470 switch unicode_eval unicode_strings
472 :5.22 bareword_filehandles current_sub evalbytes
473 fc indirect multidimensional say state
474 switch unicode_eval unicode_strings
476 :5.24 bareword_filehandles current_sub evalbytes
477 fc indirect multidimensional postderef_qq
478 say state switch unicode_eval
481 :5.26 bareword_filehandles current_sub evalbytes
482 fc indirect multidimensional postderef_qq
483 say state switch unicode_eval
486 :5.28 bareword_filehandles bitwise current_sub
487 evalbytes fc indirect multidimensional
488 postderef_qq say state switch unicode_eval
491 :5.30 bareword_filehandles bitwise current_sub
492 evalbytes fc indirect multidimensional
493 postderef_qq say state switch unicode_eval
496 :5.32 bareword_filehandles bitwise current_sub
497 evalbytes fc indirect multidimensional
498 postderef_qq say state switch unicode_eval
501 :5.34 bareword_filehandles bitwise current_sub
502 evalbytes fc indirect multidimensional
503 postderef_qq say state switch unicode_eval
506 :5.36 bareword_filehandles bitwise current_sub
507 evalbytes fc indirect multidimensional
508 postderef_qq say state unicode_eval
511 The C<:default> bundle represents the feature set that is enabled before
512 any C<use feature> or C<no feature> declaration.
514 Specifying sub-versions such as the C<0> in C<5.14.0> in feature bundles has
515 no effect. Feature bundles are guaranteed to be the same for all sub-versions.
517 use feature ":5.14.0"; # same as ":5.14"
518 use feature ":5.14.1"; # same as ":5.14"
520 =head1 IMPLICIT LOADING
522 Instead of loading feature bundles by name, it is easier to let Perl do
523 implicit loading of a feature bundle for you.
525 There are two ways to load the C<feature> pragma implicitly:
531 By using the C<-E> switch on the Perl command-line instead of C<-e>.
532 That will enable the feature bundle for that version of Perl in the
533 main compilation unit (that is, the one-liner that follows C<-E>).
537 By explicitly requiring a minimum Perl version number for your program, with
538 the C<use VERSION> construct. That is,
547 and so on. Note how the trailing sub-version
548 is automatically stripped from the
551 But to avoid portability warnings (see L<perlfunc/use>), you may prefer:
555 with the same effect.
557 If the required version is older than Perl 5.10, the ":default" feature
558 bundle is automatically loaded instead.
560 Unlike C<use feature ":5.12">, saying C<use v5.12> (or any higher version)
561 also does the equivalent of C<use strict>; see L<perlfunc/use> for details.
565 =head1 CHECKING FEATURES
567 C<feature> provides some simple APIs to check which features are enabled.
569 These functions cannot be imported and must be called by their fully
570 qualified names. If you don't otherwise need to set a feature you will
571 need to ensure C<feature> is loaded with:
577 =item feature_enabled($feature)
579 =item feature_enabled($feature, $depth)
581 package MyStandardEnforcer;
585 croak "disable indirect!" if feature::feature_enabled("indirect");
588 Test whether a named feature is enabled at a given level in the call
589 stack, returning a true value if it is. C<$depth> defaults to 1,
590 which checks the scope that called the scope calling
591 feature::feature_enabled().
593 croaks for an unknown feature name.
595 =item features_enabled()
597 =item features_enabled($depth)
599 package ReportEnabledFeatures;
602 say STDERR join " ", feature::features_enabled();
605 Returns a list of the features enabled at a given level in the call
606 stack. C<$depth> defaults to 1, which checks the scope that called
607 the scope calling feature::features_enabled().
609 =item feature_bundle()
611 =item feature_bundle($depth)
613 Returns the feature bundle, if any, selected at a given level in the
614 call stack. C<$depth> defaults to 1, which checks the scope that called
615 the scope calling feature::feature_bundle().
617 Returns an undefined value if no feature bundle is selected in the
620 The bundle name returned will be for the earliest bundle matching the
625 BEGIN { print feature::feature_bundle(0); }
629 This returns internal state, at this point C<use v5.12;> sets the
630 feature bundle, but C< use feature ":5.12"; > does not set the feature
631 bundle. This may change in a future release of perl.
641 croak("No features specified");
650 # A bare C<no feature> should reset to the default bundle
652 $^H &= ~($hint_uni8bit|$hint_mask);
662 my $bundle_number = $^H & $hint_mask;
663 my $features = $bundle_number != $hint_mask
664 && $feature_bundle{$hint_bundles[$bundle_number >> $hint_shift]};
666 # Features are enabled implicitly via bundle hints.
667 # Delete any keys that may be left over from last time.
668 delete @^H{ values(%feature) };
671 $^H{$feature{$_}} = 1;
672 $^H |= $hint_uni8bit if $_ eq 'unicode_strings';
677 if (substr($name, 0, 1) eq ":") {
678 my $v = substr($name, 1);
679 if (!exists $feature_bundle{$v}) {
680 $v =~ s/^([0-9]+)\.([0-9]+).[0-9]+$/$1.$2/;
681 if (!exists $feature_bundle{$v}) {
682 unknown_feature_bundle(substr($name, 1));
685 unshift @_, @{$feature_bundle{$v}};
688 if (!exists $feature{$name}) {
689 if (exists $noops{$name}) {
692 if (!$import && exists $removed{$name}) {
695 unknown_feature($name);
698 $^H{$feature{$name}} = 1;
699 $^H |= $hint_uni8bit if $name eq 'unicode_strings';
701 delete $^H{$feature{$name}};
702 $^H &= ~ $hint_uni8bit if $name eq 'unicode_strings';
707 sub unknown_feature {
709 croak(sprintf('Feature "%s" is not supported by Perl %vd',
713 sub unknown_feature_bundle {
715 croak(sprintf('Feature bundle "%s" is not supported by Perl %vd',
724 sub features_enabled {
728 my @frame = caller($depth+1)
730 my ($hints, $hinthash) = @frame[8, 10];
732 my $bundle_number = $hints & $hint_mask;
733 if ($bundle_number != $hint_mask) {
734 return $feature_bundle{$hint_bundles[$bundle_number >> $hint_shift]}->@*;
738 for my $feature (sort keys %feature) {
739 if ($hinthash->{$feature{$feature}}) {
740 push @features, $feature;
747 sub feature_enabled {
748 my ($feature, $depth) = @_;
751 my @frame = caller($depth+1)
753 my ($hints, $hinthash) = @frame[8, 10];
755 my $hint_feature = $feature{$feature}
756 or croak "Unknown feature $feature";
757 my $bundle_number = $hints & $hint_mask;
758 if ($bundle_number != $hint_mask) {
759 my $bundle = $hint_bundles[$bundle_number >> $hint_shift];
760 for my $bundle_feature ($feature_bundle{$bundle}->@*) {
761 return 1 if $bundle_feature eq $feature;
766 return $hinthash->{$hint_feature} // 0;
774 my @frame = caller($depth+1)
776 my $bundle_number = $frame[8] & $hint_mask;
777 if ($bundle_number != $hint_mask) {
778 return $hint_bundles[$bundle_number >> $hint_shift];