This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
feature.pm: Avoid repetition; save memory
[perl5.git] / 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     evalbytes       => 'feature_evalbytes',
11     unicode_eval    => 'feature_unieval',
12     unicode_strings => 'feature_unicode',
13 );
14
15 # This gets set (for now) in $^H as well as in %^H,
16 # for runtime speed of the uc/lc/ucfirst/lcfirst functions.
17 # See HINT_UNI_8_BIT in perl.h.
18 our $hint_uni8bit = 0x00000800;
19
20 # NB. the latest bundle must be loaded by the -E switch (see toke.c)
21
22 our %feature_bundle = (
23     "5.10" => [qw(say state switch)],
24     "5.11" => [qw(say state switch unicode_strings)],
25     "5.15" => [qw(say state switch unicode_strings unicode_eval
26                   evalbytes)],
27 );
28
29 # Each of these is the same as the previous bundle
30 for(12...14, 16) {
31     $feature_bundle{"5.$_"} = $feature_bundle{"5.".($_-1)}
32 }
33
34 # special case
35 $feature_bundle{"5.9.5"} = $feature_bundle{"5.10"};
36
37 # TODO:
38 # - think about versioned features (use feature switch => 2)
39
40 =head1 NAME
41
42 feature - Perl pragma to enable new features
43
44 =head1 SYNOPSIS
45
46     use feature qw(say switch);
47     given ($foo) {
48         when (1)          { say "\$foo == 1" }
49         when ([2,3])      { say "\$foo == 2 || \$foo == 3" }
50         when (/^a[bc]d$/) { say "\$foo eq 'abd' || \$foo eq 'acd'" }
51         when ($_ > 100)   { say "\$foo > 100" }
52         default           { say "None of the above" }
53     }
54
55     use feature ':5.10'; # loads all features available in perl 5.10
56
57 =head1 DESCRIPTION
58
59 It is usually impossible to add new syntax to Perl without breaking
60 some existing programs. This pragma provides a way to minimize that
61 risk. New syntactic constructs, or new semantic meanings to older
62 constructs, can be enabled by C<use feature 'foo'>, and will be parsed
63 only when the appropriate feature pragma is in scope. (Nevertheless, the
64 C<CORE::> prefix provides access to all Perl keywords, regardless of this
65 pragma.)
66
67 =head2 Lexical effect
68
69 Like other pragmas (C<use strict>, for example), features have a lexical
70 effect. C<use feature qw(foo)> will only make the feature "foo" available
71 from that point to the end of the enclosing block.
72
73     {
74         use feature 'say';
75         say "say is available here";
76     }
77     print "But not here.\n";
78
79 =head2 C<no feature>
80
81 Features can also be turned off by using C<no feature "foo">. This too
82 has lexical effect.
83
84     use feature 'say';
85     say "say is available here";
86     {
87         no feature 'say';
88         print "But not here.\n";
89     }
90     say "Yet it is here.";
91
92 C<no feature> with no features specified will turn off all features.
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 'switch' feature
109
110 C<use feature 'switch'> tells the compiler to enable the Perl 6
111 given/when construct.
112
113 See L<perlsyn/"Switch statements"> for details.
114
115 =head2 the 'unicode_strings' feature
116
117 C<use feature 'unicode_strings'> tells the compiler to use Unicode semantics
118 in all string operations executed within its scope (unless they are also
119 within the scope of either C<use locale> or C<use bytes>).  The same applies
120 to all regular expressions compiled within the scope, even if executed outside
121 it.
122
123 C<no feature 'unicode_strings'> tells the compiler to use the traditional
124 Perl semantics wherein the native character set semantics is used unless it is
125 clear to Perl that Unicode is desired.  This can lead to some surprises
126 when the behavior suddenly changes.  (See
127 L<perlunicode/The "Unicode Bug"> for details.)  For this reason, if you are
128 potentially using Unicode in your program, the
129 C<use feature 'unicode_strings'> subpragma is B<strongly> recommended.
130
131 This subpragma is available starting with Perl 5.11.3, but was not fully
132 implemented until 5.13.8.
133
134 =head2 the 'unicode_eval' and 'evalbytes' features
135
136 Under the C<unicode_eval> feature, Perl's C<eval> function, when passed a
137 string, will evaluate it as a string of characters, ignoring any
138 C<use utf8> declarations.  C<use utf8> exists to declare the encoding of
139 the script, which only makes sense for a stream of bytes, not a string of
140 characters.  Source filters are forbidden, as they also really only make
141 sense on strings of bytes.  Any attempt to activate a source filter will
142 result in an error.
143
144 The C<evalbytes> feature enables the C<evalbytes> keyword, which evaluates
145 the argument passed to it as a string of bytes.  It dies if the string
146 contains any characters outside the 8-bit range.  Source filters work
147 within C<evalbytes>: they apply to the contents of the string being
148 evaluated.
149
150 Together, these two features are intended to replace the historical C<eval>
151 function, which has (at least) two bugs in it, that cannot easily be fixed
152 without breaking existing programs:
153
154 =over
155
156 =item *
157
158 C<eval> behaves differently depending on the internal encoding of the
159 string, sometimes treating its argument as a string of bytes, and sometimes
160 as a string of characters.
161
162 =item *
163
164 Source filters activated within C<eval> leak out into whichever I<file>
165 scope is currently being compiled.  To give an example with the CPAN module
166 L<Semi::Semicolons>:
167
168     BEGIN { eval "use Semi::Semicolons;  # not filtered here " }
169     # filtered here!
170
171 C<evalbytes> fixes that to work the way one would expect:
172
173     use feature "evalbytes";
174     BEGIN { evalbytes "use Semi::Semicolons;  # filtered " }
175     # not filtered
176
177 =back
178
179 These two features are available starting with Perl 5.16.
180
181 =head1 FEATURE BUNDLES
182
183 It's possible to load a whole slew of features in one go, using
184 a I<feature bundle>. The name of a feature bundle is prefixed with
185 a colon, to distinguish it from an actual feature. At present, the
186 only feature bundles correspond to Perl releases, e.g. C<use feature
187 ":5.10"> which is equivalent to C<use feature qw(switch say state)>.
188
189 By convention, the feature bundle for any given Perl release includes
190 the features of previous releases, down to and including 5.10, the
191 first official release to provide this facility. Since Perl 5.12
192 only provides one new feature, C<unicode_strings>, and Perl 5.14
193 provides none, C<use feature ":5.14"> is equivalent to C<use feature
194 qw(switch say state unicode_strings)>.
195
196 Specifying sub-versions such as the C<0> in C<5.14.0> in feature bundles has
197 no effect: feature bundles are guaranteed to be the same for all sub-versions.
198
199 Note that instead of using release-based feature bundles it is usually
200 better, and shorter, to use implicit loading as described below.
201
202 =head1 IMPLICIT LOADING
203
204 There are two ways to load the C<feature> pragma implicitly :
205
206 =over 4
207
208 =item *
209
210 By using the C<-E> switch on the command-line instead of C<-e>. It enables
211 all available features in the main compilation unit (that is, the one-liner.)
212
213 =item *
214
215 By requiring explicitly a minimal Perl version number for your program, with
216 the C<use VERSION> construct, and when the version is higher than or equal to
217 5.10.0. That is,
218
219     use 5.10.0;
220
221 will do an implicit
222
223     use feature ':5.10';
224
225 and so on. Note how the trailing sub-version is automatically stripped from the
226 version.
227
228 But to avoid portability warnings (see L<perlfunc/use>), you may prefer:
229
230     use 5.010;
231
232 with the same effect.
233
234 =back
235
236 =cut
237
238 sub import {
239     my $class = shift;
240     if (@_ == 0) {
241         croak("No features specified");
242     }
243     while (@_) {
244         my $name = shift(@_);
245         if (substr($name, 0, 1) eq ":") {
246             my $v = substr($name, 1);
247             if (!exists $feature_bundle{$v}) {
248                 $v =~ s/^([0-9]+)\.([0-9]+).[0-9]+$/$1.$2/;
249                 if (!exists $feature_bundle{$v}) {
250                     unknown_feature_bundle(substr($name, 1));
251                 }
252             }
253             unshift @_, @{$feature_bundle{$v}};
254             next;
255         }
256         if (!exists $feature{$name}) {
257             unknown_feature($name);
258         }
259         $^H{$feature{$name}} = 1;
260         $^H |= $hint_uni8bit if $name eq 'unicode_strings';
261     }
262 }
263
264 sub unimport {
265     my $class = shift;
266
267     # A bare C<no feature> should disable *all* features
268     if (!@_) {
269         delete @^H{ values(%feature) };
270         $^H &= ~ $hint_uni8bit;
271         return;
272     }
273
274     while (@_) {
275         my $name = shift;
276         if (substr($name, 0, 1) eq ":") {
277             my $v = substr($name, 1);
278             if (!exists $feature_bundle{$v}) {
279                 $v =~ s/^([0-9]+)\.([0-9]+).[0-9]+$/$1.$2/;
280                 if (!exists $feature_bundle{$v}) {
281                     unknown_feature_bundle(substr($name, 1));
282                 }
283             }
284             unshift @_, @{$feature_bundle{$v}};
285             next;
286         }
287         if (!exists($feature{$name})) {
288             unknown_feature($name);
289         }
290         else {
291             delete $^H{$feature{$name}};
292             $^H &= ~ $hint_uni8bit if $name eq 'unicode_strings';
293         }
294     }
295 }
296
297 sub unknown_feature {
298     my $feature = shift;
299     croak(sprintf('Feature "%s" is not supported by Perl %vd',
300             $feature, $^V));
301 }
302
303 sub unknown_feature_bundle {
304     my $feature = shift;
305     croak(sprintf('Feature bundle "%s" is not supported by Perl %vd',
306             $feature, $^V));
307 }
308
309 sub croak {
310     require Carp;
311     Carp::croak(@_);
312 }
313
314 1;