lib/feature.pm

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