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