lib/feature.pm

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