1# -*- mode: Perl; buffer-read-only: t -*- 2# !!!!!!! DO NOT EDIT THIS FILE !!!!!!! 3# This file is built by regen/feature.pl. 4# Any changes made here will be lost! 5 6package feature; 7our $VERSION = '1.89'; 8 9our %feature = ( 10 fc => 'feature_fc', 11 isa => 'feature_isa', 12 say => 'feature_say', 13 try => 'feature_try', 14 class => 'feature_class', 15 defer => 'feature_defer', 16 state => 'feature_state', 17 switch => 'feature_switch', 18 bitwise => 'feature_bitwise', 19 indirect => 'feature_indirect', 20 evalbytes => 'feature_evalbytes', 21 signatures => 'feature_signatures', 22 current_sub => 'feature___SUB__', 23 module_true => 'feature_module_true', 24 refaliasing => 'feature_refaliasing', 25 postderef_qq => 'feature_postderef_qq', 26 unicode_eval => 'feature_unieval', 27 declared_refs => 'feature_myref', 28 unicode_strings => 'feature_unicode', 29 multidimensional => 'feature_multidimensional', 30 bareword_filehandles => 'feature_bareword_filehandles', 31 extra_paired_delimiters => 'feature_more_delims', 32); 33 34our %feature_bundle = ( 35 "5.10" => [qw(bareword_filehandles indirect multidimensional say state switch)], 36 "5.11" => [qw(bareword_filehandles indirect multidimensional say state switch unicode_strings)], 37 "5.15" => [qw(bareword_filehandles current_sub evalbytes fc indirect multidimensional say state switch unicode_eval unicode_strings)], 38 "5.23" => [qw(bareword_filehandles current_sub evalbytes fc indirect multidimensional postderef_qq say state switch unicode_eval unicode_strings)], 39 "5.27" => [qw(bareword_filehandles bitwise current_sub evalbytes fc indirect multidimensional postderef_qq say state switch unicode_eval unicode_strings)], 40 "5.35" => [qw(bareword_filehandles bitwise current_sub evalbytes fc isa postderef_qq say signatures state unicode_eval unicode_strings)], 41 "5.37" => [qw(bitwise current_sub evalbytes fc isa module_true postderef_qq say signatures state unicode_eval unicode_strings)], 42 "5.39" => [qw(bitwise current_sub evalbytes fc isa module_true postderef_qq say signatures state try unicode_eval unicode_strings)], 43 "all" => [qw(bareword_filehandles bitwise class current_sub declared_refs defer evalbytes extra_paired_delimiters fc indirect isa module_true multidimensional postderef_qq refaliasing say signatures state switch try unicode_eval unicode_strings)], 44 "default" => [qw(bareword_filehandles indirect multidimensional)], 45); 46 47$feature_bundle{"5.12"} = $feature_bundle{"5.11"}; 48$feature_bundle{"5.13"} = $feature_bundle{"5.11"}; 49$feature_bundle{"5.14"} = $feature_bundle{"5.11"}; 50$feature_bundle{"5.16"} = $feature_bundle{"5.15"}; 51$feature_bundle{"5.17"} = $feature_bundle{"5.15"}; 52$feature_bundle{"5.18"} = $feature_bundle{"5.15"}; 53$feature_bundle{"5.19"} = $feature_bundle{"5.15"}; 54$feature_bundle{"5.20"} = $feature_bundle{"5.15"}; 55$feature_bundle{"5.21"} = $feature_bundle{"5.15"}; 56$feature_bundle{"5.22"} = $feature_bundle{"5.15"}; 57$feature_bundle{"5.24"} = $feature_bundle{"5.23"}; 58$feature_bundle{"5.25"} = $feature_bundle{"5.23"}; 59$feature_bundle{"5.26"} = $feature_bundle{"5.23"}; 60$feature_bundle{"5.28"} = $feature_bundle{"5.27"}; 61$feature_bundle{"5.29"} = $feature_bundle{"5.27"}; 62$feature_bundle{"5.30"} = $feature_bundle{"5.27"}; 63$feature_bundle{"5.31"} = $feature_bundle{"5.27"}; 64$feature_bundle{"5.32"} = $feature_bundle{"5.27"}; 65$feature_bundle{"5.33"} = $feature_bundle{"5.27"}; 66$feature_bundle{"5.34"} = $feature_bundle{"5.27"}; 67$feature_bundle{"5.36"} = $feature_bundle{"5.35"}; 68$feature_bundle{"5.38"} = $feature_bundle{"5.37"}; 69$feature_bundle{"5.40"} = $feature_bundle{"5.39"}; 70$feature_bundle{"5.9.5"} = $feature_bundle{"5.10"}; 71my %noops = ( 72 postderef => 1, 73 lexical_subs => 1, 74); 75my %removed = ( 76 array_base => 1, 77); 78 79our $hint_shift = 26; 80our $hint_mask = 0x3c000000; 81our @hint_bundles = qw( default 5.10 5.11 5.15 5.23 5.27 5.35 5.37 5.39 ); 82 83# This gets set (for now) in $^H as well as in %^H, 84# for runtime speed of the uc/lc/ucfirst/lcfirst functions. 85# See HINT_UNI_8_BIT in perl.h. 86our $hint_uni8bit = 0x00000800; 87 88# TODO: 89# - think about versioned features (use feature switch => 2) 90 91=encoding utf8 92 93=head1 NAME 94 95feature - Perl pragma to enable new features 96 97=head1 SYNOPSIS 98 99 use feature qw(fc say); 100 101 # Without the "use feature" above, this code would not be able to find 102 # the built-ins "say" or "fc": 103 say "The case-folded version of $x is: " . fc $x; 104 105 106 # set features to match the :5.36 bundle, which may turn off or on 107 # multiple features (see "FEATURE BUNDLES" below) 108 use feature ':5.36'; 109 110 111 # implicitly loads :5.36 feature bundle 112 use v5.36; 113 114=head1 DESCRIPTION 115 116It is usually impossible to add new syntax to Perl without breaking 117some existing programs. This pragma provides a way to minimize that 118risk. New syntactic constructs, or new semantic meanings to older 119constructs, can be enabled by C<use feature 'foo'>, and will be parsed 120only when the appropriate feature pragma is in scope. (Nevertheless, the 121C<CORE::> prefix provides access to all Perl keywords, regardless of this 122pragma.) 123 124=head2 Lexical effect 125 126Like other pragmas (C<use strict>, for example), features have a lexical 127effect. C<use feature qw(foo)> will only make the feature "foo" available 128from that point to the end of the enclosing block. 129 130 { 131 use feature 'say'; 132 say "say is available here"; 133 } 134 print "But not here.\n"; 135 136=head2 C<no feature> 137 138Features can also be turned off by using C<no feature "foo">. This too 139has lexical effect. 140 141 use feature 'say'; 142 say "say is available here"; 143 { 144 no feature 'say'; 145 print "But not here.\n"; 146 } 147 say "Yet it is here."; 148 149C<no feature> with no features specified will reset to the default group. To 150disable I<all> features (an unusual request!) use C<no feature ':all'>. 151 152=head1 AVAILABLE FEATURES 153 154Read L</"FEATURE BUNDLES"> for the feature cheat sheet summary. 155 156=head2 The 'say' feature 157 158C<use feature 'say'> tells the compiler to enable the Raku-inspired 159C<say> function. 160 161See L<perlfunc/say> for details. 162 163This feature is available starting with Perl 5.10. 164 165=head2 The 'state' feature 166 167C<use feature 'state'> tells the compiler to enable C<state> 168variables. 169 170See L<perlsub/"Persistent Private Variables"> for details. 171 172This feature is available starting with Perl 5.10. 173 174=head2 The 'switch' feature 175 176B<WARNING>: This feature is still experimental and the implementation may 177change or be removed in future versions of Perl. For this reason, Perl will 178warn when you use the feature, unless you have explicitly disabled the warning: 179 180 no warnings "experimental::smartmatch"; 181 182C<use feature 'switch'> tells the compiler to enable the Raku 183given/when construct. 184 185See L<perlsyn/"Switch Statements"> for details. 186 187This feature is available starting with Perl 5.10. 188It is deprecated starting with Perl 5.38, and using 189C<given>, C<when> or smartmatch will throw a warning. 190It will be removed in Perl 5.42. 191 192=head2 The 'unicode_strings' feature 193 194C<use feature 'unicode_strings'> tells the compiler to use Unicode rules 195in all string operations executed within its scope (unless they are also 196within the scope of either C<use locale> or C<use bytes>). The same applies 197to all regular expressions compiled within the scope, even if executed outside 198it. It does not change the internal representation of strings, but only how 199they are interpreted. 200 201C<no feature 'unicode_strings'> tells the compiler to use the traditional 202Perl rules wherein the native character set rules is used unless it is 203clear to Perl that Unicode is desired. This can lead to some surprises 204when the behavior suddenly changes. (See 205L<perlunicode/The "Unicode Bug"> for details.) For this reason, if you are 206potentially using Unicode in your program, the 207C<use feature 'unicode_strings'> subpragma is B<strongly> recommended. 208 209This feature is available starting with Perl 5.12; was almost fully 210implemented in Perl 5.14; and extended in Perl 5.16 to cover C<quotemeta>; 211was extended further in Perl 5.26 to cover L<the range 212operator|perlop/Range Operators>; and was extended again in Perl 5.28 to 213cover L<special-cased whitespace splitting|perlfunc/split>. 214 215=head2 The 'unicode_eval' and 'evalbytes' features 216 217Together, these two features are intended to replace the legacy string 218C<eval> function, which behaves problematically in some instances. They are 219available starting with Perl 5.16, and are enabled by default by a 220S<C<use 5.16>> or higher declaration. 221 222C<unicode_eval> changes the behavior of plain string C<eval> to work more 223consistently, especially in the Unicode world. Certain (mis)behaviors 224couldn't be changed without breaking some things that had come to rely on 225them, so the feature can be enabled and disabled. Details are at 226L<perlfunc/Under the "unicode_eval" feature>. 227 228C<evalbytes> is like string C<eval>, but it treats its argument as a byte 229string. Details are at L<perlfunc/evalbytes EXPR>. Without a 230S<C<use feature 'evalbytes'>> nor a S<C<use v5.16>> (or higher) declaration in 231the current scope, you can still access it by instead writing 232C<CORE::evalbytes>. 233 234=head2 The 'current_sub' feature 235 236This provides the C<__SUB__> token that returns a reference to the current 237subroutine or C<undef> outside of a subroutine. 238 239This feature is available starting with Perl 5.16. 240 241=head2 The 'array_base' feature 242 243This feature supported the legacy C<$[> variable. See L<perlvar/$[>. 244It was on by default but disabled under C<use v5.16> (see 245L</IMPLICIT LOADING>, below) and unavailable since perl 5.30. 246 247This feature is available under this name starting with Perl 5.16. In 248previous versions, it was simply on all the time, and this pragma knew 249nothing about it. 250 251=head2 The 'fc' feature 252 253C<use feature 'fc'> tells the compiler to enable the C<fc> function, 254which implements Unicode casefolding. 255 256See L<perlfunc/fc> for details. 257 258This feature is available from Perl 5.16 onwards. 259 260=head2 The 'lexical_subs' feature 261 262In Perl versions prior to 5.26, this feature enabled 263declaration of subroutines via C<my sub foo>, C<state sub foo> 264and C<our sub foo> syntax. See L<perlsub/Lexical Subroutines> for details. 265 266This feature is available from Perl 5.18 onwards. From Perl 5.18 to 5.24, 267it was classed as experimental, and Perl emitted a warning for its 268usage, except when explicitly disabled: 269 270 no warnings "experimental::lexical_subs"; 271 272As of Perl 5.26, use of this feature no longer triggers a warning, though 273the C<experimental::lexical_subs> warning category still exists (for 274compatibility with code that disables it). In addition, this syntax is 275not only no longer experimental, but it is enabled for all Perl code, 276regardless of what feature declarations are in scope. 277 278=head2 The 'postderef' and 'postderef_qq' features 279 280The 'postderef_qq' feature extends the applicability of L<postfix 281dereference syntax|perlref/Postfix Dereference Syntax> so that 282postfix array dereference, postfix scalar dereference, and 283postfix array highest index access are available in double-quotish interpolations. 284For example, it makes the following two statements equivalent: 285 286 my $s = "[@{ $h->{a} }]"; 287 my $s = "[$h->{a}->@*]"; 288 289This feature is available from Perl 5.20 onwards. In Perl 5.20 and 5.22, it 290was classed as experimental, and Perl emitted a warning for its 291usage, except when explicitly disabled: 292 293 no warnings "experimental::postderef"; 294 295As of Perl 5.24, use of this feature no longer triggers a warning, though 296the C<experimental::postderef> warning category still exists (for 297compatibility with code that disables it). 298 299The 'postderef' feature was used in Perl 5.20 and Perl 5.22 to enable 300postfix dereference syntax outside double-quotish interpolations. In those 301versions, using it triggered the C<experimental::postderef> warning in the 302same way as the 'postderef_qq' feature did. As of Perl 5.24, this syntax is 303not only no longer experimental, but it is enabled for all Perl code, 304regardless of what feature declarations are in scope. 305 306=head2 The 'signatures' feature 307 308This enables syntax for declaring subroutine arguments as lexical variables. 309For example, for this subroutine: 310 311 sub foo ($left, $right) { 312 return $left + $right; 313 } 314 315Calling C<foo(3, 7)> will assign C<3> into C<$left> and C<7> into C<$right>. 316 317See L<perlsub/Signatures> for details. 318 319This feature is available from Perl 5.20 onwards. From Perl 5.20 to 5.34, 320it was classed as experimental, and Perl emitted a warning for its usage, 321except when explicitly disabled: 322 323 no warnings "experimental::signatures"; 324 325As of Perl 5.36, use of this feature no longer triggers a warning, though the 326C<experimental::signatures> warning category still exists (for compatibility 327with code that disables it). This feature is now considered stable, and is 328enabled automatically by C<use v5.36> (or higher). 329 330=head2 The 'refaliasing' feature 331 332B<WARNING>: This feature is still experimental and the implementation may 333change or be removed in future versions of Perl. For this reason, Perl will 334warn when you use the feature, unless you have explicitly disabled the warning: 335 336 no warnings "experimental::refaliasing"; 337 338This enables aliasing via assignment to references: 339 340 \$a = \$b; # $a and $b now point to the same scalar 341 \@a = \@b; # to the same array 342 \%a = \%b; 343 \&a = \&b; 344 foreach \%hash (@array_of_hash_refs) { 345 ... 346 } 347 348See L<perlref/Assigning to References> for details. 349 350This feature is available from Perl 5.22 onwards. 351 352=head2 The 'bitwise' feature 353 354This makes the four standard bitwise operators (C<& | ^ ~>) treat their 355operands consistently as numbers, and introduces four new dotted operators 356(C<&. |. ^. ~.>) that treat their operands consistently as strings. The 357same applies to the assignment variants (C<&= |= ^= &.= |.= ^.=>). 358 359See L<perlop/Bitwise String Operators> for details. 360 361This feature is available from Perl 5.22 onwards. Starting in Perl 5.28, 362C<use v5.28> will enable the feature. Before 5.28, it was still 363experimental and would emit a warning in the "experimental::bitwise" 364category. 365 366=head2 The 'declared_refs' feature 367 368B<WARNING>: This feature is still experimental and the implementation may 369change or be removed in future versions of Perl. For this reason, Perl will 370warn when you use the feature, unless you have explicitly disabled the warning: 371 372 no warnings "experimental::declared_refs"; 373 374This allows a reference to a variable to be declared with C<my>, C<state>, 375or C<our>, or localized with C<local>. It is intended mainly for use in 376conjunction with the "refaliasing" feature. See L<perlref/Declaring a 377Reference to a Variable> for examples. 378 379This feature is available from Perl 5.26 onwards. 380 381=head2 The 'isa' feature 382 383This allows the use of the C<isa> infix operator, which tests whether the 384scalar given by the left operand is an object of the class given by the 385right operand. See L<perlop/Class Instance Operator> for more details. 386 387This feature is available from Perl 5.32 onwards. From Perl 5.32 to 5.34, 388it was classed as experimental, and Perl emitted a warning for its usage, 389except when explicitly disabled: 390 391 no warnings "experimental::isa"; 392 393As of Perl 5.36, use of this feature no longer triggers a warning (though the 394C<experimental::isa> warning category still exists for compatibility with 395code that disables it). This feature is now considered stable, and is enabled 396automatically by C<use v5.36> (or higher). 397 398=head2 The 'indirect' feature 399 400This feature allows the use of L<indirect object 401syntax|perlobj/Indirect Object Syntax> for method calls, e.g. C<new 402Foo 1, 2;>. It is enabled by default, but can be turned off to 403disallow indirect object syntax. 404 405This feature is available under this name from Perl 5.32 onwards. In 406previous versions, it was simply on all the time. To disallow (or 407warn on) indirect object syntax on older Perls, see the L<indirect> 408CPAN module. 409 410=head2 The 'multidimensional' feature 411 412This feature enables multidimensional array emulation, a perl 4 (or 413earlier) feature that was used to emulate multidimensional arrays with 414hashes. This works by converting code like C<< $foo{$x, $y} >> into 415C<< $foo{join($;, $x, $y)} >>. It is enabled by default, but can be 416turned off to disable multidimensional array emulation. 417 418When this feature is disabled the syntax that is normally replaced 419will report a compilation error. 420 421This feature is available under this name from Perl 5.34 onwards. In 422previous versions, it was simply on all the time. 423 424You can use the L<multidimensional> module on CPAN to disable 425multidimensional array emulation for older versions of Perl. 426 427=head2 The 'bareword_filehandles' feature 428 429This feature enables bareword filehandles for builtin functions 430operations, a generally discouraged practice. It is enabled by 431default, but can be turned off to disable bareword filehandles, except 432for the exceptions listed below. 433 434The perl built-in filehandles C<STDIN>, C<STDOUT>, C<STDERR>, C<DATA>, 435C<ARGV>, C<ARGVOUT> and the special C<_> are always enabled. 436 437This feature is available under this name from Perl 5.34 onwards. In 438previous versions it was simply on all the time. 439 440You can use the L<bareword::filehandles> module on CPAN to disable 441bareword filehandles for older versions of perl. 442 443=head2 The 'try' feature 444 445B<WARNING>: This feature is still partly experimental, and the implementation 446may change or be removed in future versions of Perl. 447 448This feature enables the C<try> and C<catch> syntax, which allows exception 449handling, where exceptions thrown from the body of the block introduced with 450C<try> are caught by executing the body of the C<catch> block. 451 452This feature is available starting in Perl 5.34. Before Perl 5.40 it was 453classed as experimental, and Perl emitted a warning for its usage, except when 454explicitly disabled: 455 456 no warnings "experimental::try"; 457 458As of Perl 5.40, use of this feature without a C<finally> block no longer 459triggers a warning. The optional C<finally> block is still considered 460experimental and emits a warning, except when explicitly disabled as above. 461 462For more information, see L<perlsyn/"Try Catch Exception Handling">. 463 464=head2 The 'defer' feature 465 466B<WARNING>: This feature is still experimental and the implementation may 467change or be removed in future versions of Perl. For this reason, Perl will 468warn when you use the feature, unless you have explicitly disabled the warning: 469 470 no warnings "experimental::defer"; 471 472This feature enables the C<defer> block syntax, which allows a block of code 473to be deferred until when the flow of control leaves the block which contained 474it. For more details, see L<perlsyn/defer>. 475 476This feature is available starting in Perl 5.36. 477 478=head2 The 'extra_paired_delimiters' feature 479 480B<WARNING>: This feature is still experimental and the implementation may 481change or be removed in future versions of Perl. For this reason, Perl will 482warn when you use the feature, unless you have explicitly disabled the warning: 483 484 no warnings "experimental::extra_paired_delimiters"; 485 486This feature enables the use of more paired string delimiters than the 487traditional four, S<C<< < > >>>, S<C<( )>>, S<C<{ }>>, and S<C<[ ]>>. When 488this feature is on, for example, you can say S<C<qrE<171>patE<187>>>. 489 490As with any usage of non-ASCII delimiters in a UTF-8-encoded source file, you 491will want to ensure the parser will decode the source code from UTF-8 bytes 492with a declaration such as C<use utf8>. 493 494This feature is available starting in Perl 5.36. 495 496For a full list of the available characters, see 497L<perlop/List of Extra Paired Delimiters>. 498 499=head2 The 'module_true' feature 500 501This feature removes the need to return a true value at the end of a module 502loaded with C<require> or C<use>. Any errors during compilation will cause 503failures, but reaching the end of the module when this feature is in effect 504will prevent C<perl> from throwing an exception that the module "did not return 505a true value". 506 507=head2 The 'class' feature 508 509B<WARNING>: This feature is still experimental and the implementation may 510change or be removed in future versions of Perl. For this reason, Perl will 511warn when you use the feature, unless you have explicitly disabled the warning: 512 513 no warnings "experimental::class"; 514 515This feature enables the C<class> block syntax and other associated keywords 516which implement the "new" object system, previously codenamed "Corinna". 517 518=head1 FEATURE BUNDLES 519 520It's possible to load multiple features together, using 521a I<feature bundle>. The name of a feature bundle is prefixed with 522a colon, to distinguish it from an actual feature. 523 524 use feature ":5.10"; 525 526The following feature bundles are available: 527 528 bundle features included 529 --------- ----------------- 530 :default indirect multidimensional 531 bareword_filehandles 532 533 :5.10 bareword_filehandles indirect 534 multidimensional say state switch 535 536 :5.12 bareword_filehandles indirect 537 multidimensional say state switch 538 unicode_strings 539 540 :5.14 bareword_filehandles indirect 541 multidimensional say state switch 542 unicode_strings 543 544 :5.16 bareword_filehandles current_sub evalbytes 545 fc indirect multidimensional say state 546 switch unicode_eval unicode_strings 547 548 :5.18 bareword_filehandles current_sub evalbytes 549 fc indirect multidimensional say state 550 switch unicode_eval unicode_strings 551 552 :5.20 bareword_filehandles current_sub evalbytes 553 fc indirect multidimensional say state 554 switch unicode_eval unicode_strings 555 556 :5.22 bareword_filehandles current_sub evalbytes 557 fc indirect multidimensional say state 558 switch unicode_eval unicode_strings 559 560 :5.24 bareword_filehandles current_sub evalbytes 561 fc indirect multidimensional postderef_qq 562 say state switch unicode_eval 563 unicode_strings 564 565 :5.26 bareword_filehandles current_sub evalbytes 566 fc indirect multidimensional postderef_qq 567 say state switch unicode_eval 568 unicode_strings 569 570 :5.28 bareword_filehandles bitwise current_sub 571 evalbytes fc indirect multidimensional 572 postderef_qq say state switch unicode_eval 573 unicode_strings 574 575 :5.30 bareword_filehandles bitwise current_sub 576 evalbytes fc indirect multidimensional 577 postderef_qq say state switch unicode_eval 578 unicode_strings 579 580 :5.32 bareword_filehandles bitwise current_sub 581 evalbytes fc indirect multidimensional 582 postderef_qq say state switch unicode_eval 583 unicode_strings 584 585 :5.34 bareword_filehandles bitwise current_sub 586 evalbytes fc indirect multidimensional 587 postderef_qq say state switch unicode_eval 588 unicode_strings 589 590 :5.36 bareword_filehandles bitwise current_sub 591 evalbytes fc isa postderef_qq say signatures 592 state unicode_eval unicode_strings 593 594 :5.38 bitwise current_sub evalbytes fc isa 595 module_true postderef_qq say signatures 596 state unicode_eval unicode_strings 597 598 :5.40 bitwise current_sub evalbytes fc isa 599 module_true postderef_qq say signatures 600 state try unicode_eval unicode_strings 601 602The C<:default> bundle represents the feature set that is enabled before 603any C<use feature> or C<no feature> declaration. 604 605Specifying sub-versions such as the C<0> in C<5.14.0> in feature bundles has 606no effect. Feature bundles are guaranteed to be the same for all sub-versions. 607 608 use feature ":5.14.0"; # same as ":5.14" 609 use feature ":5.14.1"; # same as ":5.14" 610 611You can also do: 612 613 use feature ":all"; 614 615or 616 617 no feature ":all"; 618 619but the first may enable features in a later version of Perl that 620change the meaning of your code, and the second may disable mechanisms 621that are part of Perl's current behavior that have been turned into 622features, just as C<indirect> and C<bareword_filehandles> were. 623 624=head1 IMPLICIT LOADING 625 626Instead of loading feature bundles by name, it is easier to let Perl do 627implicit loading of a feature bundle for you. 628 629There are two ways to load the C<feature> pragma implicitly: 630 631=over 4 632 633=item * 634 635By using the C<-E> switch on the Perl command-line instead of C<-e>. 636That will enable the feature bundle for that version of Perl in the 637main compilation unit (that is, the one-liner that follows C<-E>). 638 639=item * 640 641By explicitly requiring a minimum Perl version number for your program, with 642the C<use VERSION> construct. That is, 643 644 use v5.36.0; 645 646will do an implicit 647 648 no feature ':all'; 649 use feature ':5.36'; 650 651and so on. Note how the trailing sub-version 652is automatically stripped from the 653version. 654 655But to avoid portability warnings (see L<perlfunc/use>), you may prefer: 656 657 use 5.036; 658 659with the same effect. 660 661If the required version is older than Perl 5.10, the ":default" feature 662bundle is automatically loaded instead. 663 664Unlike C<use feature ":5.12">, saying C<use v5.12> (or any higher version) 665also does the equivalent of C<use strict>; see L<perlfunc/use> for details. 666 667=back 668 669=head1 CHECKING FEATURES 670 671C<feature> provides some simple APIs to check which features are enabled. 672 673These functions cannot be imported and must be called by their fully 674qualified names. If you don't otherwise need to set a feature you will 675need to ensure C<feature> is loaded with: 676 677 use feature (); 678 679=over 680 681=item feature_enabled($feature) 682 683=item feature_enabled($feature, $depth) 684 685 package MyStandardEnforcer; 686 use feature (); 687 use Carp "croak"; 688 sub import { 689 croak "disable indirect!" if feature::feature_enabled("indirect"); 690 } 691 692Test whether a named feature is enabled at a given level in the call 693stack, returning a true value if it is. C<$depth> defaults to 1, 694which checks the scope that called the scope calling 695feature::feature_enabled(). 696 697croaks for an unknown feature name. 698 699=item features_enabled() 700 701=item features_enabled($depth) 702 703 package ReportEnabledFeatures; 704 use feature "say"; 705 sub import { 706 say STDERR join " ", feature::features_enabled(); 707 } 708 709Returns a list of the features enabled at a given level in the call 710stack. C<$depth> defaults to 1, which checks the scope that called 711the scope calling feature::features_enabled(). 712 713=item feature_bundle() 714 715=item feature_bundle($depth) 716 717Returns the feature bundle, if any, selected at a given level in the 718call stack. C<$depth> defaults to 1, which checks the scope that called 719the scope calling feature::feature_bundle(). 720 721Returns an undefined value if no feature bundle is selected in the 722scope. 723 724The bundle name returned will be for the earliest bundle matching the 725selected bundle, so: 726 727 use feature (); 728 use v5.12; 729 BEGIN { print feature::feature_bundle(0); } 730 731will print C<5.11>. 732 733This returns internal state, at this point C<use v5.12;> sets the 734feature bundle, but C< use feature ":5.12"; > does not set the feature 735bundle. This may change in a future release of perl. 736 737=back 738 739=cut 740 741sub import { 742 shift; 743 744 if (!@_) { 745 croak("No features specified"); 746 } 747 748 __common(1, @_); 749} 750 751sub unimport { 752 shift; 753 754 # A bare C<no feature> should reset to the default bundle 755 if (!@_) { 756 $^H &= ~($hint_uni8bit|$hint_mask); 757 return; 758 } 759 760 __common(0, @_); 761} 762 763 764sub __common { 765 my $import = shift; 766 my $bundle_number = $^H & $hint_mask; 767 my $features = $bundle_number != $hint_mask 768 && $feature_bundle{$hint_bundles[$bundle_number >> $hint_shift]}; 769 if ($features) { 770 # Features are enabled implicitly via bundle hints. 771 # Delete any keys that may be left over from last time. 772 delete @^H{ values(%feature) }; 773 $^H |= $hint_mask; 774 for (@$features) { 775 $^H{$feature{$_}} = 1; 776 $^H |= $hint_uni8bit if $_ eq 'unicode_strings'; 777 } 778 } 779 while (@_) { 780 my $name = shift; 781 if (substr($name, 0, 1) eq ":") { 782 my $v = substr($name, 1); 783 if (!exists $feature_bundle{$v}) { 784 $v =~ s/^([0-9]+)\.([0-9]+).[0-9]+$/$1.$2/; 785 if (!exists $feature_bundle{$v}) { 786 unknown_feature_bundle(substr($name, 1)); 787 } 788 } 789 unshift @_, @{$feature_bundle{$v}}; 790 next; 791 } 792 if (!exists $feature{$name}) { 793 if (exists $noops{$name}) { 794 next; 795 } 796 if (!$import && exists $removed{$name}) { 797 next; 798 } 799 unknown_feature($name); 800 } 801 if ($import) { 802 $^H{$feature{$name}} = 1; 803 $^H |= $hint_uni8bit if $name eq 'unicode_strings'; 804 } else { 805 delete $^H{$feature{$name}}; 806 $^H &= ~ $hint_uni8bit if $name eq 'unicode_strings'; 807 } 808 } 809} 810 811sub unknown_feature { 812 my $feature = shift; 813 croak(sprintf('Feature "%s" is not supported by Perl %vd', 814 $feature, $^V)); 815} 816 817sub unknown_feature_bundle { 818 my $feature = shift; 819 croak(sprintf('Feature bundle "%s" is not supported by Perl %vd', 820 $feature, $^V)); 821} 822 823sub croak { 824 require Carp; 825 Carp::croak(@_); 826} 827 828sub features_enabled { 829 my ($depth) = @_; 830 831 $depth //= 1; 832 my @frame = caller($depth+1) 833 or return; 834 my ($hints, $hinthash) = @frame[8, 10]; 835 836 my $bundle_number = $hints & $hint_mask; 837 if ($bundle_number != $hint_mask) { 838 return $feature_bundle{$hint_bundles[$bundle_number >> $hint_shift]}->@*; 839 } 840 else { 841 my @features; 842 for my $feature (sort keys %feature) { 843 if ($hinthash->{$feature{$feature}}) { 844 push @features, $feature; 845 } 846 } 847 return @features; 848 } 849} 850 851sub feature_enabled { 852 my ($feature, $depth) = @_; 853 854 $depth //= 1; 855 my @frame = caller($depth+1) 856 or return; 857 my ($hints, $hinthash) = @frame[8, 10]; 858 859 my $hint_feature = $feature{$feature} 860 or croak "Unknown feature $feature"; 861 my $bundle_number = $hints & $hint_mask; 862 if ($bundle_number != $hint_mask) { 863 my $bundle = $hint_bundles[$bundle_number >> $hint_shift]; 864 for my $bundle_feature ($feature_bundle{$bundle}->@*) { 865 return 1 if $bundle_feature eq $feature; 866 } 867 return 0; 868 } 869 else { 870 return $hinthash->{$hint_feature} // 0; 871 } 872} 873 874sub feature_bundle { 875 my $depth = shift; 876 877 $depth //= 1; 878 my @frame = caller($depth+1) 879 or return; 880 my $bundle_number = $frame[8] & $hint_mask; 881 if ($bundle_number != $hint_mask) { 882 return $hint_bundles[$bundle_number >> $hint_shift]; 883 } 884 else { 885 return undef; 886 } 887} 888 8891; 890 891# ex: set ro ft=perl: 892