prevent warning noise on mingw-64 builds
[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_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_qq' feature extends the applicability of L<postfix
264 dereference syntax|perlref/Postfix Dereference Syntax> so that postfix array
265 and scalar dereference are available in double-quotish interpolations. For
266 example, it makes the following two statements equivalent:
267
268   my $s = "[@{ $h->{a} }]";
269   my $s = "[$h->{a}->@*]";
270
271 This feature is available from Perl 5.20 onwards. In Perl 5.20 and 5.22, it
272 was classed as experimental, and Perl emitted a warning for its
273 usage, except when explicitly disabled:
274
275   no warnings "experimental::postderef";
276
277 As of Perl 5.24, use of this feature no longer triggers a warning, though
278 the C<experimental::postderef> warning category still exists (for
279 compatibility with code that disables it).
280
281 The 'postderef' feature was used in Perl 5.20 and Perl 5.22 to enable
282 postfix dereference syntax outside double-quotish interpolations. In those
283 versions, using it triggered the C<experimental::postderef> warning in the
284 same way as the 'postderef_qq' feature did. As of Perl 5.24, this syntax is
285 not only no longer experimental, but it is enabled for all Perl code,
286 regardless of what feature declarations are in scope.
287
288 =head2 The 'signatures' feature
289
290 B<WARNING>: This feature is still experimental and the implementation may
291 change in future versions of Perl.  For this reason, Perl will
292 warn when you use the feature, unless you have explicitly disabled the
293 warning:
294
295     no warnings "experimental::signatures";
296
297 This enables unpacking of subroutine arguments into lexical variables
298 by syntax such as
299
300     sub foo ($left, $right) {
301         return $left + $right;
302     }
303
304 See L<perlsub/Signatures> for details.
305
306 This feature is available from Perl 5.20 onwards.
307
308 =head2 The 'refaliasing' feature
309
310 B<WARNING>: This feature is still experimental and the implementation may
311 change in future versions of Perl.  For this reason, Perl will
312 warn when you use the feature, unless you have explicitly disabled the
313 warning:
314
315     no warnings "experimental::refaliasing";
316
317 This enables aliasing via assignment to references:
318
319     \$a = \$b; # $a and $b now point to the same scalar
320     \@a = \@b; #                     to the same array
321     \%a = \%b;
322     \&a = \&b;
323     foreach \%hash (@array_of_hash_refs) {
324         ...
325     }
326
327 See L<perlref/Assigning to References> for details.
328
329 This feature is available from Perl 5.22 onwards.
330
331 =head2 The 'bitwise' feature
332
333 B<WARNING>: This feature is still experimental and the implementation may
334 change in future versions of Perl.  For this reason, Perl will
335 warn when you use the feature, unless you have explicitly disabled the
336 warning:
337
338     no warnings "experimental::bitwise";
339
340 This makes the four standard bitwise operators (C<& | ^ ~>) treat their
341 operands consistently as numbers, and introduces four new dotted operators
342 (C<&. |. ^. ~.>) that treat their operands consistently as strings.  The
343 same applies to the assignment variants (C<&= |= ^= &.= |.= ^.=>).
344
345 See L<perlop/Bitwise String Operators> for details.
346
347 This feature is available from Perl 5.22 onwards.
348
349 =head1 FEATURE BUNDLES
350
351 It's possible to load multiple features together, using
352 a I<feature bundle>.  The name of a feature bundle is prefixed with
353 a colon, to distinguish it from an actual feature.
354
355   use feature ":5.10";
356
357 The following feature bundles are available:
358
359   bundle    features included
360   --------- -----------------
361   :default  array_base
362
363   :5.10     say state switch array_base
364
365   :5.12     say state switch unicode_strings array_base
366
367   :5.14     say state switch unicode_strings array_base
368
369   :5.16     say state switch unicode_strings
370             unicode_eval evalbytes current_sub fc
371
372   :5.18     say state switch unicode_strings
373             unicode_eval evalbytes current_sub fc
374
375   :5.20     say state switch unicode_strings
376             unicode_eval evalbytes current_sub fc
377
378   :5.22     say state switch unicode_strings
379             unicode_eval evalbytes current_sub fc
380
381   :5.24     say state switch unicode_strings
382             unicode_eval evalbytes current_sub fc
383             postderef_qq
384
385 The C<:default> bundle represents the feature set that is enabled before
386 any C<use feature> or C<no feature> declaration.
387
388 Specifying sub-versions such as the C<0> in C<5.14.0> in feature bundles has
389 no effect.  Feature bundles are guaranteed to be the same for all sub-versions.
390
391   use feature ":5.14.0";    # same as ":5.14"
392   use feature ":5.14.1";    # same as ":5.14"
393
394 =head1 IMPLICIT LOADING
395
396 Instead of loading feature bundles by name, it is easier to let Perl do
397 implicit loading of a feature bundle for you.
398
399 There are two ways to load the C<feature> pragma implicitly:
400
401 =over 4
402
403 =item *
404
405 By using the C<-E> switch on the Perl command-line instead of C<-e>.
406 That will enable the feature bundle for that version of Perl in the
407 main compilation unit (that is, the one-liner that follows C<-E>).
408
409 =item *
410
411 By explicitly requiring a minimum Perl version number for your program, with
412 the C<use VERSION> construct.  That is,
413
414     use v5.10.0;
415
416 will do an implicit
417
418     no feature ':all';
419     use feature ':5.10';
420
421 and so on.  Note how the trailing sub-version
422 is automatically stripped from the
423 version.
424
425 But to avoid portability warnings (see L<perlfunc/use>), you may prefer:
426
427     use 5.010;
428
429 with the same effect.
430
431 If the required version is older than Perl 5.10, the ":default" feature
432 bundle is automatically loaded instead.
433
434 =back
435
436 =cut
437
438 sub import {
439     shift;
440
441     if (!@_) {
442         croak("No features specified");
443     }
444
445     __common(1, @_);
446 }
447
448 sub unimport {
449     shift;
450
451     # A bare C<no feature> should reset to the default bundle
452     if (!@_) {
453         $^H &= ~($hint_uni8bit|$hint_mask);
454         return;
455     }
456
457     __common(0, @_);
458 }
459
460
461 sub __common {
462     my $import = shift;
463     my $bundle_number = $^H & $hint_mask;
464     my $features = $bundle_number != $hint_mask
465         && $feature_bundle{$hint_bundles[$bundle_number >> $hint_shift]};
466     if ($features) {
467         # Features are enabled implicitly via bundle hints.
468         # Delete any keys that may be left over from last time.
469         delete @^H{ values(%feature) };
470         $^H |= $hint_mask;
471         for (@$features) {
472             $^H{$feature{$_}} = 1;
473             $^H |= $hint_uni8bit if $_ eq 'unicode_strings';
474         }
475     }
476     while (@_) {
477         my $name = shift;
478         if (substr($name, 0, 1) eq ":") {
479             my $v = substr($name, 1);
480             if (!exists $feature_bundle{$v}) {
481                 $v =~ s/^([0-9]+)\.([0-9]+).[0-9]+$/$1.$2/;
482                 if (!exists $feature_bundle{$v}) {
483                     unknown_feature_bundle(substr($name, 1));
484                 }
485             }
486             unshift @_, @{$feature_bundle{$v}};
487             next;
488         }
489         if (!exists $feature{$name}) {
490             unknown_feature($name);
491         }
492         if ($import) {
493             $^H{$feature{$name}} = 1;
494             $^H |= $hint_uni8bit if $name eq 'unicode_strings';
495         } else {
496             delete $^H{$feature{$name}};
497             $^H &= ~ $hint_uni8bit if $name eq 'unicode_strings';
498         }
499     }
500 }
501
502 sub unknown_feature {
503     my $feature = shift;
504     croak(sprintf('Feature "%s" is not supported by Perl %vd',
505             $feature, $^V));
506 }
507
508 sub unknown_feature_bundle {
509     my $feature = shift;
510     croak(sprintf('Feature bundle "%s" is not supported by Perl %vd',
511             $feature, $^V));
512 }
513
514 sub croak {
515     require Carp;
516     Carp::croak(@_);
517 }
518
519 1;
520
521 # ex: set ro: