This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Faster feature checks
[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.56';
9
10 our %feature = (
11     fc              => 'feature_fc',
12     say             => 'feature_say',
13     state           => 'feature_state',
14     switch          => 'feature_switch',
15     bitwise         => 'feature_bitwise',
16     evalbytes       => 'feature_evalbytes',
17     signatures      => 'feature_signatures',
18     current_sub     => 'feature___SUB__',
19     refaliasing     => 'feature_refaliasing',
20     postderef_qq    => 'feature_postderef_qq',
21     unicode_eval    => 'feature_unieval',
22     declared_refs   => 'feature_myref',
23     unicode_strings => 'feature_unicode',
24 );
25
26
27 my %feature_bits = (
28     bitwise         => 0x0001,
29     current_sub     => 0x0002,
30     declared_refs   => 0x0004,
31     evalbytes       => 0x0008,
32     fc              => 0x0010,
33     postderef_qq    => 0x0020,
34     refaliasing     => 0x0040,
35     say             => 0x0080,
36     signatures      => 0x0100,
37     state           => 0x0200,
38     switch          => 0x0400,
39     unicode_eval    => 0x0800,
40     unicode_strings => 0x1000,
41 );
42
43 our %feature_bundle = (
44     "5.10"    => [qw(say state switch)],
45     "5.11"    => [qw(say state switch unicode_strings)],
46     "5.15"    => [qw(current_sub evalbytes fc say state switch unicode_eval unicode_strings)],
47     "5.23"    => [qw(current_sub evalbytes fc postderef_qq say state switch unicode_eval unicode_strings)],
48     "5.27"    => [qw(bitwise current_sub evalbytes fc postderef_qq say state switch unicode_eval unicode_strings)],
49     "all"     => [qw(bitwise current_sub declared_refs evalbytes fc postderef_qq refaliasing say signatures state switch unicode_eval unicode_strings)],
50     "default" => [qw()],
51 );
52
53 $feature_bundle{"5.12"} = $feature_bundle{"5.11"};
54 $feature_bundle{"5.13"} = $feature_bundle{"5.11"};
55 $feature_bundle{"5.14"} = $feature_bundle{"5.11"};
56 $feature_bundle{"5.16"} = $feature_bundle{"5.15"};
57 $feature_bundle{"5.17"} = $feature_bundle{"5.15"};
58 $feature_bundle{"5.18"} = $feature_bundle{"5.15"};
59 $feature_bundle{"5.19"} = $feature_bundle{"5.15"};
60 $feature_bundle{"5.20"} = $feature_bundle{"5.15"};
61 $feature_bundle{"5.21"} = $feature_bundle{"5.15"};
62 $feature_bundle{"5.22"} = $feature_bundle{"5.15"};
63 $feature_bundle{"5.24"} = $feature_bundle{"5.23"};
64 $feature_bundle{"5.25"} = $feature_bundle{"5.23"};
65 $feature_bundle{"5.26"} = $feature_bundle{"5.23"};
66 $feature_bundle{"5.28"} = $feature_bundle{"5.27"};
67 $feature_bundle{"5.29"} = $feature_bundle{"5.27"};
68 $feature_bundle{"5.30"} = $feature_bundle{"5.27"};
69 $feature_bundle{"5.31"} = $feature_bundle{"5.27"};
70 $feature_bundle{"5.32"} = $feature_bundle{"5.27"};
71 $feature_bundle{"5.9.5"} = $feature_bundle{"5.10"};
72 my %noops = (
73     postderef => 1,
74     lexical_subs => 1,
75 );
76 my %removed = (
77     array_base => 1,
78 );
79
80 our $hint_shift   = 26;
81 our $hint_mask    = 0x1c000000;
82 our @hint_bundles = qw( default 5.10 5.11 5.15 5.23 5.27 );
83
84 # This gets set (for now) in $^H as well as in %^H,
85 # for runtime speed of the uc/lc/ucfirst/lcfirst functions.
86 # See HINT_UNI_8_BIT in perl.h.
87 our $hint_uni8bit = 0x00000800;
88
89 # TODO:
90 # - think about versioned features (use feature switch => 2)
91
92 =head1 NAME
93
94 feature - Perl pragma to enable new features
95
96 =head1 SYNOPSIS
97
98     use feature qw(say switch);
99     given ($foo) {
100         when (1)          { say "\$foo == 1" }
101         when ([2,3])      { say "\$foo == 2 || \$foo == 3" }
102         when (/^a[bc]d$/) { say "\$foo eq 'abd' || \$foo eq 'acd'" }
103         when ($_ > 100)   { say "\$foo > 100" }
104         default           { say "None of the above" }
105     }
106
107     use feature ':5.10'; # loads all features available in perl 5.10
108
109     use v5.10;           # implicitly loads :5.10 feature bundle
110
111 =head1 DESCRIPTION
112
113 It is usually impossible to add new syntax to Perl without breaking
114 some existing programs.  This pragma provides a way to minimize that
115 risk. New syntactic constructs, or new semantic meanings to older
116 constructs, can be enabled by C<use feature 'foo'>, and will be parsed
117 only when the appropriate feature pragma is in scope.  (Nevertheless, the
118 C<CORE::> prefix provides access to all Perl keywords, regardless of this
119 pragma.)
120
121 =head2 Lexical effect
122
123 Like other pragmas (C<use strict>, for example), features have a lexical
124 effect.  C<use feature qw(foo)> will only make the feature "foo" available
125 from that point to the end of the enclosing block.
126
127     {
128         use feature 'say';
129         say "say is available here";
130     }
131     print "But not here.\n";
132
133 =head2 C<no feature>
134
135 Features can also be turned off by using C<no feature "foo">.  This too
136 has lexical effect.
137
138     use feature 'say';
139     say "say is available here";
140     {
141         no feature 'say';
142         print "But not here.\n";
143     }
144     say "Yet it is here.";
145
146 C<no feature> with no features specified will reset to the default group.  To
147 disable I<all> features (an unusual request!) use C<no feature ':all'>.
148
149 =head1 AVAILABLE FEATURES
150
151 =head2 The 'say' feature
152
153 C<use feature 'say'> tells the compiler to enable the Perl 6 style
154 C<say> function.
155
156 See L<perlfunc/say> for details.
157
158 This feature is available starting with Perl 5.10.
159
160 =head2 The 'state' feature
161
162 C<use feature 'state'> tells the compiler to enable C<state>
163 variables.
164
165 See L<perlsub/"Persistent Private Variables"> for details.
166
167 This feature is available starting with Perl 5.10.
168
169 =head2 The 'switch' feature
170
171 B<WARNING>: Because the L<smartmatch operator|perlop/"Smartmatch Operator"> is
172 experimental, Perl will warn when you use this feature, unless you have
173 explicitly disabled the warning:
174
175     no warnings "experimental::smartmatch";
176
177 C<use feature 'switch'> tells the compiler to enable the Perl 6
178 given/when construct.
179
180 See L<perlsyn/"Switch Statements"> for details.
181
182 This feature is available starting with Perl 5.10.
183
184 =head2 The 'unicode_strings' feature
185
186 C<use feature 'unicode_strings'> tells the compiler to use Unicode rules
187 in all string operations executed within its scope (unless they are also
188 within the scope of either C<use locale> or C<use bytes>).  The same applies
189 to all regular expressions compiled within the scope, even if executed outside
190 it.  It does not change the internal representation of strings, but only how
191 they are interpreted.
192
193 C<no feature 'unicode_strings'> tells the compiler to use the traditional
194 Perl rules wherein the native character set rules is used unless it is
195 clear to Perl that Unicode is desired.  This can lead to some surprises
196 when the behavior suddenly changes.  (See
197 L<perlunicode/The "Unicode Bug"> for details.)  For this reason, if you are
198 potentially using Unicode in your program, the
199 C<use feature 'unicode_strings'> subpragma is B<strongly> recommended.
200
201 This feature is available starting with Perl 5.12; was almost fully
202 implemented in Perl 5.14; and extended in Perl 5.16 to cover C<quotemeta>;
203 was extended further in Perl 5.26 to cover L<the range
204 operator|perlop/Range Operators>; and was extended again in Perl 5.28 to
205 cover L<special-cased whitespace splitting|perlfunc/split>.
206
207 =head2 The 'unicode_eval' and 'evalbytes' features
208
209 Together, these two features are intended to replace the legacy string
210 C<eval> function, which behaves problematically in some instances.  They are
211 available starting with Perl 5.16, and are enabled by default by a
212 S<C<use 5.16>> or higher declaration.
213
214 C<unicode_eval> changes the behavior of plain string C<eval> to work more
215 consistently, especially in the Unicode world.  Certain (mis)behaviors
216 couldn't be changed without breaking some things that had come to rely on
217 them, so the feature can be enabled and disabled.  Details are at
218 L<perlfunc/Under the "unicode_eval" feature>.
219
220 C<evalbytes> is like string C<eval>, but operating on a byte stream that is
221 not UTF-8 encoded.  Details are at L<perlfunc/evalbytes EXPR>.  Without a
222 S<C<use feature 'evalbytes'>> nor a S<C<use v5.16>> (or higher) declaration in
223 the current scope, you can still access it by instead writing
224 C<CORE::evalbytes>.
225
226 =head2 The 'current_sub' feature
227
228 This provides the C<__SUB__> token that returns a reference to the current
229 subroutine or C<undef> outside of a subroutine.
230
231 This feature is available starting with Perl 5.16.
232
233 =head2 The 'array_base' feature
234
235 This feature supported the legacy C<$[> variable.  See L<perlvar/$[>.
236 It was on by default but disabled under C<use v5.16> (see
237 L</IMPLICIT LOADING>, below) and unavailable since perl 5.30.
238
239 This feature is available under this name starting with Perl 5.16.  In
240 previous versions, it was simply on all the time, and this pragma knew
241 nothing about it.
242
243 =head2 The 'fc' feature
244
245 C<use feature 'fc'> tells the compiler to enable the C<fc> function,
246 which implements Unicode casefolding.
247
248 See L<perlfunc/fc> for details.
249
250 This feature is available from Perl 5.16 onwards.
251
252 =head2 The 'lexical_subs' feature
253
254 In Perl versions prior to 5.26, this feature enabled
255 declaration of subroutines via C<my sub foo>, C<state sub foo>
256 and C<our sub foo> syntax.  See L<perlsub/Lexical Subroutines> for details.
257
258 This feature is available from Perl 5.18 onwards.  From Perl 5.18 to 5.24,
259 it was classed as experimental, and Perl emitted a warning for its
260 usage, except when explicitly disabled:
261
262   no warnings "experimental::lexical_subs";
263
264 As of Perl 5.26, use of this feature no longer triggers a warning, though
265 the C<experimental::lexical_subs> warning category still exists (for
266 compatibility with code that disables it).  In addition, this syntax is
267 not only no longer experimental, but it is enabled for all Perl code,
268 regardless of what feature declarations are in scope.
269
270 =head2 The 'postderef' and 'postderef_qq' features
271
272 The 'postderef_qq' feature extends the applicability of L<postfix
273 dereference syntax|perlref/Postfix Dereference Syntax> so that postfix array
274 and scalar dereference are available in double-quotish interpolations. For
275 example, it makes the following two statements equivalent:
276
277   my $s = "[@{ $h->{a} }]";
278   my $s = "[$h->{a}->@*]";
279
280 This feature is available from Perl 5.20 onwards. In Perl 5.20 and 5.22, it
281 was classed as experimental, and Perl emitted a warning for its
282 usage, except when explicitly disabled:
283
284   no warnings "experimental::postderef";
285
286 As of Perl 5.24, use of this feature no longer triggers a warning, though
287 the C<experimental::postderef> warning category still exists (for
288 compatibility with code that disables it).
289
290 The 'postderef' feature was used in Perl 5.20 and Perl 5.22 to enable
291 postfix dereference syntax outside double-quotish interpolations. In those
292 versions, using it triggered the C<experimental::postderef> warning in the
293 same way as the 'postderef_qq' feature did. As of Perl 5.24, this syntax is
294 not only no longer experimental, but it is enabled for all Perl code,
295 regardless of what feature declarations are in scope.
296
297 =head2 The 'signatures' feature
298
299 B<WARNING>: This feature is still experimental and the implementation may
300 change in future versions of Perl.  For this reason, Perl will
301 warn when you use the feature, unless you have explicitly disabled the
302 warning:
303
304     no warnings "experimental::signatures";
305
306 This enables unpacking of subroutine arguments into lexical variables
307 by syntax such as
308
309     sub foo ($left, $right) {
310         return $left + $right;
311     }
312
313 See L<perlsub/Signatures> for details.
314
315 This feature is available from Perl 5.20 onwards.
316
317 =head2 The 'refaliasing' feature
318
319 B<WARNING>: This feature is still experimental and the implementation may
320 change in future versions of Perl.  For this reason, Perl will
321 warn when you use the feature, unless you have explicitly disabled the
322 warning:
323
324     no warnings "experimental::refaliasing";
325
326 This enables aliasing via assignment to references:
327
328     \$a = \$b; # $a and $b now point to the same scalar
329     \@a = \@b; #                     to the same array
330     \%a = \%b;
331     \&a = \&b;
332     foreach \%hash (@array_of_hash_refs) {
333         ...
334     }
335
336 See L<perlref/Assigning to References> for details.
337
338 This feature is available from Perl 5.22 onwards.
339
340 =head2 The 'bitwise' feature
341
342 This makes the four standard bitwise operators (C<& | ^ ~>) treat their
343 operands consistently as numbers, and introduces four new dotted operators
344 (C<&. |. ^. ~.>) that treat their operands consistently as strings.  The
345 same applies to the assignment variants (C<&= |= ^= &.= |.= ^.=>).
346
347 See L<perlop/Bitwise String Operators> for details.
348
349 This feature is available from Perl 5.22 onwards.  Starting in Perl 5.28,
350 C<use v5.28> will enable the feature.  Before 5.28, it was still
351 experimental and would emit a warning in the "experimental::bitwise"
352 category.
353
354 =head2 The 'declared_refs' feature
355
356 B<WARNING>: This feature is still experimental and the implementation may
357 change in future versions of Perl.  For this reason, Perl will
358 warn when you use the feature, unless you have explicitly disabled the
359 warning:
360
361     no warnings "experimental::declared_refs";
362
363 This allows a reference to a variable to be declared with C<my>, C<state>,
364 our C<our>, or localized with C<local>.  It is intended mainly for use in
365 conjunction with the "refaliasing" feature.  See L<perlref/Declaring a
366 Reference to a Variable> for examples.
367
368 This feature is available from Perl 5.26 onwards.
369
370 =head1 FEATURE BUNDLES
371
372 It's possible to load multiple features together, using
373 a I<feature bundle>.  The name of a feature bundle is prefixed with
374 a colon, to distinguish it from an actual feature.
375
376   use feature ":5.10";
377
378 The following feature bundles are available:
379
380   bundle    features included
381   --------- -----------------
382   :default
383
384   :5.10     say state switch
385
386   :5.12     say state switch unicode_strings
387
388   :5.14     say state switch unicode_strings
389
390   :5.16     say state switch unicode_strings
391             unicode_eval evalbytes current_sub fc
392
393   :5.18     say state switch unicode_strings
394             unicode_eval evalbytes current_sub fc
395
396   :5.20     say state switch unicode_strings
397             unicode_eval evalbytes current_sub fc
398
399   :5.22     say state switch unicode_strings
400             unicode_eval evalbytes current_sub fc
401
402   :5.24     say state switch unicode_strings
403             unicode_eval evalbytes current_sub fc
404             postderef_qq
405
406   :5.26     say state switch unicode_strings
407             unicode_eval evalbytes current_sub fc
408             postderef_qq
409
410   :5.28     say state switch unicode_strings
411             unicode_eval evalbytes current_sub fc
412             postderef_qq bitwise
413
414   :5.30     say state switch unicode_strings
415             unicode_eval evalbytes current_sub fc
416             postderef_qq bitwise
417
418   :5.32     say state switch unicode_strings
419             unicode_eval evalbytes current_sub fc
420             postderef_qq bitwise
421
422 The C<:default> bundle represents the feature set that is enabled before
423 any C<use feature> or C<no feature> declaration.
424
425 Specifying sub-versions such as the C<0> in C<5.14.0> in feature bundles has
426 no effect.  Feature bundles are guaranteed to be the same for all sub-versions.
427
428   use feature ":5.14.0";    # same as ":5.14"
429   use feature ":5.14.1";    # same as ":5.14"
430
431 =head1 IMPLICIT LOADING
432
433 Instead of loading feature bundles by name, it is easier to let Perl do
434 implicit loading of a feature bundle for you.
435
436 There are two ways to load the C<feature> pragma implicitly:
437
438 =over 4
439
440 =item *
441
442 By using the C<-E> switch on the Perl command-line instead of C<-e>.
443 That will enable the feature bundle for that version of Perl in the
444 main compilation unit (that is, the one-liner that follows C<-E>).
445
446 =item *
447
448 By explicitly requiring a minimum Perl version number for your program, with
449 the C<use VERSION> construct.  That is,
450
451     use v5.10.0;
452
453 will do an implicit
454
455     no feature ':all';
456     use feature ':5.10';
457
458 and so on.  Note how the trailing sub-version
459 is automatically stripped from the
460 version.
461
462 But to avoid portability warnings (see L<perlfunc/use>), you may prefer:
463
464     use 5.010;
465
466 with the same effect.
467
468 If the required version is older than Perl 5.10, the ":default" feature
469 bundle is automatically loaded instead.
470
471 Unlike C<use feature ":5.12">, saying C<use v5.12> (or any higher version)
472 also does the equivalent of C<use strict>; see L<perlfunc/use> for details.
473
474 =back
475
476 =cut
477
478 sub import {
479     shift;
480
481     if (!@_) {
482         croak("No features specified");
483     }
484
485     __common(1, @_);
486 }
487
488 sub unimport {
489     shift;
490
491     # A bare C<no feature> should reset to the default bundle
492     if (!@_) {
493         $^H &= ~($hint_uni8bit|$hint_mask);
494         return;
495     }
496
497     __common(0, @_);
498 }
499
500
501 sub __common {
502     my $import = shift;
503     my $bundle_number = $^H & $hint_mask;
504     my $features = $bundle_number != $hint_mask
505       && $feature_bundle{$hint_bundles[$bundle_number >> $hint_shift]};
506     my $bits = ${^FEATURE_BITS};
507     if ($features) {
508         # Features are enabled implicitly via bundle hints.
509         # Delete any keys that may be left over from last time.
510         delete @^H{ values(%feature) };
511         $bits = 0;
512         $^H |= $hint_mask;
513         for (@$features) {
514             $^H{$feature{$_}} = 1;
515             $bits |= $feature_bits{$_};
516             $^H |= $hint_uni8bit if $_ eq 'unicode_strings';
517         }
518     }
519     while (@_) {
520         my $name = shift;
521         if (substr($name, 0, 1) eq ":") {
522             my $v = substr($name, 1);
523             if (!exists $feature_bundle{$v}) {
524                 $v =~ s/^([0-9]+)\.([0-9]+).[0-9]+$/$1.$2/;
525                 if (!exists $feature_bundle{$v}) {
526                     unknown_feature_bundle(substr($name, 1));
527                 }
528             }
529             unshift @_, @{$feature_bundle{$v}};
530             next;
531         }
532         if (!exists $feature{$name}) {
533             if (exists $noops{$name}) {
534                 next;
535             }
536             if (!$import && exists $removed{$name}) {
537                 next;
538             }
539             unknown_feature($name);
540         }
541         if ($import) {
542             $^H{$feature{$name}} = 1;
543             $bits |= $feature_bits{$name};
544             $^H |= $hint_uni8bit if $name eq 'unicode_strings';
545         } else {
546             delete $^H{$feature{$name}};
547             $bits &= ~$feature_bits{$name};
548             $^H &= ~ $hint_uni8bit if $name eq 'unicode_strings';
549         }
550     }
551     ${^FEATURE_BITS} = $bits;
552 }
553
554 sub unknown_feature {
555     my $feature = shift;
556     croak(sprintf('Feature "%s" is not supported by Perl %vd',
557             $feature, $^V));
558 }
559
560 sub unknown_feature_bundle {
561     my $feature = shift;
562     croak(sprintf('Feature bundle "%s" is not supported by Perl %vd',
563             $feature, $^V));
564 }
565
566 sub croak {
567     require Carp;
568     Carp::croak(@_);
569 }
570
571 1;
572
573 # ex: set ro: