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