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!
13 state => 'feature_state',
14 switch => 'feature_switch',
15 evalbytes => 'feature_evalbytes',
16 postderef => 'feature_postderef',
17 array_base => 'feature_arybase',
18 signatures => 'feature_signatures',
19 current_sub => 'feature___SUB__',
20 refaliasing => 'feature_refaliasing',
21 lexical_subs => 'feature_lexsubs',
22 postderef_qq => 'feature_postderef_qq',
23 unicode_eval => 'feature_unieval',
24 unicode_strings => 'feature_unicode',
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 "all" => [qw(array_base current_sub evalbytes fc lexical_subs postderef postderef_qq refaliasing say signatures state switch unicode_eval unicode_strings)],
32 "default" => [qw(array_base)],
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.9.5"} = $feature_bundle{"5.10"};
48 our $hint_mask = 0x1c000000;
49 our @hint_bundles = qw( default 5.10 5.11 5.15 );
51 # This gets set (for now) in $^H as well as in %^H,
52 # for runtime speed of the uc/lc/ucfirst/lcfirst functions.
53 # See HINT_UNI_8_BIT in perl.h.
54 our $hint_uni8bit = 0x00000800;
57 # - think about versioned features (use feature switch => 2)
61 feature - Perl pragma to enable new features
65 use feature qw(say switch);
67 when (1) { say "\$foo == 1" }
68 when ([2,3]) { say "\$foo == 2 || \$foo == 3" }
69 when (/^a[bc]d$/) { say "\$foo eq 'abd' || \$foo eq 'acd'" }
70 when ($_ > 100) { say "\$foo > 100" }
71 default { say "None of the above" }
74 use feature ':5.10'; # loads all features available in perl 5.10
76 use v5.10; # implicitly loads :5.10 feature bundle
80 It is usually impossible to add new syntax to Perl without breaking
81 some existing programs. This pragma provides a way to minimize that
82 risk. New syntactic constructs, or new semantic meanings to older
83 constructs, can be enabled by C<use feature 'foo'>, and will be parsed
84 only when the appropriate feature pragma is in scope. (Nevertheless, the
85 C<CORE::> prefix provides access to all Perl keywords, regardless of this
90 Like other pragmas (C<use strict>, for example), features have a lexical
91 effect. C<use feature qw(foo)> will only make the feature "foo" available
92 from that point to the end of the enclosing block.
96 say "say is available here";
98 print "But not here.\n";
102 Features can also be turned off by using C<no feature "foo">. This too
106 say "say is available here";
109 print "But not here.\n";
111 say "Yet it is here.";
113 C<no feature> with no features specified will reset to the default group. To
114 disable I<all> features (an unusual request!) use C<no feature ':all'>.
116 =head1 AVAILABLE FEATURES
118 =head2 The 'say' feature
120 C<use feature 'say'> tells the compiler to enable the Perl 6 style
123 See L<perlfunc/say> for details.
125 This feature is available starting with Perl 5.10.
127 =head2 The 'state' feature
129 C<use feature 'state'> tells the compiler to enable C<state>
132 See L<perlsub/"Persistent Private Variables"> for details.
134 This feature is available starting with Perl 5.10.
136 =head2 The 'switch' feature
138 B<WARNING>: Because the L<smartmatch operator|perlop/"Smartmatch Operator"> is
139 experimental, Perl will warn when you use this feature, unless you have
140 explicitly disabled the warning:
142 no warnings "experimental::smartmatch";
144 C<use feature 'switch'> tells the compiler to enable the Perl 6
145 given/when construct.
147 See L<perlsyn/"Switch Statements"> for details.
149 This feature is available starting with Perl 5.10.
151 =head2 The 'unicode_strings' feature
153 C<use feature 'unicode_strings'> tells the compiler to use Unicode rules
154 in all string operations executed within its scope (unless they are also
155 within the scope of either C<use locale> or C<use bytes>). The same applies
156 to all regular expressions compiled within the scope, even if executed outside
157 it. It does not change the internal representation of strings, but only how
158 they are interpreted.
160 C<no feature 'unicode_strings'> tells the compiler to use the traditional
161 Perl rules wherein the native character set rules is used unless it is
162 clear to Perl that Unicode is desired. This can lead to some surprises
163 when the behavior suddenly changes. (See
164 L<perlunicode/The "Unicode Bug"> for details.) For this reason, if you are
165 potentially using Unicode in your program, the
166 C<use feature 'unicode_strings'> subpragma is B<strongly> recommended.
168 This feature is available starting with Perl 5.12; was almost fully
169 implemented in Perl 5.14; and extended in Perl 5.16 to cover C<quotemeta>.
171 =head2 The 'unicode_eval' and 'evalbytes' features
173 Under the C<unicode_eval> feature, Perl's C<eval> function, when passed a
174 string, will evaluate it as a string of characters, ignoring any
175 C<use utf8> declarations. C<use utf8> exists to declare the encoding of
176 the script, which only makes sense for a stream of bytes, not a string of
177 characters. Source filters are forbidden, as they also really only make
178 sense on strings of bytes. Any attempt to activate a source filter will
181 The C<evalbytes> feature enables the C<evalbytes> keyword, which evaluates
182 the argument passed to it as a string of bytes. It dies if the string
183 contains any characters outside the 8-bit range. Source filters work
184 within C<evalbytes>: they apply to the contents of the string being
187 Together, these two features are intended to replace the historical C<eval>
188 function, which has (at least) two bugs in it, that cannot easily be fixed
189 without breaking existing programs:
195 C<eval> behaves differently depending on the internal encoding of the
196 string, sometimes treating its argument as a string of bytes, and sometimes
197 as a string of characters.
201 Source filters activated within C<eval> leak out into whichever I<file>
202 scope is currently being compiled. To give an example with the CPAN module
205 BEGIN { eval "use Semi::Semicolons; # not filtered here " }
208 C<evalbytes> fixes that to work the way one would expect:
210 use feature "evalbytes";
211 BEGIN { evalbytes "use Semi::Semicolons; # filtered " }
216 These two features are available starting with Perl 5.16.
218 =head2 The 'current_sub' feature
220 This provides the C<__SUB__> token that returns a reference to the current
221 subroutine or C<undef> outside of a subroutine.
223 This feature is available starting with Perl 5.16.
225 =head2 The 'array_base' feature
227 This feature supports the legacy C<$[> variable. See L<perlvar/$[> and
228 L<arybase>. It is on by default but disabled under C<use v5.16> (see
229 L</IMPLICIT LOADING>, below).
231 This feature is available under this name starting with Perl 5.16. In
232 previous versions, it was simply on all the time, and this pragma knew
235 =head2 The 'fc' feature
237 C<use feature 'fc'> tells the compiler to enable the C<fc> function,
238 which implements Unicode casefolding.
240 See L<perlfunc/fc> for details.
242 This feature is available from Perl 5.16 onwards.
244 =head2 The 'lexical_subs' feature
246 B<WARNING>: This feature is still experimental and the implementation may
247 change in future versions of Perl. For this reason, Perl will
248 warn when you use the feature, unless you have explicitly disabled the
251 no warnings "experimental::lexical_subs";
253 This enables declaration of subroutines via C<my sub foo>, C<state sub foo>
254 and C<our sub foo> syntax. See L<perlsub/Lexical Subroutines> for details.
256 This feature is available from Perl 5.18 onwards.
258 =head2 The 'postderef' and 'postderef_qq' features
260 B<WARNING>: This feature is still experimental and the implementation may
261 change in future versions of Perl. For this reason, Perl will
262 warn when you use the feature, unless you have explicitly disabled the
265 no warnings "experimental::postderef";
267 The 'postderef' feature allows the use of L<postfix dereference
268 syntax|perlref/Postfix Dereference Syntax>. For example, it will make the
269 following two statements equivalent:
271 my @x = @{ $h->{a} };
274 The 'postderef_qq' feature extends this, for array and scalar dereference, to
275 working inside of double-quotish interpolations.
277 This feature is available from Perl 5.20 onwards.
279 =head2 The 'signatures' feature
281 B<WARNING>: This feature is still experimental and the implementation may
282 change in future versions of Perl. For this reason, Perl will
283 warn when you use the feature, unless you have explicitly disabled the
286 no warnings "experimental::signatures";
288 This enables unpacking of subroutine arguments into lexical variables
291 sub foo ($left, $right) {
292 return $left + $right;
295 See L<perlsub/Signatures> for details.
297 This feature is available from Perl 5.20 onwards.
299 =head2 The 'refaliasing' feature
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
306 no warnings "experimental::refaliasing";
308 This enables aliasing via assignment to references:
310 \$a = \$b; # $a and $b now point to the same scalar
311 \@a = \@b; # to the same array
314 foreach \%hash (@array_of_hash_refs) {
318 See L<perlref/Assigning to References> for details.
320 This feature is available from Perl 5.22 onwards.
322 =head1 FEATURE BUNDLES
324 It's possible to load multiple features together, using
325 a I<feature bundle>. The name of a feature bundle is prefixed with
326 a colon, to distinguish it from an actual feature.
330 The following feature bundles are available:
332 bundle features included
333 --------- -----------------
336 :5.10 say state switch array_base
338 :5.12 say state switch unicode_strings array_base
340 :5.14 say state switch unicode_strings array_base
342 :5.16 say state switch unicode_strings
343 unicode_eval evalbytes current_sub fc
345 :5.18 say state switch unicode_strings
346 unicode_eval evalbytes current_sub fc
348 :5.20 say state switch unicode_strings
349 unicode_eval evalbytes current_sub fc
351 :5.22 say state switch unicode_strings
352 unicode_eval evalbytes current_sub fc
354 The C<:default> bundle represents the feature set that is enabled before
355 any C<use feature> or C<no feature> declaration.
357 Specifying sub-versions such as the C<0> in C<5.14.0> in feature bundles has
358 no effect. Feature bundles are guaranteed to be the same for all sub-versions.
360 use feature ":5.14.0"; # same as ":5.14"
361 use feature ":5.14.1"; # same as ":5.14"
363 =head1 IMPLICIT LOADING
365 Instead of loading feature bundles by name, it is easier to let Perl do
366 implicit loading of a feature bundle for you.
368 There are two ways to load the C<feature> pragma implicitly:
374 By using the C<-E> switch on the Perl command-line instead of C<-e>.
375 That will enable the feature bundle for that version of Perl in the
376 main compilation unit (that is, the one-liner that follows C<-E>).
380 By explicitly requiring a minimum Perl version number for your program, with
381 the C<use VERSION> construct. That is,
390 and so on. Note how the trailing sub-version
391 is automatically stripped from the
394 But to avoid portability warnings (see L<perlfunc/use>), you may prefer:
398 with the same effect.
400 If the required version is older than Perl 5.10, the ":default" feature
401 bundle is automatically loaded instead.
411 croak("No features specified");
420 # A bare C<no feature> should reset to the default bundle
422 $^H &= ~($hint_uni8bit|$hint_mask);
432 my $bundle_number = $^H & $hint_mask;
433 my $features = $bundle_number != $hint_mask
434 && $feature_bundle{$hint_bundles[$bundle_number >> $hint_shift]};
436 # Features are enabled implicitly via bundle hints.
437 # Delete any keys that may be left over from last time.
438 delete @^H{ values(%feature) };
441 $^H{$feature{$_}} = 1;
442 $^H |= $hint_uni8bit if $_ eq 'unicode_strings';
447 if (substr($name, 0, 1) eq ":") {
448 my $v = substr($name, 1);
449 if (!exists $feature_bundle{$v}) {
450 $v =~ s/^([0-9]+)\.([0-9]+).[0-9]+$/$1.$2/;
451 if (!exists $feature_bundle{$v}) {
452 unknown_feature_bundle(substr($name, 1));
455 unshift @_, @{$feature_bundle{$v}};
458 if (!exists $feature{$name}) {
459 unknown_feature($name);
462 $^H{$feature{$name}} = 1;
463 $^H |= $hint_uni8bit if $name eq 'unicode_strings';
465 delete $^H{$feature{$name}};
466 $^H &= ~ $hint_uni8bit if $name eq 'unicode_strings';
471 sub unknown_feature {
473 croak(sprintf('Feature "%s" is not supported by Perl %vd',
477 sub unknown_feature_bundle {
479 croak(sprintf('Feature bundle "%s" is not supported by Perl %vd',