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