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! 5 6package feature; 7 8our $VERSION = '1.64'; 9 10our %feature = ( 11 fc => 'feature_fc', 12 isa => 'feature_isa', 13 say => 'feature_say', 14 try => 'feature_try', 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', 29); 30 31our %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 "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)], 38 "default" => [qw(bareword_filehandles indirect multidimensional)], 39); 40 41$feature_bundle{"5.12"} = $feature_bundle{"5.11"}; 42$feature_bundle{"5.13"} = $feature_bundle{"5.11"}; 43$feature_bundle{"5.14"} = $feature_bundle{"5.11"}; 44$feature_bundle{"5.16"} = $feature_bundle{"5.15"}; 45$feature_bundle{"5.17"} = $feature_bundle{"5.15"}; 46$feature_bundle{"5.18"} = $feature_bundle{"5.15"}; 47$feature_bundle{"5.19"} = $feature_bundle{"5.15"}; 48$feature_bundle{"5.20"} = $feature_bundle{"5.15"}; 49$feature_bundle{"5.21"} = $feature_bundle{"5.15"}; 50$feature_bundle{"5.22"} = $feature_bundle{"5.15"}; 51$feature_bundle{"5.24"} = $feature_bundle{"5.23"}; 52$feature_bundle{"5.25"} = $feature_bundle{"5.23"}; 53$feature_bundle{"5.26"} = $feature_bundle{"5.23"}; 54$feature_bundle{"5.28"} = $feature_bundle{"5.27"}; 55$feature_bundle{"5.29"} = $feature_bundle{"5.27"}; 56$feature_bundle{"5.30"} = $feature_bundle{"5.27"}; 57$feature_bundle{"5.31"} = $feature_bundle{"5.27"}; 58$feature_bundle{"5.32"} = $feature_bundle{"5.27"}; 59$feature_bundle{"5.33"} = $feature_bundle{"5.27"}; 60$feature_bundle{"5.34"} = $feature_bundle{"5.27"}; 61$feature_bundle{"5.9.5"} = $feature_bundle{"5.10"}; 62my %noops = ( 63 postderef => 1, 64 lexical_subs => 1, 65); 66my %removed = ( 67 array_base => 1, 68); 69 70our $hint_shift = 26; 71our $hint_mask = 0x3c000000; 72our @hint_bundles = qw( default 5.10 5.11 5.15 5.23 5.27 ); 73 74# This gets set (for now) in $^H as well as in %^H, 75# for runtime speed of the uc/lc/ucfirst/lcfirst functions. 76# See HINT_UNI_8_BIT in perl.h. 77our $hint_uni8bit = 0x00000800; 78 79# TODO: 80# - think about versioned features (use feature switch => 2) 81 82=head1 NAME 83 84feature - Perl pragma to enable new features 85 86=head1 SYNOPSIS 87 88 use feature qw(fc say); 89 90 # Without the "use feature" above, this code would not be able to find 91 # the built-ins "say" or "fc": 92 say "The case-folded version of $x is: " . fc $x; 93 94 95 # set features to match the :5.10 bundle, which may turn off or on 96 # multiple features (see below) 97 use feature ':5.10'; 98 99 100 # implicitly loads :5.10 feature bundle 101 use v5.10; 102 103=head1 DESCRIPTION 104 105It is usually impossible to add new syntax to Perl without breaking 106some existing programs. This pragma provides a way to minimize that 107risk. New syntactic constructs, or new semantic meanings to older 108constructs, can be enabled by C<use feature 'foo'>, and will be parsed 109only when the appropriate feature pragma is in scope. (Nevertheless, the 110C<CORE::> prefix provides access to all Perl keywords, regardless of this 111pragma.) 112 113=head2 Lexical effect 114 115Like other pragmas (C<use strict>, for example), features have a lexical 116effect. C<use feature qw(foo)> will only make the feature "foo" available 117from that point to the end of the enclosing block. 118 119 { 120 use feature 'say'; 121 say "say is available here"; 122 } 123 print "But not here.\n"; 124 125=head2 C<no feature> 126 127Features can also be turned off by using C<no feature "foo">. This too 128has lexical effect. 129 130 use feature 'say'; 131 say "say is available here"; 132 { 133 no feature 'say'; 134 print "But not here.\n"; 135 } 136 say "Yet it is here."; 137 138C<no feature> with no features specified will reset to the default group. To 139disable I<all> features (an unusual request!) use C<no feature ':all'>. 140 141=head1 AVAILABLE FEATURES 142 143=head2 The 'say' feature 144 145C<use feature 'say'> tells the compiler to enable the Raku-inspired 146C<say> function. 147 148See L<perlfunc/say> for details. 149 150This feature is available starting with Perl 5.10. 151 152=head2 The 'state' feature 153 154C<use feature 'state'> tells the compiler to enable C<state> 155variables. 156 157See L<perlsub/"Persistent Private Variables"> for details. 158 159This feature is available starting with Perl 5.10. 160 161=head2 The 'switch' feature 162 163B<WARNING>: This feature is still experimental and the implementation may 164change or be removed in future versions of Perl. For this reason, Perl will 165warn when you use the feature, unless you have explicitly disabled the warning: 166 167 no warnings "experimental::smartmatch"; 168 169C<use feature 'switch'> tells the compiler to enable the Raku 170given/when construct. 171 172See L<perlsyn/"Switch Statements"> for details. 173 174This feature is available starting with Perl 5.10. 175 176=head2 The 'unicode_strings' feature 177 178C<use feature 'unicode_strings'> tells the compiler to use Unicode rules 179in all string operations executed within its scope (unless they are also 180within the scope of either C<use locale> or C<use bytes>). The same applies 181to all regular expressions compiled within the scope, even if executed outside 182it. It does not change the internal representation of strings, but only how 183they are interpreted. 184 185C<no feature 'unicode_strings'> tells the compiler to use the traditional 186Perl rules wherein the native character set rules is used unless it is 187clear to Perl that Unicode is desired. This can lead to some surprises 188when the behavior suddenly changes. (See 189L<perlunicode/The "Unicode Bug"> for details.) For this reason, if you are 190potentially using Unicode in your program, the 191C<use feature 'unicode_strings'> subpragma is B<strongly> recommended. 192 193This feature is available starting with Perl 5.12; was almost fully 194implemented in Perl 5.14; and extended in Perl 5.16 to cover C<quotemeta>; 195was extended further in Perl 5.26 to cover L<the range 196operator|perlop/Range Operators>; and was extended again in Perl 5.28 to 197cover L<special-cased whitespace splitting|perlfunc/split>. 198 199=head2 The 'unicode_eval' and 'evalbytes' features 200 201Together, these two features are intended to replace the legacy string 202C<eval> function, which behaves problematically in some instances. They are 203available starting with Perl 5.16, and are enabled by default by a 204S<C<use 5.16>> or higher declaration. 205 206C<unicode_eval> changes the behavior of plain string C<eval> to work more 207consistently, especially in the Unicode world. Certain (mis)behaviors 208couldn't be changed without breaking some things that had come to rely on 209them, so the feature can be enabled and disabled. Details are at 210L<perlfunc/Under the "unicode_eval" feature>. 211 212C<evalbytes> is like string C<eval>, but operating on a byte stream that is 213not UTF-8 encoded. Details are at L<perlfunc/evalbytes EXPR>. Without a 214S<C<use feature 'evalbytes'>> nor a S<C<use v5.16>> (or higher) declaration in 215the current scope, you can still access it by instead writing 216C<CORE::evalbytes>. 217 218=head2 The 'current_sub' feature 219 220This provides the C<__SUB__> token that returns a reference to the current 221subroutine or C<undef> outside of a subroutine. 222 223This feature is available starting with Perl 5.16. 224 225=head2 The 'array_base' feature 226 227This feature supported the legacy C<$[> variable. See L<perlvar/$[>. 228It was on by default but disabled under C<use v5.16> (see 229L</IMPLICIT LOADING>, below) and unavailable since perl 5.30. 230 231This feature is available under this name starting with Perl 5.16. In 232previous versions, it was simply on all the time, and this pragma knew 233nothing about it. 234 235=head2 The 'fc' feature 236 237C<use feature 'fc'> tells the compiler to enable the C<fc> function, 238which implements Unicode casefolding. 239 240See L<perlfunc/fc> for details. 241 242This feature is available from Perl 5.16 onwards. 243 244=head2 The 'lexical_subs' feature 245 246In Perl versions prior to 5.26, this feature enabled 247declaration of subroutines via C<my sub foo>, C<state sub foo> 248and C<our sub foo> syntax. See L<perlsub/Lexical Subroutines> for details. 249 250This feature is available from Perl 5.18 onwards. From Perl 5.18 to 5.24, 251it was classed as experimental, and Perl emitted a warning for its 252usage, except when explicitly disabled: 253 254 no warnings "experimental::lexical_subs"; 255 256As of Perl 5.26, use of this feature no longer triggers a warning, though 257the C<experimental::lexical_subs> warning category still exists (for 258compatibility with code that disables it). In addition, this syntax is 259not only no longer experimental, but it is enabled for all Perl code, 260regardless of what feature declarations are in scope. 261 262=head2 The 'postderef' and 'postderef_qq' features 263 264The 'postderef_qq' feature extends the applicability of L<postfix 265dereference syntax|perlref/Postfix Dereference Syntax> so that postfix array 266and scalar dereference are available in double-quotish interpolations. For 267example, it makes the following two statements equivalent: 268 269 my $s = "[@{ $h->{a} }]"; 270 my $s = "[$h->{a}->@*]"; 271 272This feature is available from Perl 5.20 onwards. In Perl 5.20 and 5.22, it 273was classed as experimental, and Perl emitted a warning for its 274usage, except when explicitly disabled: 275 276 no warnings "experimental::postderef"; 277 278As of Perl 5.24, use of this feature no longer triggers a warning, though 279the C<experimental::postderef> warning category still exists (for 280compatibility with code that disables it). 281 282The 'postderef' feature was used in Perl 5.20 and Perl 5.22 to enable 283postfix dereference syntax outside double-quotish interpolations. In those 284versions, using it triggered the C<experimental::postderef> warning in the 285same way as the 'postderef_qq' feature did. As of Perl 5.24, this syntax is 286not only no longer experimental, but it is enabled for all Perl code, 287regardless of what feature declarations are in scope. 288 289=head2 The 'signatures' feature 290 291B<WARNING>: This feature is still experimental and the implementation may 292change or be removed in future versions of Perl. For this reason, Perl will 293warn when you use the feature, unless you have explicitly disabled the warning: 294 295 no warnings "experimental::signatures"; 296 297This enables unpacking of subroutine arguments into lexical variables 298by syntax such as 299 300 sub foo ($left, $right) { 301 return $left + $right; 302 } 303 304See L<perlsub/Signatures> for details. 305 306This feature is available from Perl 5.20 onwards. 307 308=head2 The 'refaliasing' feature 309 310B<WARNING>: This feature is still experimental and the implementation may 311change or be removed in future versions of Perl. For this reason, Perl will 312warn when you use the feature, unless you have explicitly disabled the warning: 313 314 no warnings "experimental::refaliasing"; 315 316This enables aliasing via assignment to references: 317 318 \$a = \$b; # $a and $b now point to the same scalar 319 \@a = \@b; # to the same array 320 \%a = \%b; 321 \&a = \&b; 322 foreach \%hash (@array_of_hash_refs) { 323 ... 324 } 325 326See L<perlref/Assigning to References> for details. 327 328This feature is available from Perl 5.22 onwards. 329 330=head2 The 'bitwise' feature 331 332This makes the four standard bitwise operators (C<& | ^ ~>) treat their 333operands consistently as numbers, and introduces four new dotted operators 334(C<&. |. ^. ~.>) that treat their operands consistently as strings. The 335same applies to the assignment variants (C<&= |= ^= &.= |.= ^.=>). 336 337See L<perlop/Bitwise String Operators> for details. 338 339This feature is available from Perl 5.22 onwards. Starting in Perl 5.28, 340C<use v5.28> will enable the feature. Before 5.28, it was still 341experimental and would emit a warning in the "experimental::bitwise" 342category. 343 344=head2 The 'declared_refs' feature 345 346B<WARNING>: This feature is still experimental and the implementation may 347change or be removed in future versions of Perl. For this reason, Perl will 348warn when you use the feature, unless you have explicitly disabled the warning: 349 350 no warnings "experimental::declared_refs"; 351 352This allows a reference to a variable to be declared with C<my>, C<state>, 353our C<our>, or localized with C<local>. It is intended mainly for use in 354conjunction with the "refaliasing" feature. See L<perlref/Declaring a 355Reference to a Variable> for examples. 356 357This feature is available from Perl 5.26 onwards. 358 359=head2 The 'isa' feature 360 361B<WARNING>: This feature is still experimental and the implementation may 362change or be removed in future versions of Perl. For this reason, Perl will 363warn when you use the feature, unless you have explicitly disabled the warning: 364 365 no warnings "experimental::isa"; 366 367This allows the use of the C<isa> infix operator, which tests whether the 368scalar given by the left operand is an object of the class given by the 369right operand. See L<perlop/Class Instance Operator> for more details. 370 371This feature is available from Perl 5.32 onwards. 372 373=head2 The 'indirect' feature 374 375This feature allows the use of L<indirect object 376syntax|perlobj/Indirect Object Syntax> for method calls, e.g. C<new 377Foo 1, 2;>. It is enabled by default, but can be turned off to 378disallow indirect object syntax. 379 380This feature is available under this name from Perl 5.32 onwards. In 381previous versions, it was simply on all the time. To disallow (or 382warn on) indirect object syntax on older Perls, see the L<indirect> 383CPAN module. 384 385=head2 The 'multidimensional' feature 386 387This feature enables multidimensional array emulation, a perl 4 (or 388earlier) feature that was used to emulate multidimensional arrays with 389hashes. This works by converting code like C<< $foo{$x, $y} >> into 390C<< $foo{join($;, $x, $y)} >>. It is enabled by default, but can be 391turned off to disable multidimensional array emulation. 392 393When this feature is disabled the syntax that is normally replaced 394will report a compilation error. 395 396This feature is available under this name from Perl 5.34 onwards. In 397previous versions, it was simply on all the time. 398 399You can use the L<multidimensional> module on CPAN to disable 400multidimensional array emulation for older versions of Perl. 401 402=head2 The 'bareword_filehandles' feature. 403 404This feature enables bareword filehandles for builtin functions 405operations, a generally discouraged practice. It is enabled by 406default, but can be turned off to disable bareword filehandles, except 407for the exceptions listed below. 408 409The perl built-in filehandles C<STDIN>, C<STDOUT>, C<STDERR>, C<DATA>, 410C<ARGV>, C<ARGVOUT> and the special C<_> are always enabled. 411 412This feature is enabled under this name from Perl 5.34 onwards. In 413previous versions it was simply on all the time. 414 415You can use the L<bareword::filehandles> module on CPAN to disable 416bareword filehandles for older versions of perl. 417 418=head2 The 'try' feature. 419 420B<WARNING>: This feature is still experimental and the implementation may 421change or be removed in future versions of Perl. For this reason, Perl will 422warn when you use the feature, unless you have explicitly disabled the warning: 423 424 no warnings "experimental::try"; 425 426This feature enables the C<try> and C<catch> syntax, which allows exception 427handling, where exceptions thrown from the body of the block introduced with 428C<try> are caught by executing the body of the C<catch> block. 429 430For more information, see L<perlsyn/"Try Catch Exception Handling">. 431 432=head1 FEATURE BUNDLES 433 434It's possible to load multiple features together, using 435a I<feature bundle>. The name of a feature bundle is prefixed with 436a colon, to distinguish it from an actual feature. 437 438 use feature ":5.10"; 439 440The following feature bundles are available: 441 442 bundle features included 443 --------- ----------------- 444 :default indirect multidimensional 445 bareword_filehandles 446 447 :5.10 bareword_filehandles indirect 448 multidimensional say state switch 449 450 :5.12 bareword_filehandles indirect 451 multidimensional say state switch 452 unicode_strings 453 454 :5.14 bareword_filehandles indirect 455 multidimensional say state switch 456 unicode_strings 457 458 :5.16 bareword_filehandles current_sub evalbytes 459 fc indirect multidimensional say state 460 switch unicode_eval unicode_strings 461 462 :5.18 bareword_filehandles current_sub evalbytes 463 fc indirect multidimensional say state 464 switch unicode_eval unicode_strings 465 466 :5.20 bareword_filehandles current_sub evalbytes 467 fc indirect multidimensional say state 468 switch unicode_eval unicode_strings 469 470 :5.22 bareword_filehandles current_sub evalbytes 471 fc indirect multidimensional say state 472 switch unicode_eval unicode_strings 473 474 :5.24 bareword_filehandles current_sub evalbytes 475 fc indirect multidimensional postderef_qq 476 say state switch unicode_eval 477 unicode_strings 478 479 :5.26 bareword_filehandles current_sub evalbytes 480 fc indirect multidimensional postderef_qq 481 say state switch unicode_eval 482 unicode_strings 483 484 :5.28 bareword_filehandles bitwise current_sub 485 evalbytes fc indirect multidimensional 486 postderef_qq say state switch unicode_eval 487 unicode_strings 488 489 :5.30 bareword_filehandles bitwise current_sub 490 evalbytes fc indirect multidimensional 491 postderef_qq say state switch unicode_eval 492 unicode_strings 493 494 :5.32 bareword_filehandles bitwise current_sub 495 evalbytes fc indirect multidimensional 496 postderef_qq say state switch unicode_eval 497 unicode_strings 498 499 :5.34 bareword_filehandles bitwise current_sub 500 evalbytes fc indirect multidimensional 501 postderef_qq say state switch unicode_eval 502 unicode_strings 503 504The C<:default> bundle represents the feature set that is enabled before 505any C<use feature> or C<no feature> declaration. 506 507Specifying sub-versions such as the C<0> in C<5.14.0> in feature bundles has 508no effect. Feature bundles are guaranteed to be the same for all sub-versions. 509 510 use feature ":5.14.0"; # same as ":5.14" 511 use feature ":5.14.1"; # same as ":5.14" 512 513=head1 IMPLICIT LOADING 514 515Instead of loading feature bundles by name, it is easier to let Perl do 516implicit loading of a feature bundle for you. 517 518There are two ways to load the C<feature> pragma implicitly: 519 520=over 4 521 522=item * 523 524By using the C<-E> switch on the Perl command-line instead of C<-e>. 525That will enable the feature bundle for that version of Perl in the 526main compilation unit (that is, the one-liner that follows C<-E>). 527 528=item * 529 530By explicitly requiring a minimum Perl version number for your program, with 531the C<use VERSION> construct. That is, 532 533 use v5.10.0; 534 535will do an implicit 536 537 no feature ':all'; 538 use feature ':5.10'; 539 540and so on. Note how the trailing sub-version 541is automatically stripped from the 542version. 543 544But to avoid portability warnings (see L<perlfunc/use>), you may prefer: 545 546 use 5.010; 547 548with the same effect. 549 550If the required version is older than Perl 5.10, the ":default" feature 551bundle is automatically loaded instead. 552 553Unlike C<use feature ":5.12">, saying C<use v5.12> (or any higher version) 554also does the equivalent of C<use strict>; see L<perlfunc/use> for details. 555 556=back 557 558=cut 559 560sub import { 561 shift; 562 563 if (!@_) { 564 croak("No features specified"); 565 } 566 567 __common(1, @_); 568} 569 570sub unimport { 571 shift; 572 573 # A bare C<no feature> should reset to the default bundle 574 if (!@_) { 575 $^H &= ~($hint_uni8bit|$hint_mask); 576 return; 577 } 578 579 __common(0, @_); 580} 581 582 583sub __common { 584 my $import = shift; 585 my $bundle_number = $^H & $hint_mask; 586 my $features = $bundle_number != $hint_mask 587 && $feature_bundle{$hint_bundles[$bundle_number >> $hint_shift]}; 588 if ($features) { 589 # Features are enabled implicitly via bundle hints. 590 # Delete any keys that may be left over from last time. 591 delete @^H{ values(%feature) }; 592 $^H |= $hint_mask; 593 for (@$features) { 594 $^H{$feature{$_}} = 1; 595 $^H |= $hint_uni8bit if $_ eq 'unicode_strings'; 596 } 597 } 598 while (@_) { 599 my $name = shift; 600 if (substr($name, 0, 1) eq ":") { 601 my $v = substr($name, 1); 602 if (!exists $feature_bundle{$v}) { 603 $v =~ s/^([0-9]+)\.([0-9]+).[0-9]+$/$1.$2/; 604 if (!exists $feature_bundle{$v}) { 605 unknown_feature_bundle(substr($name, 1)); 606 } 607 } 608 unshift @_, @{$feature_bundle{$v}}; 609 next; 610 } 611 if (!exists $feature{$name}) { 612 if (exists $noops{$name}) { 613 next; 614 } 615 if (!$import && exists $removed{$name}) { 616 next; 617 } 618 unknown_feature($name); 619 } 620 if ($import) { 621 $^H{$feature{$name}} = 1; 622 $^H |= $hint_uni8bit if $name eq 'unicode_strings'; 623 } else { 624 delete $^H{$feature{$name}}; 625 $^H &= ~ $hint_uni8bit if $name eq 'unicode_strings'; 626 } 627 } 628} 629 630sub unknown_feature { 631 my $feature = shift; 632 croak(sprintf('Feature "%s" is not supported by Perl %vd', 633 $feature, $^V)); 634} 635 636sub unknown_feature_bundle { 637 my $feature = shift; 638 croak(sprintf('Feature bundle "%s" is not supported by Perl %vd', 639 $feature, $^V)); 640} 641 642sub croak { 643 require Carp; 644 Carp::croak(@_); 645} 646 6471; 648 649# ex: set ro: 650