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