lib/feature.pm

   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
   6 package feature;
   7
   8 our $VERSION = '1.58';
   9
  10 our %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
  28 our %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"};
  57 my %noops = (
  58     postderef => 1,
  59     lexical_subs => 1,
  60 );
  61 my %removed = (
  62     array_base => 1,
  63 );
  64
  65 our $hint_shift   = 26;
  66 our $hint_mask    = 0x1c000000;
  67 our @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.
  72 our $hint_uni8bit = 0x00000800;
  73
  74 # TODO:
  75 # - think about versioned features (use feature switch => 2)
  76
  77 =head1 NAME
  78
  79 feature - 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
  98 It is usually impossible to add new syntax to Perl without breaking
  99 some existing programs.  This pragma provides a way to minimize that
 100 risk. New syntactic constructs, or new semantic meanings to older
 101 constructs, can be enabled by C<use feature 'foo'>, and will be parsed
 102 only when the appropriate feature pragma is in scope.  (Nevertheless, the
 103 C<CORE::> prefix provides access to all Perl keywords, regardless of this
 104 pragma.)
 105
 106 =head2 Lexical effect
 107
 108 Like other pragmas (C<use strict>, for example), features have a lexical
 109 effect.  C<use feature qw(foo)> will only make the feature "foo" available
 110 from 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
 120 Features can also be turned off by using C<no feature "foo">.  This too
 121 has 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
 131 C<no feature> with no features specified will reset to the default group.  To
 132 disable I<all> features (an unusual request!) use C<no feature ':all'>.
 133
 134 =head1 AVAILABLE FEATURES
 135
 136 =head2 The 'say' feature
 137
 138 C<use feature 'say'> tells the compiler to enable the Perl 6 style
 139 C<say> function.
 140
 141 See L<perlfunc/say> for details.
 142
 143 This feature is available starting with Perl 5.10.
 144
 145 =head2 The 'state' feature
 146
 147 C<use feature 'state'> tells the compiler to enable C<state>
 148 variables.
 149
 150 See L<perlsub/"Persistent Private Variables"> for details.
 151
 152 This feature is available starting with Perl 5.10.
 153
 154 =head2 The 'switch' feature
 155
 156 B<WARNING>: Because the L<smartmatch operator|perlop/"Smartmatch Operator"> is
 157 experimental, Perl will warn when you use this feature, unless you have
 158 explicitly disabled the warning:
 159
 160     no warnings "experimental::smartmatch";
 161
 162 C<use feature 'switch'> tells the compiler to enable the Perl 6
 163 given/when construct.
 164
 165 See L<perlsyn/"Switch Statements"> for details.
 166
 167 This feature is available starting with Perl 5.10.
 168
 169 =head2 The 'unicode_strings' feature
 170
 171 C<use feature 'unicode_strings'> tells the compiler to use Unicode rules
 172 in all string operations executed within its scope (unless they are also
 173 within the scope of either C<use locale> or C<use bytes>).  The same applies
 174 to all regular expressions compiled within the scope, even if executed outside
 175 it.  It does not change the internal representation of strings, but only how
 176 they are interpreted.
 177
 178 C<no feature 'unicode_strings'> tells the compiler to use the traditional
 179 Perl rules wherein the native character set rules is used unless it is
 180 clear to Perl that Unicode is desired.  This can lead to some surprises
 181 when the behavior suddenly changes.  (See
 182 L<perlunicode/The "Unicode Bug"> for details.)  For this reason, if you are
 183 potentially using Unicode in your program, the
 184 C<use feature 'unicode_strings'> subpragma is B<strongly> recommended.
 185
 186 This feature is available starting with Perl 5.12; was almost fully
 187 implemented in Perl 5.14; and extended in Perl 5.16 to cover C<quotemeta>;
 188 was extended further in Perl 5.26 to cover L<the range
 189 operator|perlop/Range Operators>; and was extended again in Perl 5.28 to
 190 cover L<special-cased whitespace splitting|perlfunc/split>.
 191
 192 =head2 The 'unicode_eval' and 'evalbytes' features
 193
 194 Together, these two features are intended to replace the legacy string
 195 C<eval> function, which behaves problematically in some instances.  They are
 196 available starting with Perl 5.16, and are enabled by default by a
 197 S<C<use 5.16>> or higher declaration.
 198
 199 C<unicode_eval> changes the behavior of plain string C<eval> to work more
 200 consistently, especially in the Unicode world.  Certain (mis)behaviors
 201 couldn't be changed without breaking some things that had come to rely on
 202 them, so the feature can be enabled and disabled.  Details are at
 203 L<perlfunc/Under the "unicode_eval" feature>.
 204
 205 C<evalbytes> is like string C<eval>, but operating on a byte stream that is
 206 not UTF-8 encoded.  Details are at L<perlfunc/evalbytes EXPR>.  Without a
 207 S<C<use feature 'evalbytes'>> nor a S<C<use v5.16>> (or higher) declaration in
 208 the current scope, you can still access it by instead writing
 209 C<CORE::evalbytes>.
 210
 211 =head2 The 'current_sub' feature
 212
 213 This provides the C<__SUB__> token that returns a reference to the current
 214 subroutine or C<undef> outside of a subroutine.
 215
 216 This feature is available starting with Perl 5.16.
 217
 218 =head2 The 'array_base' feature
 219
 220 This feature supported the legacy C<$[> variable.  See L<perlvar/$[>.
 221 It was on by default but disabled under C<use v5.16> (see
 222 L</IMPLICIT LOADING>, below) and unavailable since perl 5.30.
 223
 224 This feature is available under this name starting with Perl 5.16.  In
 225 previous versions, it was simply on all the time, and this pragma knew
 226 nothing about it.
 227
 228 =head2 The 'fc' feature
 229
 230 C<use feature 'fc'> tells the compiler to enable the C<fc> function,
 231 which implements Unicode casefolding.
 232
 233 See L<perlfunc/fc> for details.
 234
 235 This feature is available from Perl 5.16 onwards.
 236
 237 =head2 The 'lexical_subs' feature
 238
 239 In Perl versions prior to 5.26, this feature enabled
 240 declaration of subroutines via C<my sub foo>, C<state sub foo>
 241 and C<our sub foo> syntax.  See L<perlsub/Lexical Subroutines> for details.
 242
 243 This feature is available from Perl 5.18 onwards.  From Perl 5.18 to 5.24,
 244 it was classed as experimental, and Perl emitted a warning for its
 245 usage, except when explicitly disabled:
 246
 247   no warnings "experimental::lexical_subs";
 248
 249 As of Perl 5.26, use of this feature no longer triggers a warning, though
 250 the C<experimental::lexical_subs> warning category still exists (for
 251 compatibility with code that disables it).  In addition, this syntax is
 252 not only no longer experimental, but it is enabled for all Perl code,
 253 regardless of what feature declarations are in scope.
 254
 255 =head2 The 'postderef' and 'postderef_qq' features
 256
 257 The 'postderef_qq' feature extends the applicability of L<postfix
 258 dereference syntax|perlref/Postfix Dereference Syntax> so that postfix array
 259 and scalar dereference are available in double-quotish interpolations. For
 260 example, it makes the following two statements equivalent:
 261
 262   my $s = "[@{ $h->{a} }]";
 263   my $s = "[$h->{a}->@*]";
 264
 265 This feature is available from Perl 5.20 onwards. In Perl 5.20 and 5.22, it
 266 was classed as experimental, and Perl emitted a warning for its
 267 usage, except when explicitly disabled:
 268
 269   no warnings "experimental::postderef";
 270
 271 As of Perl 5.24, use of this feature no longer triggers a warning, though
 272 the C<experimental::postderef> warning category still exists (for
 273 compatibility with code that disables it).
 274
 275 The 'postderef' feature was used in Perl 5.20 and Perl 5.22 to enable
 276 postfix dereference syntax outside double-quotish interpolations. In those
 277 versions, using it triggered the C<experimental::postderef> warning in the
 278 same way as the 'postderef_qq' feature did. As of Perl 5.24, this syntax is
 279 not only no longer experimental, but it is enabled for all Perl code,
 280 regardless of what feature declarations are in scope.
 281
 282 =head2 The 'signatures' feature
 283
 284 B<WARNING>: This feature is still experimental and the implementation may
 285 change in future versions of Perl.  For this reason, Perl will
 286 warn when you use the feature, unless you have explicitly disabled the
 287 warning:
 288
 289     no warnings "experimental::signatures";
 290
 291 This enables unpacking of subroutine arguments into lexical variables
 292 by syntax such as
 293
 294     sub foo ($left, $right) {
 295         return $left + $right;
 296     }
 297
 298 See L<perlsub/Signatures> for details.
 299
 300 This feature is available from Perl 5.20 onwards.
 301
 302 =head2 The 'refaliasing' feature
 303
 304 B<WARNING>: This feature is still experimental and the implementation may
 305 change in future versions of Perl.  For this reason, Perl will
 306 warn when you use the feature, unless you have explicitly disabled the
 307 warning:
 308
 309     no warnings "experimental::refaliasing";
 310
 311 This 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
 321 See L<perlref/Assigning to References> for details.
 322
 323 This feature is available from Perl 5.22 onwards.
 324
 325 =head2 The 'bitwise' feature
 326
 327 This makes the four standard bitwise operators (C<& | ^ ~>) treat their
 328 operands consistently as numbers, and introduces four new dotted operators
 329 (C<&. |. ^. ~.>) that treat their operands consistently as strings.  The
 330 same applies to the assignment variants (C<&= |= ^= &.= |.= ^.=>).
 331
 332 See L<perlop/Bitwise String Operators> for details.
 333
 334 This feature is available from Perl 5.22 onwards.  Starting in Perl 5.28,
 335 C<use v5.28> will enable the feature.  Before 5.28, it was still
 336 experimental and would emit a warning in the "experimental::bitwise"
 337 category.
 338
 339 =head2 The 'declared_refs' feature
 340
 341 B<WARNING>: This feature is still experimental and the implementation may
 342 change in future versions of Perl.  For this reason, Perl will
 343 warn when you use the feature, unless you have explicitly disabled the
 344 warning:
 345
 346     no warnings "experimental::declared_refs";
 347
 348 This allows a reference to a variable to be declared with C<my>, C<state>,
 349 our C<our>, or localized with C<local>.  It is intended mainly for use in
 350 conjunction with the "refaliasing" feature.  See L<perlref/Declaring a
 351 Reference to a Variable> for examples.
 352
 353 This feature is available from Perl 5.26 onwards.
 354
 355 =head2 The 'isa' feature
 356
 357 This allows the use of the C<isa> infix operator, which tests whether the
 358 scalar given by the left operand is an object of the class given by the
 359 right operand. See L<perlop/Class Instance Operator> for more details.
 360
 361 This feature is available from Perl 5.32 onwards.
 362
 363 =head2 The 'indirect' feature
 364
 365 This feature allows the use of L<indirect object
 366 syntax|perlobj/Indirect Object Syntax> for method calls, e.g.  C<new
 367 Foo 1, 2;>. It is enabled by default, but can be turned off to
 368 disallow indirect object syntax.
 369
 370 This feature is available under this name from Perl 5.32 onwards. In
 371 previous versions, it was simply on all the time.  To disallow (or
 372 warn on) indirect object syntax on older Perls, see the L<indirect>
 373 CPAN module.
 374
 375 =head1 FEATURE BUNDLES
 376
 377 It's possible to load multiple features together, using
 378 a I<feature bundle>.  The name of a feature bundle is prefixed with
 379 a colon, to distinguish it from an actual feature.
 380
 381   use feature ":5.10";
 382
 383 The 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
 431 The C<:default> bundle represents the feature set that is enabled before
 432 any C<use feature> or C<no feature> declaration.
 433
 434 Specifying sub-versions such as the C<0> in C<5.14.0> in feature bundles has
 435 no 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
 442 Instead of loading feature bundles by name, it is easier to let Perl do
 443 implicit loading of a feature bundle for you.
 444
 445 There are two ways to load the C<feature> pragma implicitly:
 446
 447 =over 4
 448
 449 =item *
 450
 451 By using the C<-E> switch on the Perl command-line instead of C<-e>.
 452 That will enable the feature bundle for that version of Perl in the
 453 main compilation unit (that is, the one-liner that follows C<-E>).
 454
 455 =item *
 456
 457 By explicitly requiring a minimum Perl version number for your program, with
 458 the C<use VERSION> construct.  That is,
 459
 460     use v5.10.0;
 461
 462 will do an implicit
 463
 464     no feature ':all';
 465     use feature ':5.10';
 466
 467 and so on.  Note how the trailing sub-version
 468 is automatically stripped from the
 469 version.
 470
 471 But to avoid portability warnings (see L<perlfunc/use>), you may prefer:
 472
 473     use 5.010;
 474
 475 with the same effect.
 476
 477 If the required version is older than Perl 5.10, the ":default" feature
 478 bundle is automatically loaded instead.
 479
 480 Unlike C<use feature ":5.12">, saying C<use v5.12> (or any higher version)
 481 also does the equivalent of C<use strict>; see L<perlfunc/use> for details.
 482
 483 =back
 484
 485 =cut
 486
 487 sub import {
 488     shift;
 489
 490     if (!@_) {
 491         croak("No features specified");
 492     }
 493
 494     __common(1, @_);
 495 }
 496
 497 sub 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
 510 sub __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
 557 sub unknown_feature {
 558     my $feature = shift;
 559     croak(sprintf('Feature "%s" is not supported by Perl %vd',
 560             $feature, $^V));
 561 }
 562
 563 sub unknown_feature_bundle {
 564     my $feature = shift;
 565     croak(sprintf('Feature bundle "%s" is not supported by Perl %vd',
 566             $feature, $^V));
 567 }
 568
 569 sub croak {
 570     require Carp;
 571     Carp::croak(@_);
 572 }
 573
 574 1;
 575
 576 # ex: set ro: