lib/feature.pm

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