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