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