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