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