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