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