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 lexical_subs => 'feature_lexsubs',
21 postderef_qq => 'feature_postderef_qq',
22 unicode_eval => 'feature_unieval',
23 unicode_strings => 'feature_unicode',
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 "all" => [qw(array_base current_sub evalbytes fc lexical_subs postderef postderef_qq say signatures state switch unicode_eval unicode_strings)],
31 "default" => [qw(array_base)],
34 $feature_bundle{"5.12"} = $feature_bundle{"5.11"};
35 $feature_bundle{"5.13"} = $feature_bundle{"5.11"};
36 $feature_bundle{"5.14"} = $feature_bundle{"5.11"};
37 $feature_bundle{"5.16"} = $feature_bundle{"5.15"};
38 $feature_bundle{"5.17"} = $feature_bundle{"5.15"};
39 $feature_bundle{"5.18"} = $feature_bundle{"5.15"};
40 $feature_bundle{"5.19"} = $feature_bundle{"5.15"};
41 $feature_bundle{"5.20"} = $feature_bundle{"5.15"};
42 $feature_bundle{"5.21"} = $feature_bundle{"5.15"};
43 $feature_bundle{"5.22"} = $feature_bundle{"5.15"};
44 $feature_bundle{"5.9.5"} = $feature_bundle{"5.10"};
47 our $hint_mask = 0x1c000000;
48 our @hint_bundles = qw( default 5.10 5.11 5.15 );
50 # This gets set (for now) in $^H as well as in %^H,
51 # for runtime speed of the uc/lc/ucfirst/lcfirst functions.
52 # See HINT_UNI_8_BIT in perl.h.
53 our $hint_uni8bit = 0x00000800;
56 # - think about versioned features (use feature switch => 2)
60 feature - Perl pragma to enable new features
64 use feature qw(say switch);
66 when (1) { say "\$foo == 1" }
67 when ([2,3]) { say "\$foo == 2 || \$foo == 3" }
68 when (/^a[bc]d$/) { say "\$foo eq 'abd' || \$foo eq 'acd'" }
69 when ($_ > 100) { say "\$foo > 100" }
70 default { say "None of the above" }
73 use feature ':5.10'; # loads all features available in perl 5.10
75 use v5.10; # implicitly loads :5.10 feature bundle
79 It is usually impossible to add new syntax to Perl without breaking
80 some existing programs. This pragma provides a way to minimize that
81 risk. New syntactic constructs, or new semantic meanings to older
82 constructs, can be enabled by C<use feature 'foo'>, and will be parsed
83 only when the appropriate feature pragma is in scope. (Nevertheless, the
84 C<CORE::> prefix provides access to all Perl keywords, regardless of this
89 Like other pragmas (C<use strict>, for example), features have a lexical
90 effect. C<use feature qw(foo)> will only make the feature "foo" available
91 from that point to the end of the enclosing block.
95 say "say is available here";
97 print "But not here.\n";
101 Features can also be turned off by using C<no feature "foo">. This too
105 say "say is available here";
108 print "But not here.\n";
110 say "Yet it is here.";
112 C<no feature> with no features specified will reset to the default group. To
113 disable I<all> features (an unusual request!) use C<no feature ':all'>.
115 =head1 AVAILABLE FEATURES
117 =head2 The 'say' feature
119 C<use feature 'say'> tells the compiler to enable the Perl 6 style
122 See L<perlfunc/say> for details.
124 This feature is available starting with Perl 5.10.
126 =head2 The 'state' feature
128 C<use feature 'state'> tells the compiler to enable C<state>
131 See L<perlsub/"Persistent Private Variables"> for details.
133 This feature is available starting with Perl 5.10.
135 =head2 The 'switch' feature
137 C<use feature 'switch'> tells the compiler to enable the Perl 6
138 given/when construct.
140 See L<perlsyn/"Switch Statements"> for details.
142 This feature is available starting with Perl 5.10.
144 =head2 The 'unicode_strings' feature
146 C<use feature 'unicode_strings'> tells the compiler to use Unicode rules
147 in all string operations executed within its scope (unless they are also
148 within the scope of either C<use locale> or C<use bytes>). The same applies
149 to all regular expressions compiled within the scope, even if executed outside
150 it. It does not change the internal representation of strings, but only how
151 they are interpreted.
153 C<no feature 'unicode_strings'> tells the compiler to use the traditional
154 Perl rules wherein the native character set rules is used unless it is
155 clear to Perl that Unicode is desired. This can lead to some surprises
156 when the behavior suddenly changes. (See
157 L<perlunicode/The "Unicode Bug"> for details.) For this reason, if you are
158 potentially using Unicode in your program, the
159 C<use feature 'unicode_strings'> subpragma is B<strongly> recommended.
161 This feature is available starting with Perl 5.12; was almost fully
162 implemented in Perl 5.14; and extended in Perl 5.16 to cover C<quotemeta>.
164 =head2 The 'unicode_eval' and 'evalbytes' features
166 Under the C<unicode_eval> feature, Perl's C<eval> function, when passed a
167 string, will evaluate it as a string of characters, ignoring any
168 C<use utf8> declarations. C<use utf8> exists to declare the encoding of
169 the script, which only makes sense for a stream of bytes, not a string of
170 characters. Source filters are forbidden, as they also really only make
171 sense on strings of bytes. Any attempt to activate a source filter will
174 The C<evalbytes> feature enables the C<evalbytes> keyword, which evaluates
175 the argument passed to it as a string of bytes. It dies if the string
176 contains any characters outside the 8-bit range. Source filters work
177 within C<evalbytes>: they apply to the contents of the string being
180 Together, these two features are intended to replace the historical C<eval>
181 function, which has (at least) two bugs in it, that cannot easily be fixed
182 without breaking existing programs:
188 C<eval> behaves differently depending on the internal encoding of the
189 string, sometimes treating its argument as a string of bytes, and sometimes
190 as a string of characters.
194 Source filters activated within C<eval> leak out into whichever I<file>
195 scope is currently being compiled. To give an example with the CPAN module
198 BEGIN { eval "use Semi::Semicolons; # not filtered here " }
201 C<evalbytes> fixes that to work the way one would expect:
203 use feature "evalbytes";
204 BEGIN { evalbytes "use Semi::Semicolons; # filtered " }
209 These two features are available starting with Perl 5.16.
211 =head2 The 'current_sub' feature
213 This provides the C<__SUB__> token that returns a reference to the current
214 subroutine or C<undef> outside of a subroutine.
216 This feature is available starting with Perl 5.16.
218 =head2 The 'array_base' feature
220 This feature supports the legacy C<$[> variable. See L<perlvar/$[> and
221 L<arybase>. It is on by default but disabled under C<use v5.16> (see
222 L</IMPLICIT LOADING>, below).
224 This feature is available under this name starting with Perl 5.16. In
225 previous versions, it was simply on all the time, and this pragma knew
228 =head2 The 'fc' feature
230 C<use feature 'fc'> tells the compiler to enable the C<fc> function,
231 which implements Unicode casefolding.
233 See L<perlfunc/fc> for details.
235 This feature is available from Perl 5.16 onwards.
237 =head2 The 'lexical_subs' feature
239 B<WARNING>: This feature is still experimental and the implementation may
240 change in future versions of Perl. For this reason, Perl will
241 warn when you use the feature, unless you have explicitly disabled the
244 no warnings "experimental::lexical_subs";
246 This enables declaration of subroutines via C<my sub foo>, C<state sub foo>
247 and C<our sub foo> syntax. See L<perlsub/Lexical Subroutines> for details.
249 This feature is available from Perl 5.18 onwards.
251 =head2 The 'signatures' feature
253 B<WARNING>: This feature is still experimental and the implementation may
254 change in future versions of Perl. For this reason, Perl will
255 warn when you use the feature, unless you have explicitly disabled the
258 no warnings "experimental::signatures";
260 This enables unpacking of subroutine arguments into lexical variables
263 sub foo ($left, $right) {
264 return $left + $right;
267 See L<perlsub/Signatures> for details.
269 This feature is available from Perl 5.20 onwards.
271 =head1 FEATURE BUNDLES
273 It's possible to load multiple features together, using
274 a I<feature bundle>. The name of a feature bundle is prefixed with
275 a colon, to distinguish it from an actual feature.
279 The following feature bundles are available:
281 bundle features included
282 --------- -----------------
285 :5.10 say state switch array_base
287 :5.12 say state switch unicode_strings array_base
289 :5.14 say state switch unicode_strings array_base
291 :5.16 say state switch unicode_strings
292 unicode_eval evalbytes current_sub fc
294 :5.18 say state switch unicode_strings
295 unicode_eval evalbytes current_sub fc
297 :5.20 say state switch unicode_strings
298 unicode_eval evalbytes current_sub fc
300 :5.22 say state switch unicode_strings
301 unicode_eval evalbytes current_sub fc
303 The C<:default> bundle represents the feature set that is enabled before
304 any C<use feature> or C<no feature> declaration.
306 Specifying sub-versions such as the C<0> in C<5.14.0> in feature bundles has
307 no effect. Feature bundles are guaranteed to be the same for all sub-versions.
309 use feature ":5.14.0"; # same as ":5.14"
310 use feature ":5.14.1"; # same as ":5.14"
312 =head1 IMPLICIT LOADING
314 Instead of loading feature bundles by name, it is easier to let Perl do
315 implicit loading of a feature bundle for you.
317 There are two ways to load the C<feature> pragma implicitly:
323 By using the C<-E> switch on the Perl command-line instead of C<-e>.
324 That will enable the feature bundle for that version of Perl in the
325 main compilation unit (that is, the one-liner that follows C<-E>).
329 By explicitly requiring a minimum Perl version number for your program, with
330 the C<use VERSION> construct. That is,
339 and so on. Note how the trailing sub-version
340 is automatically stripped from the
343 But to avoid portability warnings (see L<perlfunc/use>), you may prefer:
347 with the same effect.
349 If the required version is older than Perl 5.10, the ":default" feature
350 bundle is automatically loaded instead.
360 croak("No features specified");
369 # A bare C<no feature> should reset to the default bundle
371 $^H &= ~($hint_uni8bit|$hint_mask);
381 my $bundle_number = $^H & $hint_mask;
382 my $features = $bundle_number != $hint_mask
383 && $feature_bundle{$hint_bundles[$bundle_number >> $hint_shift]};
385 # Features are enabled implicitly via bundle hints.
386 # Delete any keys that may be left over from last time.
387 delete @^H{ values(%feature) };
390 $^H{$feature{$_}} = 1;
391 $^H |= $hint_uni8bit if $_ eq 'unicode_strings';
396 if (substr($name, 0, 1) eq ":") {
397 my $v = substr($name, 1);
398 if (!exists $feature_bundle{$v}) {
399 $v =~ s/^([0-9]+)\.([0-9]+).[0-9]+$/$1.$2/;
400 if (!exists $feature_bundle{$v}) {
401 unknown_feature_bundle(substr($name, 1));
404 unshift @_, @{$feature_bundle{$v}};
407 if (!exists $feature{$name}) {
408 unknown_feature($name);
411 $^H{$feature{$name}} = 1;
412 $^H |= $hint_uni8bit if $name eq 'unicode_strings';
414 delete $^H{$feature{$name}};
415 $^H &= ~ $hint_uni8bit if $name eq 'unicode_strings';
420 sub unknown_feature {
422 croak(sprintf('Feature "%s" is not supported by Perl %vd',
426 sub unknown_feature_bundle {
428 croak(sprintf('Feature bundle "%s" is not supported by Perl %vd',