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