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