1feature(3pm)           Perl Programmers Reference Guide           feature(3pm)
2
3
4

NAME

6       feature - Perl pragma to enable new features
7

SYNOPSIS

9           use feature qw(fc say);
10
11           # Without the "use feature" above, this code would not be able to find
12           # the built-ins "say" or "fc":
13           say "The case-folded version of $x is: " . fc $x;
14
15
16           # set features to match the :5.10 bundle, which may turn off or on
17           # multiple features (see below)
18           use feature ':5.10';
19
20
21           # implicitly loads :5.10 feature bundle
22           use v5.10;
23

DESCRIPTION

25       It is usually impossible to add new syntax to Perl without breaking
26       some existing programs.  This pragma provides a way to minimize that
27       risk. New syntactic constructs, or new semantic meanings to older
28       constructs, can be enabled by "use feature 'foo'", and will be parsed
29       only when the appropriate feature pragma is in scope.  (Nevertheless,
30       the "CORE::" prefix provides access to all Perl keywords, regardless of
31       this pragma.)
32
33   Lexical effect
34       Like other pragmas ("use strict", for example), features have a lexical
35       effect.  "use feature qw(foo)" will only make the feature "foo"
36       available from that point to the end of the enclosing block.
37
38           {
39               use feature 'say';
40               say "say is available here";
41           }
42           print "But not here.\n";
43
44   "no feature"
45       Features can also be turned off by using "no feature "foo"".  This too
46       has lexical effect.
47
48           use feature 'say';
49           say "say is available here";
50           {
51               no feature 'say';
52               print "But not here.\n";
53           }
54           say "Yet it is here.";
55
56       "no feature" with no features specified will reset to the default
57       group.  To disable all features (an unusual request!) use "no feature
58       ':all'".
59

AVAILABLE FEATURES

61   The 'say' feature
62       "use feature 'say'" tells the compiler to enable the Raku-inspired
63       "say" function.
64
65       See "say" in perlfunc for details.
66
67       This feature is available starting with Perl 5.10.
68
69   The 'state' feature
70       "use feature 'state'" tells the compiler to enable "state" variables.
71
72       See "Persistent Private Variables" in perlsub for details.
73
74       This feature is available starting with Perl 5.10.
75
76   The 'switch' feature
77       WARNING: This feature is still experimental and the implementation may
78       change or be removed in future versions of Perl.  For this reason, Perl
79       will warn when you use the feature, unless you have explicitly disabled
80       the warning:
81
82           no warnings "experimental::smartmatch";
83
84       "use feature 'switch'" tells the compiler to enable the Raku given/when
85       construct.
86
87       See "Switch Statements" in perlsyn for details.
88
89       This feature is available starting with Perl 5.10.
90
91   The 'unicode_strings' feature
92       "use feature 'unicode_strings'" tells the compiler to use Unicode rules
93       in all string operations executed within its scope (unless they are
94       also within the scope of either "use locale" or "use bytes").  The same
95       applies to all regular expressions compiled within the scope, even if
96       executed outside it.  It does not change the internal representation of
97       strings, but only how they are interpreted.
98
99       "no feature 'unicode_strings'" tells the compiler to use the
100       traditional Perl rules wherein the native character set rules is used
101       unless it is clear to Perl that Unicode is desired.  This can lead to
102       some surprises when the behavior suddenly changes.  (See "The "Unicode
103       Bug"" in perlunicode for details.)  For this reason, if you are
104       potentially using Unicode in your program, the "use feature
105       'unicode_strings'" subpragma is strongly recommended.
106
107       This feature is available starting with Perl 5.12; was almost fully
108       implemented in Perl 5.14; and extended in Perl 5.16 to cover
109       "quotemeta"; was extended further in Perl 5.26 to cover the range
110       operator; and was extended again in Perl 5.28 to cover special-cased
111       whitespace splitting.
112
113   The 'unicode_eval' and 'evalbytes' features
114       Together, these two features are intended to replace the legacy string
115       "eval" function, which behaves problematically in some instances.  They
116       are available starting with Perl 5.16, and are enabled by default by a
117       "use 5.16" or higher declaration.
118
119       "unicode_eval" changes the behavior of plain string "eval" to work more
120       consistently, especially in the Unicode world.  Certain (mis)behaviors
121       couldn't be changed without breaking some things that had come to rely
122       on them, so the feature can be enabled and disabled.  Details are at
123       "Under the "unicode_eval" feature" in perlfunc.
124
125       "evalbytes" is like string "eval", but operating on a byte stream that
126       is not UTF-8 encoded.  Details are at "evalbytes EXPR" in perlfunc.
127       Without a "use feature 'evalbytes'" nor a "use v5.16" (or higher)
128       declaration in the current scope, you can still access it by instead
129       writing "CORE::evalbytes".
130
131   The 'current_sub' feature
132       This provides the "__SUB__" token that returns a reference to the
133       current subroutine or "undef" outside of a subroutine.
134
135       This feature is available starting with Perl 5.16.
136
137   The 'array_base' feature
138       This feature supported the legacy $[ variable.  See "$[" in perlvar.
139       It was on by default but disabled under "use v5.16" (see "IMPLICIT
140       LOADING", below) and unavailable since perl 5.30.
141
142       This feature is available under this name starting with Perl 5.16.  In
143       previous versions, it was simply on all the time, and this pragma knew
144       nothing about it.
145
146   The 'fc' feature
147       "use feature 'fc'" tells the compiler to enable the "fc" function,
148       which implements Unicode casefolding.
149
150       See "fc" in perlfunc for details.
151
152       This feature is available from Perl 5.16 onwards.
153
154   The 'lexical_subs' feature
155       In Perl versions prior to 5.26, this feature enabled declaration of
156       subroutines via "my sub foo", "state sub foo" and "our sub foo" syntax.
157       See "Lexical Subroutines" in perlsub for details.
158
159       This feature is available from Perl 5.18 onwards.  From Perl 5.18 to
160       5.24, it was classed as experimental, and Perl emitted a warning for
161       its usage, except when explicitly disabled:
162
163         no warnings "experimental::lexical_subs";
164
165       As of Perl 5.26, use of this feature no longer triggers a warning,
166       though the "experimental::lexical_subs" warning category still exists
167       (for compatibility with code that disables it).  In addition, this
168       syntax is not only no longer experimental, but it is enabled for all
169       Perl code, regardless of what feature declarations are in scope.
170
171   The 'postderef' and 'postderef_qq' features
172       The 'postderef_qq' feature extends the applicability of postfix
173       dereference syntax so that postfix array and scalar dereference are
174       available in double-quotish interpolations. For example, it makes the
175       following two statements equivalent:
176
177         my $s = "[@{ $h->{a} }]";
178         my $s = "[$h->{a}->@*]";
179
180       This feature is available from Perl 5.20 onwards. In Perl 5.20 and
181       5.22, it was classed as experimental, and Perl emitted a warning for
182       its usage, except when explicitly disabled:
183
184         no warnings "experimental::postderef";
185
186       As of Perl 5.24, use of this feature no longer triggers a warning,
187       though the "experimental::postderef" warning category still exists (for
188       compatibility with code that disables it).
189
190       The 'postderef' feature was used in Perl 5.20 and Perl 5.22 to enable
191       postfix dereference syntax outside double-quotish interpolations. In
192       those versions, using it triggered the "experimental::postderef"
193       warning in the same way as the 'postderef_qq' feature did. As of Perl
194       5.24, this syntax is not only no longer experimental, but it is enabled
195       for all Perl code, regardless of what feature declarations are in
196       scope.
197
198   The 'signatures' feature
199       WARNING: This feature is still experimental and the implementation may
200       change or be removed in future versions of Perl.  For this reason, Perl
201       will warn when you use the feature, unless you have explicitly disabled
202       the warning:
203
204           no warnings "experimental::signatures";
205
206       This enables unpacking of subroutine arguments into lexical variables
207       by syntax such as
208
209           sub foo ($left, $right) {
210               return $left + $right;
211           }
212
213       See "Signatures" in perlsub for details.
214
215       This feature is available from Perl 5.20 onwards.
216
217   The 'refaliasing' feature
218       WARNING: This feature is still experimental and the implementation may
219       change or be removed in future versions of Perl.  For this reason, Perl
220       will warn when you use the feature, unless you have explicitly disabled
221       the warning:
222
223           no warnings "experimental::refaliasing";
224
225       This enables aliasing via assignment to references:
226
227           \$a = \$b; # $a and $b now point to the same scalar
228           \@a = \@b; #                     to the same array
229           \%a = \%b;
230           \&a = \&b;
231           foreach \%hash (@array_of_hash_refs) {
232               ...
233           }
234
235       See "Assigning to References" in perlref for details.
236
237       This feature is available from Perl 5.22 onwards.
238
239   The 'bitwise' feature
240       This makes the four standard bitwise operators ("& | ^ ~") treat their
241       operands consistently as numbers, and introduces four new dotted
242       operators ("&. |. ^. ~.") that treat their operands consistently as
243       strings.  The same applies to the assignment variants ("&= |= ^= &.=
244       |.= ^.=").
245
246       See "Bitwise String Operators" in perlop for details.
247
248       This feature is available from Perl 5.22 onwards.  Starting in Perl
249       5.28, "use v5.28" will enable the feature.  Before 5.28, it was still
250       experimental and would emit a warning in the "experimental::bitwise"
251       category.
252
253   The 'declared_refs' feature
254       WARNING: This feature is still experimental and the implementation may
255       change or be removed in future versions of Perl.  For this reason, Perl
256       will warn when you use the feature, unless you have explicitly disabled
257       the warning:
258
259           no warnings "experimental::declared_refs";
260
261       This allows a reference to a variable to be declared with "my",
262       "state", our "our", or localized with "local".  It is intended mainly
263       for use in conjunction with the "refaliasing" feature.  See "Declaring
264       a Reference to a Variable" in perlref for examples.
265
266       This feature is available from Perl 5.26 onwards.
267
268   The 'isa' feature
269       WARNING: This feature is still experimental and the implementation may
270       change or be removed in future versions of Perl.  For this reason, Perl
271       will warn when you use the feature, unless you have explicitly disabled
272       the warning:
273
274           no warnings "experimental::isa";
275
276       This allows the use of the "isa" infix operator, which tests whether
277       the scalar given by the left operand is an object of the class given by
278       the right operand. See "Class Instance Operator" in perlop for more
279       details.
280
281       This feature is available from Perl 5.32 onwards.
282
283   The 'indirect' feature
284       This feature allows the use of indirect object syntax for method calls,
285       e.g.  "new Foo 1, 2;". It is enabled by default, but can be turned off
286       to disallow indirect object syntax.
287
288       This feature is available under this name from Perl 5.32 onwards. In
289       previous versions, it was simply on all the time.  To disallow (or warn
290       on) indirect object syntax on older Perls, see the indirect CPAN
291       module.
292
293   The 'multidimensional' feature
294       This feature enables multidimensional array emulation, a perl 4 (or
295       earlier) feature that was used to emulate multidimensional arrays with
296       hashes.  This works by converting code like $foo{$x, $y} into
297       $foo{join($;, $x, $y)}.  It is enabled by default, but can be turned
298       off to disable multidimensional array emulation.
299
300       When this feature is disabled the syntax that is normally replaced will
301       report a compilation error.
302
303       This feature is available under this name from Perl 5.34 onwards. In
304       previous versions, it was simply on all the time.
305
306       You can use the multidimensional module on CPAN to disable
307       multidimensional array emulation for older versions of Perl.
308
309   The 'bareword_filehandles' feature.
310       This feature enables bareword filehandles for builtin functions
311       operations, a generally discouraged practice.  It is enabled by
312       default, but can be turned off to disable bareword filehandles, except
313       for the exceptions listed below.
314
315       The perl built-in filehandles "STDIN", "STDOUT", "STDERR", "DATA",
316       "ARGV", "ARGVOUT" and the special "_" are always enabled.
317
318       This feature is enabled under this name from Perl 5.34 onwards.  In
319       previous versions it was simply on all the time.
320
321       You can use the bareword::filehandles module on CPAN to disable
322       bareword filehandles for older versions of perl.
323
324   The 'try' feature.
325       WARNING: This feature is still experimental and the implementation may
326       change or be removed in future versions of Perl.  For this reason, Perl
327       will warn when you use the feature, unless you have explicitly disabled
328       the warning:
329
330           no warnings "experimental::try";
331
332       This feature enables the "try" and "catch" syntax, which allows
333       exception handling, where exceptions thrown from the body of the block
334       introduced with "try" are caught by executing the body of the "catch"
335       block.
336
337       For more information, see "Try Catch Exception Handling" in perlsyn.
338

FEATURE BUNDLES

340       It's possible to load multiple features together, using a feature
341       bundle.  The name of a feature bundle is prefixed with a colon, to
342       distinguish it from an actual feature.
343
344         use feature ":5.10";
345
346       The following feature bundles are available:
347
348         bundle    features included
349         --------- -----------------
350         :default  indirect multidimensional
351                   bareword_filehandles
352
353         :5.10     bareword_filehandles indirect
354                   multidimensional say state switch
355
356         :5.12     bareword_filehandles indirect
357                   multidimensional say state switch
358                   unicode_strings
359
360         :5.14     bareword_filehandles indirect
361                   multidimensional say state switch
362                   unicode_strings
363
364         :5.16     bareword_filehandles current_sub evalbytes
365                   fc indirect multidimensional say state
366                   switch unicode_eval unicode_strings
367
368         :5.18     bareword_filehandles current_sub evalbytes
369                   fc indirect multidimensional say state
370                   switch unicode_eval unicode_strings
371
372         :5.20     bareword_filehandles current_sub evalbytes
373                   fc indirect multidimensional say state
374                   switch unicode_eval unicode_strings
375
376         :5.22     bareword_filehandles current_sub evalbytes
377                   fc indirect multidimensional say state
378                   switch unicode_eval unicode_strings
379
380         :5.24     bareword_filehandles current_sub evalbytes
381                   fc indirect multidimensional postderef_qq
382                   say state switch unicode_eval
383                   unicode_strings
384
385         :5.26     bareword_filehandles current_sub evalbytes
386                   fc indirect multidimensional postderef_qq
387                   say state switch unicode_eval
388                   unicode_strings
389
390         :5.28     bareword_filehandles bitwise current_sub
391                   evalbytes fc indirect multidimensional
392                   postderef_qq say state switch unicode_eval
393                   unicode_strings
394
395         :5.30     bareword_filehandles bitwise current_sub
396                   evalbytes fc indirect multidimensional
397                   postderef_qq say state switch unicode_eval
398                   unicode_strings
399
400         :5.32     bareword_filehandles bitwise current_sub
401                   evalbytes fc indirect multidimensional
402                   postderef_qq say state switch unicode_eval
403                   unicode_strings
404
405         :5.34     bareword_filehandles bitwise current_sub
406                   evalbytes fc indirect multidimensional
407                   postderef_qq say state switch unicode_eval
408                   unicode_strings
409
410       The ":default" bundle represents the feature set that is enabled before
411       any "use feature" or "no feature" declaration.
412
413       Specifying sub-versions such as the 0 in 5.14.0 in feature bundles has
414       no effect.  Feature bundles are guaranteed to be the same for all sub-
415       versions.
416
417         use feature ":5.14.0";    # same as ":5.14"
418         use feature ":5.14.1";    # same as ":5.14"
419

IMPLICIT LOADING

421       Instead of loading feature bundles by name, it is easier to let Perl do
422       implicit loading of a feature bundle for you.
423
424       There are two ways to load the "feature" pragma implicitly:
425
426       •   By using the "-E" switch on the Perl command-line instead of "-e".
427           That will enable the feature bundle for that version of Perl in the
428           main compilation unit (that is, the one-liner that follows "-E").
429
430       •   By explicitly requiring a minimum Perl version number for your
431           program, with the "use VERSION" construct.  That is,
432
433               use v5.10.0;
434
435           will do an implicit
436
437               no feature ':all';
438               use feature ':5.10';
439
440           and so on.  Note how the trailing sub-version is automatically
441           stripped from the version.
442
443           But to avoid portability warnings (see "use" in perlfunc), you may
444           prefer:
445
446               use 5.010;
447
448           with the same effect.
449
450           If the required version is older than Perl 5.10, the ":default"
451           feature bundle is automatically loaded instead.
452
453           Unlike "use feature ":5.12"", saying "use v5.12" (or any higher
454           version) also does the equivalent of "use strict"; see "use" in
455           perlfunc for details.
456
457
458
459perl v5.34.0                      2021-10-18                      feature(3pm)
Impressum