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