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 array_base => 'feature_arybase',
17 current_sub => 'feature___SUB__',
18 lexical_subs => 'feature_lexsubs',
19 unicode_eval => 'feature_unieval',
20 unicode_strings => 'feature_unicode',
23 our %feature_bundle = (
24 "5.10" => [qw(array_base say state switch)],
25 "5.11" => [qw(array_base say state switch unicode_strings)],
26 "5.15" => [qw(current_sub evalbytes fc say state switch unicode_eval unicode_strings)],
27 "all" => [qw(array_base current_sub evalbytes fc lexical_subs say state switch unicode_eval unicode_strings)],
28 "default" => [qw(array_base)],
31 $feature_bundle{"5.12"} = $feature_bundle{"5.11"};
32 $feature_bundle{"5.13"} = $feature_bundle{"5.11"};
33 $feature_bundle{"5.14"} = $feature_bundle{"5.11"};
34 $feature_bundle{"5.16"} = $feature_bundle{"5.15"};
35 $feature_bundle{"5.17"} = $feature_bundle{"5.15"};
36 $feature_bundle{"5.18"} = $feature_bundle{"5.15"};
37 $feature_bundle{"5.9.5"} = $feature_bundle{"5.10"};
43 our $hint_mask = 0x1c000000;
44 our @hint_bundles = qw( default 5.10 5.11 5.15 );
46 # This gets set (for now) in $^H as well as in %^H,
47 # for runtime speed of the uc/lc/ucfirst/lcfirst functions.
48 # See HINT_UNI_8_BIT in perl.h.
49 our $hint_uni8bit = 0x00000800;
52 # - think about versioned features (use feature switch => 2)
56 feature - Perl pragma to enable new features
60 use feature qw(say switch);
62 when (1) { say "\$foo == 1" }
63 when ([2,3]) { say "\$foo == 2 || \$foo == 3" }
64 when (/^a[bc]d$/) { say "\$foo eq 'abd' || \$foo eq 'acd'" }
65 when ($_ > 100) { say "\$foo > 100" }
66 default { say "None of the above" }
69 use feature ':5.10'; # loads all features available in perl 5.10
71 use v5.10; # implicitly loads :5.10 feature bundle
75 It is usually impossible to add new syntax to Perl without breaking
76 some existing programs. This pragma provides a way to minimize that
77 risk. New syntactic constructs, or new semantic meanings to older
78 constructs, can be enabled by C<use feature 'foo'>, and will be parsed
79 only when the appropriate feature pragma is in scope. (Nevertheless, the
80 C<CORE::> prefix provides access to all Perl keywords, regardless of this
85 Like other pragmas (C<use strict>, for example), features have a lexical
86 effect. C<use feature qw(foo)> will only make the feature "foo" available
87 from that point to the end of the enclosing block.
91 say "say is available here";
93 print "But not here.\n";
97 Features can also be turned off by using C<no feature "foo">. This too
101 say "say is available here";
104 print "But not here.\n";
106 say "Yet it is here.";
108 C<no feature> with no features specified will reset to the default group. To
109 disable I<all> features (an unusual request!) use C<no feature ':all'>.
111 =head1 AVAILABLE FEATURES
113 =head2 The 'say' feature
115 C<use feature 'say'> tells the compiler to enable the Perl 6 style
118 See L<perlfunc/say> for details.
120 This feature is available starting with Perl 5.10.
122 =head2 The 'state' feature
124 C<use feature 'state'> tells the compiler to enable C<state>
127 See L<perlsub/"Persistent Private Variables"> for details.
129 This feature is available starting with Perl 5.10.
131 =head2 The 'switch' feature
133 C<use feature 'switch'> tells the compiler to enable the Perl 6
134 given/when construct.
136 See L<perlsyn/"Switch Statements"> for details.
138 This feature is available starting with Perl 5.10.
140 =head2 The 'unicode_strings' feature
142 C<use feature 'unicode_strings'> tells the compiler to use Unicode semantics
143 in all string operations executed within its scope (unless they are also
144 within the scope of either C<use locale> or C<use bytes>). The same applies
145 to all regular expressions compiled within the scope, even if executed outside
146 it. It does not change the internal representation of strings, but only how
147 they are interpreted.
149 C<no feature 'unicode_strings'> tells the compiler to use the traditional
150 Perl semantics wherein the native character set semantics is used unless it is
151 clear to Perl that Unicode is desired. This can lead to some surprises
152 when the behavior suddenly changes. (See
153 L<perlunicode/The "Unicode Bug"> for details.) For this reason, if you are
154 potentially using Unicode in your program, the
155 C<use feature 'unicode_strings'> subpragma is B<strongly> recommended.
157 This feature is available starting with Perl 5.12; was almost fully
158 implemented in Perl 5.14; and extended in Perl 5.16 to cover C<quotemeta>.
160 =head2 The 'unicode_eval' and 'evalbytes' features
162 Under the C<unicode_eval> feature, Perl's C<eval> function, when passed a
163 string, will evaluate it as a string of characters, ignoring any
164 C<use utf8> declarations. C<use utf8> exists to declare the encoding of
165 the script, which only makes sense for a stream of bytes, not a string of
166 characters. Source filters are forbidden, as they also really only make
167 sense on strings of bytes. Any attempt to activate a source filter will
170 The C<evalbytes> feature enables the C<evalbytes> keyword, which evaluates
171 the argument passed to it as a string of bytes. It dies if the string
172 contains any characters outside the 8-bit range. Source filters work
173 within C<evalbytes>: they apply to the contents of the string being
176 Together, these two features are intended to replace the historical C<eval>
177 function, which has (at least) two bugs in it, that cannot easily be fixed
178 without breaking existing programs:
184 C<eval> behaves differently depending on the internal encoding of the
185 string, sometimes treating its argument as a string of bytes, and sometimes
186 as a string of characters.
190 Source filters activated within C<eval> leak out into whichever I<file>
191 scope is currently being compiled. To give an example with the CPAN module
194 BEGIN { eval "use Semi::Semicolons; # not filtered here " }
197 C<evalbytes> fixes that to work the way one would expect:
199 use feature "evalbytes";
200 BEGIN { evalbytes "use Semi::Semicolons; # filtered " }
205 These two features are available starting with Perl 5.16.
207 =head2 The 'current_sub' feature
209 This provides the C<__SUB__> token that returns a reference to the current
210 subroutine or C<undef> outside of a subroutine.
212 This feature is available starting with Perl 5.16.
214 =head2 The 'array_base' feature
216 This feature supports the legacy C<$[> variable. See L<perlvar/$[> and
217 L<arybase>. It is on by default but disabled under C<use v5.16> (see
218 L</IMPLICIT LOADING>, below).
220 This feature is available under this name starting with Perl 5.16. In
221 previous versions, it was simply on all the time, and this pragma knew
224 =head2 The 'fc' feature
226 C<use feature 'fc'> tells the compiler to enable the C<fc> function,
227 which implements Unicode casefolding.
229 See L<perlfunc/fc> for details.
231 This feature is available from Perl 5.16 onwards.
233 =head2 The 'lexical_subs' feature
235 B<WARNING>: This feature is still experimental and the implementation may
236 change in future versions of Perl. For this reason, F<feature.pm> will
237 warn when you enable the feature, unless you have explicitly disabled the
240 no warnings "experimental::lexical_subs";
242 This enables declaration of subroutines via C<my sub foo>, C<state sub foo>
243 and C<our sub foo> syntax. See L<perlsub/Lexical Subroutines> for details.
245 This feature is available from Perl 5.18 onwards.
247 =head1 FEATURE BUNDLES
249 It's possible to load multiple features together, using
250 a I<feature bundle>. The name of a feature bundle is prefixed with
251 a colon, to distinguish it from an actual feature.
255 The following feature bundles are available:
257 bundle features included
258 --------- -----------------
261 :5.10 say state switch array_base
263 :5.12 say state switch unicode_strings array_base
265 :5.14 say state switch unicode_strings array_base
267 :5.16 say state switch unicode_strings
268 unicode_eval evalbytes current_sub fc
270 :5.18 say state switch unicode_strings
271 unicode_eval evalbytes current_sub fc
273 The C<:default> bundle represents the feature set that is enabled before
274 any C<use feature> or C<no feature> declaration.
276 Specifying sub-versions such as the C<0> in C<5.14.0> in feature bundles has
277 no effect. Feature bundles are guaranteed to be the same for all sub-versions.
279 use feature ":5.14.0"; # same as ":5.14"
280 use feature ":5.14.1"; # same as ":5.14"
282 =head1 IMPLICIT LOADING
284 Instead of loading feature bundles by name, it is easier to let Perl do
285 implicit loading of a feature bundle for you.
287 There are two ways to load the C<feature> pragma implicitly:
293 By using the C<-E> switch on the Perl command-line instead of C<-e>.
294 That will enable the feature bundle for that version of Perl in the
295 main compilation unit (that is, the one-liner that follows C<-E>).
299 By explicitly requiring a minimum Perl version number for your program, with
300 the C<use VERSION> construct. That is,
309 and so on. Note how the trailing sub-version
310 is automatically stripped from the
313 But to avoid portability warnings (see L<perlfunc/use>), you may prefer:
317 with the same effect.
319 If the required version is older than Perl 5.10, the ":default" feature
320 bundle is automatically loaded instead.
330 croak("No features specified");
339 # A bare C<no feature> should reset to the default bundle
341 $^H &= ~($hint_uni8bit|$hint_mask);
351 my $bundle_number = $^H & $hint_mask;
352 my $features = $bundle_number != $hint_mask
353 && $feature_bundle{$hint_bundles[$bundle_number >> $hint_shift]};
355 # Features are enabled implicitly via bundle hints.
356 # Delete any keys that may be left over from last time.
357 delete @^H{ values(%feature) };
360 $^H{$feature{$_}} = 1;
361 $^H |= $hint_uni8bit if $_ eq 'unicode_strings';
366 if (substr($name, 0, 1) eq ":") {
367 my $v = substr($name, 1);
368 if (!exists $feature_bundle{$v}) {
369 $v =~ s/^([0-9]+)\.([0-9]+).[0-9]+$/$1.$2/;
370 if (!exists $feature_bundle{$v}) {
371 unknown_feature_bundle(substr($name, 1));
374 unshift @_, @{$feature_bundle{$v}};
377 if (!exists $feature{$name}) {
378 unknown_feature($name);
381 $^H{$feature{$name}} = 1;
382 $^H |= $hint_uni8bit if $name eq 'unicode_strings';
383 if ($experimental{$name}) {
385 warnings::warnif("experimental::$name",
386 "The $name feature is experimental");
389 delete $^H{$feature{$name}};
390 $^H &= ~ $hint_uni8bit if $name eq 'unicode_strings';
395 sub unknown_feature {
397 croak(sprintf('Feature "%s" is not supported by Perl %vd',
401 sub unknown_feature_bundle {
403 croak(sprintf('Feature bundle "%s" is not supported by Perl %vd',