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