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