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