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.
  59
  60 =head2 Lexical effect
  61
  62 Like other pragmas (C<use strict>, for example), features have a lexical
  63 effect. C<use feature qw(foo)> will only make the feature "foo" available
  64 from that point to the end of the enclosing block.
  65
  66     {
  67         use feature 'say';
  68         say "say is available here";
  69     }
  70     print "But not here.\n";
  71
  72 =head2 C<no feature>
  73
  74 Features can also be turned off by using C<no feature "foo">. This too
  75 has lexical effect.
  76
  77     use feature 'say';
  78     say "say is available here";
  79     {
  80         no feature 'say';
  81         print "But not here.\n";
  82     }
  83     say "Yet it is here.";
  84
  85 C<no feature> with no features specified will turn off all features.
  86
  87 =head2 The 'switch' feature
  88
  89 C<use feature 'switch'> tells the compiler to enable the Perl 6
  90 given/when construct.
  91
  92 See L<perlsyn/"Switch statements"> for details.
  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 'unicode_strings' feature
 109
 110 C<use feature 'unicode_strings'> tells the compiler to use Unicode semantics
 111 in all string operations executed within its scope (unless they are also
 112 within the scope of either C<use locale> or C<use bytes>).  The same applies
 113 to all regular expressions compiled within the scope, even if executed outside
 114 it.
 115
 116 C<no feature 'unicode_strings'> tells the compiler to use the traditional
 117 Perl semantics wherein the native character set semantics is used unless it is
 118 clear to Perl that Unicode is desired.  This can lead to some surprises
 119 when the behavior suddenly changes.  (See
 120 L<perlunicode/The "Unicode Bug"> for details.)  For this reason, if you are
 121 potentially using Unicode in your program, the
 122 C<use feature 'unicode_strings'> subpragma is B<strongly> recommended.
 123
 124 This subpragma is available starting with Perl 5.11.3, but was not fully
 125 implemented until 5.13.8.
 126
 127 =head1 FEATURE BUNDLES
 128
 129 It's possible to load a whole slew of features in one go, using
 130 a I<feature bundle>. The name of a feature bundle is prefixed with
 131 a colon, to distinguish it from an actual feature. At present, the
 132 only feature bundles correspond to Perl releases, e.g. C<use feature
 133 ":5.10"> which is equivalent to C<use feature qw(switch say state)>.
 134
 135 By convention, the feature bundle for any given Perl release includes
 136 the features of previous releases, down to and including 5.10, the
 137 first official release to provide this facility. Since Perl 5.12
 138 only provides one new feature, C<unicode_strings>, and Perl 5.14
 139 provides none, C<use feature ":5.14"> is equivalent to C<use feature
 140 qw(switch say state unicode_strings)>.
 141
 142 Specifying sub-versions such as the C<0> in C<5.14.0> in feature bundles has
 143 no effect: feature bundles are guaranteed to be the same for all sub-versions.
 144
 145 Note that instead of using release-based feature bundles it is usually
 146 better, and shorter, to use implicit loading as described below.
 147
 148 =head1 IMPLICIT LOADING
 149
 150 There are two ways to load the C<feature> pragma implicitly :
 151
 152 =over 4
 153
 154 =item *
 155
 156 By using the C<-E> switch on the command-line instead of C<-e>. It enables
 157 all available features in the main compilation unit (that is, the one-liner.)
 158
 159 =item *
 160
 161 By requiring explicitly a minimal Perl version number for your program, with
 162 the C<use VERSION> construct, and when the version is higher than or equal to
 163 5.10.0. That is,
 164
 165     use 5.10.0;
 166
 167 will do an implicit
 168
 169     use feature ':5.10';
 170
 171 and so on. Note how the trailing sub-version is automatically stripped from the
 172 version.
 173
 174 But to avoid portability warnings (see L<perlfunc/use>), you may prefer:
 175
 176     use 5.010;
 177
 178 with the same effect.
 179
 180 =back
 181
 182 =cut
 183
 184 sub import {
 185     my $class = shift;
 186     if (@_ == 0) {
 187         croak("No features specified");
 188     }
 189     while (@_) {
 190         my $name = shift(@_);
 191         if (substr($name, 0, 1) eq ":") {
 192             my $v = substr($name, 1);
 193             if (!exists $feature_bundle{$v}) {
 194                 $v =~ s/^([0-9]+)\.([0-9]+).[0-9]+$/$1.$2/;
 195                 if (!exists $feature_bundle{$v}) {
 196                     unknown_feature_bundle(substr($name, 1));
 197                 }
 198             }
 199             unshift @_, @{$feature_bundle{$v}};
 200             next;
 201         }
 202         if (!exists $feature{$name}) {
 203             unknown_feature($name);
 204         }
 205         $^H{$feature{$name}} = 1;
 206         $^H |= $hint_uni8bit if $name eq 'unicode_strings';
 207     }
 208 }
 209
 210 sub unimport {
 211     my $class = shift;
 212
 213     # A bare C<no feature> should disable *all* features
 214     if (!@_) {
 215         delete @^H{ values(%feature) };
 216         $^H &= ~ $hint_uni8bit;
 217         return;
 218     }
 219
 220     while (@_) {
 221         my $name = shift;
 222         if (substr($name, 0, 1) eq ":") {
 223             my $v = substr($name, 1);
 224             if (!exists $feature_bundle{$v}) {
 225                 $v =~ s/^([0-9]+)\.([0-9]+).[0-9]+$/$1.$2/;
 226                 if (!exists $feature_bundle{$v}) {
 227                     unknown_feature_bundle(substr($name, 1));
 228                 }
 229             }
 230             unshift @_, @{$feature_bundle{$v}};
 231             next;
 232         }
 233         if (!exists($feature{$name})) {
 234             unknown_feature($name);
 235         }
 236         else {
 237             delete $^H{$feature{$name}};
 238             $^H &= ~ $hint_uni8bit if $name eq 'unicode_strings';
 239         }
 240     }
 241 }
 242
 243 sub unknown_feature {
 244     my $feature = shift;
 245     croak(sprintf('Feature "%s" is not supported by Perl %vd',
 246             $feature, $^V));
 247 }
 248
 249 sub unknown_feature_bundle {
 250     my $feature = shift;
 251     croak(sprintf('Feature bundle "%s" is not supported by Perl %vd',
 252             $feature, $^V));
 253 }
 254
 255 sub croak {
 256     require Carp;
 257     Carp::croak(@_);
 258 }
 259
 260 1;