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