lib/feature.pm

   1 package feature;
   2
   3 our $VERSION = '1.14';
   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 our $hint_uni8bit = 0x00000800;
  16
  17 # NB. the latest bundle must be loaded by the -E switch (see toke.c)
  18
  19 my %feature_bundle = (
  20     "5.10" => [qw(switch say state)],
  21     "5.11" => [qw(switch say state unicode_strings)],
  22 );
  23
  24 # special case
  25 $feature_bundle{"5.9.5"} = $feature_bundle{"5.10"};
  26
  27 # TODO:
  28 # - think about versioned features (use feature switch => 2)
  29
  30 =head1 NAME
  31
  32 feature - Perl pragma to enable new features
  33
  34 =head1 SYNOPSIS
  35
  36     use feature qw(switch say);
  37     given ($foo) {
  38         when (1)          { say "\$foo == 1" }
  39         when ([2,3])      { say "\$foo == 2 || \$foo == 3" }
  40         when (/^a[bc]d$/) { say "\$foo eq 'abd' || \$foo eq 'acd'" }
  41         when ($_ > 100)   { say "\$foo > 100" }
  42         default           { say "None of the above" }
  43     }
  44
  45     use feature ':5.10'; # loads all features available in perl 5.10
  46
  47 =head1 DESCRIPTION
  48
  49 It is usually impossible to add new syntax to Perl without breaking
  50 some existing programs. This pragma provides a way to minimize that
  51 risk. New syntactic constructs, or new semantic meanings to older
  52 constructs, can be enabled by C<use feature 'foo'>, and will be parsed
  53 only when the appropriate feature pragma is in scope.
  54
  55 =head2 Lexical effect
  56
  57 Like other pragmas (C<use strict>, for example), features have a lexical
  58 effect. C<use feature qw(foo)> will only make the feature "foo" available
  59 from that point to the end of the enclosing block.
  60
  61     {
  62         use feature 'say';
  63         say "say is available here";
  64     }
  65     print "But not here.\n";
  66
  67 =head2 C<no feature>
  68
  69 Features can also be turned off by using C<no feature "foo">. This too
  70 has lexical effect.
  71
  72     use feature 'say';
  73     say "say is available here";
  74     {
  75         no feature 'say';
  76         print "But not here.\n";
  77     }
  78     say "Yet it is here.";
  79
  80 C<no feature> with no features specified will turn off all features.
  81
  82 =head2 The 'switch' feature
  83
  84 C<use feature 'switch'> tells the compiler to enable the Perl 6
  85 given/when construct.
  86
  87 See L<perlsyn/"Switch statements"> for details.
  88
  89 =head2 The 'say' feature
  90
  91 C<use feature 'say'> tells the compiler to enable the Perl 6
  92 C<say> function.
  93
  94 See L<perlfunc/say> for details.
  95
  96 =head2 the 'state' feature
  97
  98 C<use feature 'state'> tells the compiler to enable C<state>
  99 variables.
 100
 101 See L<perlsub/"Persistent Private Variables"> for details.
 102
 103 =head2 the 'unicode_strings' feature
 104
 105 C<use feature 'unicode_strings'> tells the compiler to treat
 106 all strings outside of C<use locale> and C<use bytes> as Unicode. It is
 107 available starting with Perl 5.11.3.
 108
 109 See L<perlunicode/The "Unicode Bug"> for details.
 110
 111 =head1 FEATURE BUNDLES
 112
 113 It's possible to load a whole slew of features in one go, using
 114 a I<feature bundle>. The name of a feature bundle is prefixed with
 115 a colon, to distinguish it from an actual feature. At present, the
 116 only feature bundle is C<use feature ":5.10"> which is equivalent
 117 to C<use feature qw(switch say state)>.
 118
 119 Specifying sub-versions such as the C<0> in C<5.10.0> in feature bundles has
 120 no effect: feature bundles are guaranteed to be the same for all sub-versions.
 121
 122 =head1 IMPLICIT LOADING
 123
 124 There are two ways to load the C<feature> pragma implicitly :
 125
 126 =over 4
 127
 128 =item *
 129
 130 By using the C<-E> switch on the command-line instead of C<-e>. It enables
 131 all available features in the main compilation unit (that is, the one-liner.)
 132
 133 =item *
 134
 135 By requiring explicitly a minimal Perl version number for your program, with
 136 the C<use VERSION> construct, and when the version is higher than or equal to
 137 5.10.0. That is,
 138
 139     use 5.10.0;
 140
 141 will do an implicit
 142
 143     use feature ':5.10';
 144
 145 and so on. Note how the trailing sub-version is automatically stripped from the
 146 version.
 147
 148 But to avoid portability warnings (see L<perlfunc/use>), you may prefer:
 149
 150     use 5.010;
 151
 152 with the same effect.
 153
 154 =back
 155
 156 =cut
 157
 158 sub import {
 159     my $class = shift;
 160     if (@_ == 0) {
 161         croak("No features specified");
 162     }
 163     while (@_) {
 164         my $name = shift(@_);
 165         if (substr($name, 0, 1) eq ":") {
 166             my $v = substr($name, 1);
 167             if (!exists $feature_bundle{$v}) {
 168                 $v =~ s/^([0-9]+)\.([0-9]+).[0-9]+$/$1.$2/;
 169                 if (!exists $feature_bundle{$v}) {
 170                     unknown_feature_bundle(substr($name, 1));
 171                 }
 172             }
 173             unshift @_, @{$feature_bundle{$v}};
 174             next;
 175         }
 176         if (!exists $feature{$name}) {
 177             unknown_feature($name);
 178         }
 179         $^H{$feature{$name}} = 1;
 180         $^H |= $hint_uni8bit if $name eq 'unicode_strings';
 181     }
 182 }
 183
 184 sub unimport {
 185     my $class = shift;
 186
 187     # A bare C<no feature> should disable *all* features
 188     if (!@_) {
 189         delete @^H{ values(%feature) };
 190         $^H &= ~ $hint_uni8bit;
 191         return;
 192     }
 193
 194     while (@_) {
 195         my $name = shift;
 196         if (substr($name, 0, 1) eq ":") {
 197             my $v = substr($name, 1);
 198             if (!exists $feature_bundle{$v}) {
 199                 $v =~ s/^([0-9]+)\.([0-9]+).[0-9]+$/$1.$2/;
 200                 if (!exists $feature_bundle{$v}) {
 201                     unknown_feature_bundle(substr($name, 1));
 202                 }
 203             }
 204             unshift @_, @{$feature_bundle{$v}};
 205             next;
 206         }
 207         if (!exists($feature{$name})) {
 208             unknown_feature($name);
 209         }
 210         else {
 211             delete $^H{$feature{$name}};
 212             $^H &= ~ $hint_uni8bit if $name eq 'unicode_strings';
 213         }
 214     }
 215 }
 216
 217 sub unknown_feature {
 218     my $feature = shift;
 219     croak(sprintf('Feature "%s" is not supported by Perl %vd',
 220             $feature, $^V));
 221 }
 222
 223 sub unknown_feature_bundle {
 224     my $feature = shift;
 225     croak(sprintf('Feature bundle "%s" is not supported by Perl %vd',
 226             $feature, $^V));
 227 }
 228
 229 sub croak {
 230     require Carp;
 231     Carp::croak(@_);
 232 }
 233
 234 1;