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