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