This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Increase $feature::VERSION to 1.32
[perl5.git] / lib / feature.pm
1 # -*- buffer-read-only: t -*-
2 # !!!!!!!   DO NOT EDIT THIS FILE   !!!!!!!
3 # This file is built by regen/feature.pl.
4 # Any changes made here will be lost!
5
6 package feature;
7
8 our $VERSION = '1.32';
9
10 our %feature = (
11     fc              => 'feature_fc',
12     say             => 'feature_say',
13     state           => 'feature_state',
14     switch          => 'feature_switch',
15     evalbytes       => 'feature_evalbytes',
16     array_base      => 'feature_arybase',
17     current_sub     => 'feature___SUB__',
18     lexical_subs    => 'feature_lexsubs',
19     unicode_eval    => 'feature_unieval',
20     unicode_strings => 'feature_unicode',
21 );
22
23 our %feature_bundle = (
24     "5.10"    => [qw(array_base say state switch)],
25     "5.11"    => [qw(array_base say state switch unicode_strings)],
26     "5.15"    => [qw(current_sub evalbytes fc say state switch unicode_eval unicode_strings)],
27     "all"     => [qw(array_base current_sub evalbytes fc lexical_subs say state switch unicode_eval unicode_strings)],
28     "default" => [qw(array_base)],
29 );
30
31 $feature_bundle{"5.12"} = $feature_bundle{"5.11"};
32 $feature_bundle{"5.13"} = $feature_bundle{"5.11"};
33 $feature_bundle{"5.14"} = $feature_bundle{"5.11"};
34 $feature_bundle{"5.16"} = $feature_bundle{"5.15"};
35 $feature_bundle{"5.17"} = $feature_bundle{"5.15"};
36 $feature_bundle{"5.18"} = $feature_bundle{"5.15"};
37 $feature_bundle{"5.9.5"} = $feature_bundle{"5.10"};
38
39 our $hint_shift   = 26;
40 our $hint_mask    = 0x1c000000;
41 our @hint_bundles = qw( default 5.10 5.11 5.15 );
42
43 # This gets set (for now) in $^H as well as in %^H,
44 # for runtime speed of the uc/lc/ucfirst/lcfirst functions.
45 # See HINT_UNI_8_BIT in perl.h.
46 our $hint_uni8bit = 0x00000800;
47
48 # TODO:
49 # - think about versioned features (use feature switch => 2)
50
51 =head1 NAME
52
53 feature - Perl pragma to enable new features
54
55 =head1 SYNOPSIS
56
57     use feature qw(say switch);
58     given ($foo) {
59         when (1)          { say "\$foo == 1" }
60         when ([2,3])      { say "\$foo == 2 || \$foo == 3" }
61         when (/^a[bc]d$/) { say "\$foo eq 'abd' || \$foo eq 'acd'" }
62         when ($_ > 100)   { say "\$foo > 100" }
63         default           { say "None of the above" }
64     }
65
66     use feature ':5.10'; # loads all features available in perl 5.10
67
68     use v5.10;           # implicitly loads :5.10 feature bundle
69
70 =head1 DESCRIPTION
71
72 It is usually impossible to add new syntax to Perl without breaking
73 some existing programs.  This pragma provides a way to minimize that
74 risk. New syntactic constructs, or new semantic meanings to older
75 constructs, can be enabled by C<use feature 'foo'>, and will be parsed
76 only when the appropriate feature pragma is in scope.  (Nevertheless, the
77 C<CORE::> prefix provides access to all Perl keywords, regardless of this
78 pragma.)
79
80 =head2 Lexical effect
81
82 Like other pragmas (C<use strict>, for example), features have a lexical
83 effect.  C<use feature qw(foo)> will only make the feature "foo" available
84 from that point to the end of the enclosing block.
85
86     {
87         use feature 'say';
88         say "say is available here";
89     }
90     print "But not here.\n";
91
92 =head2 C<no feature>
93
94 Features can also be turned off by using C<no feature "foo">.  This too
95 has lexical effect.
96
97     use feature 'say';
98     say "say is available here";
99     {
100         no feature 'say';
101         print "But not here.\n";
102     }
103     say "Yet it is here.";
104
105 C<no feature> with no features specified will reset to the default group.  To
106 disable I<all> features (an unusual request!) use C<no feature ':all'>.
107
108 =head1 AVAILABLE FEATURES
109
110 =head2 The 'say' feature
111
112 C<use feature 'say'> tells the compiler to enable the Perl 6 style
113 C<say> function.
114
115 See L<perlfunc/say> for details.
116
117 This feature is available starting with Perl 5.10.
118
119 =head2 The 'state' feature
120
121 C<use feature 'state'> tells the compiler to enable C<state>
122 variables.
123
124 See L<perlsub/"Persistent Private Variables"> for details.
125
126 This feature is available starting with Perl 5.10.
127
128 =head2 The 'switch' feature
129
130 C<use feature 'switch'> tells the compiler to enable the Perl 6
131 given/when construct.
132
133 See L<perlsyn/"Switch Statements"> for details.
134
135 This feature is available starting with Perl 5.10.
136
137 =head2 The 'unicode_strings' feature
138
139 C<use feature 'unicode_strings'> tells the compiler to use Unicode semantics
140 in all string operations executed within its scope (unless they are also
141 within the scope of either C<use locale> or C<use bytes>).  The same applies
142 to all regular expressions compiled within the scope, even if executed outside
143 it.  It does not change the internal representation of strings, but only how
144 they are interpreted.
145
146 C<no feature 'unicode_strings'> tells the compiler to use the traditional
147 Perl semantics wherein the native character set semantics is used unless it is
148 clear to Perl that Unicode is desired.  This can lead to some surprises
149 when the behavior suddenly changes.  (See
150 L<perlunicode/The "Unicode Bug"> for details.)  For this reason, if you are
151 potentially using Unicode in your program, the
152 C<use feature 'unicode_strings'> subpragma is B<strongly> recommended.
153
154 This feature is available starting with Perl 5.12; was almost fully
155 implemented in Perl 5.14; and extended in Perl 5.16 to cover C<quotemeta>.
156
157 =head2 The 'unicode_eval' and 'evalbytes' features
158
159 Under the C<unicode_eval> feature, Perl's C<eval> function, when passed a
160 string, will evaluate it as a string of characters, ignoring any
161 C<use utf8> declarations.  C<use utf8> exists to declare the encoding of
162 the script, which only makes sense for a stream of bytes, not a string of
163 characters.  Source filters are forbidden, as they also really only make
164 sense on strings of bytes.  Any attempt to activate a source filter will
165 result in an error.
166
167 The C<evalbytes> feature enables the C<evalbytes> keyword, which evaluates
168 the argument passed to it as a string of bytes.  It dies if the string
169 contains any characters outside the 8-bit range.  Source filters work
170 within C<evalbytes>: they apply to the contents of the string being
171 evaluated.
172
173 Together, these two features are intended to replace the historical C<eval>
174 function, which has (at least) two bugs in it, that cannot easily be fixed
175 without breaking existing programs:
176
177 =over
178
179 =item *
180
181 C<eval> behaves differently depending on the internal encoding of the
182 string, sometimes treating its argument as a string of bytes, and sometimes
183 as a string of characters.
184
185 =item *
186
187 Source filters activated within C<eval> leak out into whichever I<file>
188 scope is currently being compiled.  To give an example with the CPAN module
189 L<Semi::Semicolons>:
190
191     BEGIN { eval "use Semi::Semicolons;  # not filtered here " }
192     # filtered here!
193
194 C<evalbytes> fixes that to work the way one would expect:
195
196     use feature "evalbytes";
197     BEGIN { evalbytes "use Semi::Semicolons;  # filtered " }
198     # not filtered
199
200 =back
201
202 These two features are available starting with Perl 5.16.
203
204 =head2 The 'current_sub' feature
205
206 This provides the C<__SUB__> token that returns a reference to the current
207 subroutine or C<undef> outside of a subroutine.
208
209 This feature is available starting with Perl 5.16.
210
211 =head2 The 'array_base' feature
212
213 This feature supports the legacy C<$[> variable.  See L<perlvar/$[> and
214 L<arybase>.  It is on by default but disabled under C<use v5.16> (see
215 L</IMPLICIT LOADING>, below).
216
217 This feature is available under this name starting with Perl 5.16.  In
218 previous versions, it was simply on all the time, and this pragma knew
219 nothing about it.
220
221 =head2 The 'fc' feature
222
223 C<use feature 'fc'> tells the compiler to enable the C<fc> function,
224 which implements Unicode casefolding.
225
226 See L<perlfunc/fc> for details.
227
228 This feature is available from Perl 5.16 onwards.
229
230 =head2 The 'lexical_subs' feature
231
232 B<WARNING>: This feature is still experimental and the implementation may
233 change in future versions of Perl.  For this reason, Perl will
234 warn when you use the feature, unless you have explicitly disabled the
235 warning:
236
237     no warnings "experimental::lexical_subs";
238
239 This enables declaration of subroutines via C<my sub foo>, C<state sub foo>
240 and C<our sub foo> syntax.  See L<perlsub/Lexical Subroutines> for details.
241
242 This feature is available from Perl 5.18 onwards.
243
244 =head1 FEATURE BUNDLES
245
246 It's possible to load multiple features together, using
247 a I<feature bundle>.  The name of a feature bundle is prefixed with
248 a colon, to distinguish it from an actual feature.
249
250   use feature ":5.10";
251
252 The following feature bundles are available:
253
254   bundle    features included
255   --------- -----------------
256   :default  array_base
257
258   :5.10     say state switch array_base
259
260   :5.12     say state switch unicode_strings array_base
261
262   :5.14     say state switch unicode_strings array_base
263
264   :5.16     say state switch unicode_strings
265             unicode_eval evalbytes current_sub fc
266
267   :5.18     say state switch unicode_strings
268             unicode_eval evalbytes current_sub fc
269
270 The C<:default> bundle represents the feature set that is enabled before
271 any C<use feature> or C<no feature> declaration.
272
273 Specifying sub-versions such as the C<0> in C<5.14.0> in feature bundles has
274 no effect.  Feature bundles are guaranteed to be the same for all sub-versions.
275
276   use feature ":5.14.0";    # same as ":5.14"
277   use feature ":5.14.1";    # same as ":5.14"
278
279 =head1 IMPLICIT LOADING
280
281 Instead of loading feature bundles by name, it is easier to let Perl do
282 implicit loading of a feature bundle for you.
283
284 There are two ways to load the C<feature> pragma implicitly:
285
286 =over 4
287
288 =item *
289
290 By using the C<-E> switch on the Perl command-line instead of C<-e>.
291 That will enable the feature bundle for that version of Perl in the
292 main compilation unit (that is, the one-liner that follows C<-E>).
293
294 =item *
295
296 By explicitly requiring a minimum Perl version number for your program, with
297 the C<use VERSION> construct.  That is,
298
299     use v5.10.0;
300
301 will do an implicit
302
303     no feature ':all';
304     use feature ':5.10';
305
306 and so on.  Note how the trailing sub-version
307 is automatically stripped from the
308 version.
309
310 But to avoid portability warnings (see L<perlfunc/use>), you may prefer:
311
312     use 5.010;
313
314 with the same effect.
315
316 If the required version is older than Perl 5.10, the ":default" feature
317 bundle is automatically loaded instead.
318
319 =back
320
321 =cut
322
323 sub import {
324     my $class = shift;
325
326     if (!@_) {
327         croak("No features specified");
328     }
329
330     __common(1, @_);
331 }
332
333 sub unimport {
334     my $class = shift;
335
336     # A bare C<no feature> should reset to the default bundle
337     if (!@_) {
338         $^H &= ~($hint_uni8bit|$hint_mask);
339         return;
340     }
341
342     __common(0, @_);
343 }
344
345
346 sub __common {
347     my $import = shift;
348     my $bundle_number = $^H & $hint_mask;
349     my $features = $bundle_number != $hint_mask
350         && $feature_bundle{$hint_bundles[$bundle_number >> $hint_shift]};
351     if ($features) {
352         # Features are enabled implicitly via bundle hints.
353         # Delete any keys that may be left over from last time.
354         delete @^H{ values(%feature) };
355         $^H |= $hint_mask;
356         for (@$features) {
357             $^H{$feature{$_}} = 1;
358             $^H |= $hint_uni8bit if $_ eq 'unicode_strings';
359         }
360     }
361     while (@_) {
362         my $name = shift;
363         if (substr($name, 0, 1) eq ":") {
364             my $v = substr($name, 1);
365             if (!exists $feature_bundle{$v}) {
366                 $v =~ s/^([0-9]+)\.([0-9]+).[0-9]+$/$1.$2/;
367                 if (!exists $feature_bundle{$v}) {
368                     unknown_feature_bundle(substr($name, 1));
369                 }
370             }
371             unshift @_, @{$feature_bundle{$v}};
372             next;
373         }
374         if (!exists $feature{$name}) {
375             unknown_feature($name);
376         }
377         if ($import) {
378             $^H{$feature{$name}} = 1;
379             $^H |= $hint_uni8bit if $name eq 'unicode_strings';
380         } else {
381             delete $^H{$feature{$name}};
382             $^H &= ~ $hint_uni8bit if $name eq 'unicode_strings';
383         }
384     }
385 }
386
387 sub unknown_feature {
388     my $feature = shift;
389     croak(sprintf('Feature "%s" is not supported by Perl %vd',
390             $feature, $^V));
391 }
392
393 sub unknown_feature_bundle {
394     my $feature = shift;
395     croak(sprintf('Feature bundle "%s" is not supported by Perl %vd',
396             $feature, $^V));
397 }
398
399 sub croak {
400     require Carp;
401     Carp::croak(@_);
402 }
403
404 1;
405
406 # ex: set ro: