[Summary view] [Print] [Text view]

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