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