Debian Codegraph @

upstream/debian-unstable/man3/feature.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "feature 3perl"
58 .TH feature 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 feature \- Perl pragma to enable new features
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 1
68 \& use feature qw(fc say);
69 \&
70 \& # Without the "use feature" above, this code would not be able to find
71 \& # the built\-ins "say" or "fc":
72 \& say "The case\-folded version of $x is: " . fc $x;
73 \&
74 \&
75 \& # set features to match the :5.36 bundle, which may turn off or on
76 \& # multiple features (see "FEATURE BUNDLES" below)
77 \& use feature \*(Aq:5.36\*(Aq;
78 \&
79 \&
80 \& # implicitly loads :5.36 feature bundle
81 \& use v5.36;
82 .Ve
83 .SH DESCRIPTION
84 .IX Header "DESCRIPTION"
85 It is usually impossible to add new syntax to Perl without breaking
86 some existing programs. This pragma provides a way to minimize that
87 risk. New syntactic constructs, or new semantic meanings to older
88 constructs, can be enabled by \f(CW\*(C`use feature \*(Aqfoo\*(Aq\*(C'\fR, and will be parsed
89 only when the appropriate feature pragma is in scope. (Nevertheless, the
90 \&\f(CW\*(C`CORE::\*(C'\fR prefix provides access to all Perl keywords, regardless of this
91 pragma.)
92 .SS "Lexical effect"
93 .IX Subsection "Lexical effect"
94 Like other pragmas (\f(CW\*(C`use strict\*(C'\fR, for example), features have a lexical
95 effect. \f(CW\*(C`use feature qw(foo)\*(C'\fR will only make the feature "foo" available
96 from that point to the end of the enclosing block.
97 .PP
98 .Vb 5
99 \& {
100 \& use feature \*(Aqsay\*(Aq;
101 \& say "say is available here";
102 \& }
103 \& print "But not here.\en";
104 .Ve
105 .ie n .SS """no feature"""
106 .el .SS "\f(CWno feature\fP"
107 .IX Subsection "no feature"
108 Features can also be turned off by using \f(CW\*(C`no feature "foo"\*(C'\fR. This too
109 has lexical effect.
110 .PP
111 .Vb 7
112 \& use feature \*(Aqsay\*(Aq;
113 \& say "say is available here";
114 \& {
115 \& no feature \*(Aqsay\*(Aq;
116 \& print "But not here.\en";
117 \& }
118 \& say "Yet it is here.";
119 .Ve
120 .PP
121 \&\f(CW\*(C`no feature\*(C'\fR with no features specified will reset to the default group. To
122 disable \fIall\fR features (an unusual request!) use \f(CW\*(C`no feature \*(Aq:all\*(Aq\*(C'\fR.
123 .SH "AVAILABLE FEATURES"
124 .IX Header "AVAILABLE FEATURES"
125 Read "FEATURE BUNDLES" for the feature cheat sheet summary.
126 .SS "The 'say' feature"
127 .IX Subsection "The 'say' feature"
128 \&\f(CW\*(C`use feature \*(Aqsay\*(Aq\*(C'\fR tells the compiler to enable the Raku-inspired
129 \&\f(CW\*(C`say\*(C'\fR function.
130 .PP
131 See "say" in perlfunc for details.
132 .PP
133 This feature is available starting with Perl 5.10.
134 .SS "The 'state' feature"
135 .IX Subsection "The 'state' feature"
136 \&\f(CW\*(C`use feature \*(Aqstate\*(Aq\*(C'\fR tells the compiler to enable \f(CW\*(C`state\*(C'\fR
137 variables.
138 .PP
139 See "Persistent Private Variables" in perlsub for details.
140 .PP
141 This feature is available starting with Perl 5.10.
142 .SS "The 'switch' feature"
143 .IX Subsection "The 'switch' feature"
144 \&\fBWARNING\fR: This feature is still experimental and the implementation may
145 change or be removed in future versions of Perl. For this reason, Perl will
146 warn when you use the feature, unless you have explicitly disabled the warning:
147 .PP
148 .Vb 1
149 \& no warnings "experimental::smartmatch";
150 .Ve
151 .PP
152 \&\f(CW\*(C`use feature \*(Aqswitch\*(Aq\*(C'\fR tells the compiler to enable the Raku
153 given/when construct.
154 .PP
155 See "Switch Statements" in perlsyn for details.
156 .PP
157 This feature is available starting with Perl 5.10.
158 It is deprecated starting with Perl 5.38, and using
159 \&\f(CW\*(C`given\*(C'\fR, \f(CW\*(C`when\*(C'\fR or smartmatch will throw a warning.
160 It will be removed in Perl 5.42.
161 .SS "The 'unicode_strings' feature"
162 .IX Subsection "The 'unicode_strings' feature"
163 \&\f(CW\*(C`use feature \*(Aqunicode_strings\*(Aq\*(C'\fR tells the compiler to use Unicode rules
164 in all string operations executed within its scope (unless they are also
165 within the scope of either \f(CW\*(C`use locale\*(C'\fR or \f(CW\*(C`use bytes\*(C'\fR). The same applies
166 to all regular expressions compiled within the scope, even if executed outside
167 it. It does not change the internal representation of strings, but only how
168 they are interpreted.
169 .PP
170 \&\f(CW\*(C`no feature \*(Aqunicode_strings\*(Aq\*(C'\fR tells the compiler to use the traditional
171 Perl rules wherein the native character set rules is used unless it is
172 clear to Perl that Unicode is desired. This can lead to some surprises
173 when the behavior suddenly changes. (See
174 "The "Unicode Bug"" in perlunicode for details.) For this reason, if you are
175 potentially using Unicode in your program, the
176 \&\f(CW\*(C`use feature \*(Aqunicode_strings\*(Aq\*(C'\fR subpragma is \fBstrongly\fR recommended.
177 .PP
178 This feature is available starting with Perl 5.12; was almost fully
179 implemented in Perl 5.14; and extended in Perl 5.16 to cover \f(CW\*(C`quotemeta\*(C'\fR;
180 was extended further in Perl 5.26 to cover the range
181 operator; and was extended again in Perl 5.28 to
182 cover special-cased whitespace splitting.
183 .SS "The 'unicode_eval' and 'evalbytes' features"
184 .IX Subsection "The 'unicode_eval' and 'evalbytes' features"
185 Together, these two features are intended to replace the legacy string
186 \&\f(CW\*(C`eval\*(C'\fR function, which behaves problematically in some instances. They are
187 available starting with Perl 5.16, and are enabled by default by a
188 \&\f(CW\*(C`use\ 5.16\*(C'\fR or higher declaration.
189 .PP
190 \&\f(CW\*(C`unicode_eval\*(C'\fR changes the behavior of plain string \f(CW\*(C`eval\*(C'\fR to work more
191 consistently, especially in the Unicode world. Certain (mis)behaviors
192 couldn't be changed without breaking some things that had come to rely on
193 them, so the feature can be enabled and disabled. Details are at
194 "Under the "unicode_eval" feature" in perlfunc.
195 .PP
196 \&\f(CW\*(C`evalbytes\*(C'\fR is like string \f(CW\*(C`eval\*(C'\fR, but it treats its argument as a byte
197 string. Details are at "evalbytes EXPR" in perlfunc. Without a
198 \&\f(CW\*(C`use\ feature\ \*(Aqevalbytes\*(Aq\*(C'\fR nor a \f(CW\*(C`use\ v5.16\*(C'\fR (or higher) declaration in
199 the current scope, you can still access it by instead writing
200 \&\f(CW\*(C`CORE::evalbytes\*(C'\fR.
201 .SS "The 'current_sub' feature"
202 .IX Subsection "The 'current_sub' feature"
203 This provides the \f(CW\*(C`_\|_SUB_\|_\*(C'\fR token that returns a reference to the current
204 subroutine or \f(CW\*(C`undef\*(C'\fR outside of a subroutine.
205 .PP
206 This feature is available starting with Perl 5.16.
207 .SS "The 'array_base' feature"
208 .IX Subsection "The 'array_base' feature"
209 This feature supported the legacy \f(CW$[\fR variable. See "$[" in perlvar.
210 It was on by default but disabled under \f(CW\*(C`use v5.16\*(C'\fR (see
211 "IMPLICIT LOADING", below) and unavailable since perl 5.30.
212 .PP
213 This feature is available under this name starting with Perl 5.16. In
214 previous versions, it was simply on all the time, and this pragma knew
215 nothing about it.
216 .SS "The 'fc' feature"
217 .IX Subsection "The 'fc' feature"
218 \&\f(CW\*(C`use feature \*(Aqfc\*(Aq\*(C'\fR tells the compiler to enable the \f(CW\*(C`fc\*(C'\fR function,
219 which implements Unicode casefolding.
220 .PP
221 See "fc" in perlfunc for details.
222 .PP
223 This feature is available from Perl 5.16 onwards.
224 .SS "The 'lexical_subs' feature"
225 .IX Subsection "The 'lexical_subs' feature"
226 In Perl versions prior to 5.26, this feature enabled
227 declaration of subroutines via \f(CW\*(C`my sub foo\*(C'\fR, \f(CW\*(C`state sub foo\*(C'\fR
228 and \f(CW\*(C`our sub foo\*(C'\fR syntax. See "Lexical Subroutines" in perlsub for details.
229 .PP
230 This feature is available from Perl 5.18 onwards. From Perl 5.18 to 5.24,
231 it was classed as experimental, and Perl emitted a warning for its
232 usage, except when explicitly disabled:
233 .PP
234 .Vb 1
235 \& no warnings "experimental::lexical_subs";
236 .Ve
237 .PP
238 As of Perl 5.26, use of this feature no longer triggers a warning, though
239 the \f(CW\*(C`experimental::lexical_subs\*(C'\fR warning category still exists (for
240 compatibility with code that disables it). In addition, this syntax is
241 not only no longer experimental, but it is enabled for all Perl code,
242 regardless of what feature declarations are in scope.
243 .SS "The 'postderef' and 'postderef_qq' features"
244 .IX Subsection "The 'postderef' and 'postderef_qq' features"
245 The 'postderef_qq' feature extends the applicability of postfix
246 dereference syntax so that
247 postfix array dereference, postfix scalar dereference, and
248 postfix array highest index access are available in double-quotish interpolations.
249 For example, it makes the following two statements equivalent:
250 .PP
251 .Vb 2
252 \& my $s = "[@{ $h\->{a} }]";
253 \& my $s = "[$h\->{a}\->@*]";
254 .Ve
255 .PP
256 This feature is available from Perl 5.20 onwards. In Perl 5.20 and 5.22, it
257 was classed as experimental, and Perl emitted a warning for its
258 usage, except when explicitly disabled:
259 .PP
260 .Vb 1
261 \& no warnings "experimental::postderef";
262 .Ve
263 .PP
264 As of Perl 5.24, use of this feature no longer triggers a warning, though
265 the \f(CW\*(C`experimental::postderef\*(C'\fR warning category still exists (for
266 compatibility with code that disables it).
267 .PP
268 The 'postderef' feature was used in Perl 5.20 and Perl 5.22 to enable
269 postfix dereference syntax outside double-quotish interpolations. In those
270 versions, using it triggered the \f(CW\*(C`experimental::postderef\*(C'\fR warning in the
271 same way as the 'postderef_qq' feature did. As of Perl 5.24, this syntax is
272 not only no longer experimental, but it is enabled for all Perl code,
273 regardless of what feature declarations are in scope.
274 .SS "The 'signatures' feature"
275 .IX Subsection "The 'signatures' feature"
276 This enables syntax for declaring subroutine arguments as lexical variables.
277 For example, for this subroutine:
278 .PP
279 .Vb 3
280 \& sub foo ($left, $right) {
281 \& return $left + $right;
282 \& }
283 .Ve
284 .PP
285 Calling \f(CW\*(C`foo(3, 7)\*(C'\fR will assign \f(CW3\fR into \f(CW$left\fR and \f(CW7\fR into \f(CW$right\fR.
286 .PP
287 See "Signatures" in perlsub for details.
288 .PP
289 This feature is available from Perl 5.20 onwards. From Perl 5.20 to 5.34,
290 it was classed as experimental, and Perl emitted a warning for its usage,
291 except when explicitly disabled:
292 .PP
293 .Vb 1
294 \& no warnings "experimental::signatures";
295 .Ve
296 .PP
297 As of Perl 5.36, use of this feature no longer triggers a warning, though the
298 \&\f(CW\*(C`experimental::signatures\*(C'\fR warning category still exists (for compatibility
299 with code that disables it). This feature is now considered stable, and is
300 enabled automatically by \f(CW\*(C`use v5.36\*(C'\fR (or higher).
301 .SS "The 'refaliasing' feature"
302 .IX Subsection "The 'refaliasing' feature"
303 \&\fBWARNING\fR: This feature is still experimental and the implementation may
304 change or be removed in future versions of Perl. For this reason, Perl will
305 warn when you use the feature, unless you have explicitly disabled the warning:
306 .PP
307 .Vb 1
308 \& no warnings "experimental::refaliasing";
309 .Ve
310 .PP
311 This enables aliasing via assignment to references:
312 .PP
313 .Vb 7
314 \& \e$a = \e$b; # $a and $b now point to the same scalar
315 \& \e@a = \e@b; # to the same array
316 \& \e%a = \e%b;
317 \& \e&a = \e&b;
318 \& foreach \e%hash (@array_of_hash_refs) {
319 \& ...
320 \& }
321 .Ve
322 .PP
323 See "Assigning to References" in perlref for details.
324 .PP
325 This feature is available from Perl 5.22 onwards.
326 .SS "The 'bitwise' feature"
327 .IX Subsection "The 'bitwise' feature"
328 This makes the four standard bitwise operators (\f(CW\*(C`& | ^ ~\*(C'\fR) treat their
329 operands consistently as numbers, and introduces four new dotted operators
330 (\f(CW\*(C`&. |. ^. ~.\*(C'\fR) that treat their operands consistently as strings. The
331 same applies to the assignment variants (\f(CW\*(C`&= |= ^= &.= |.= ^.=\*(C'\fR).
332 .PP
333 See "Bitwise String Operators" in perlop for details.
334 .PP
335 This feature is available from Perl 5.22 onwards. Starting in Perl 5.28,
336 \&\f(CW\*(C`use v5.28\*(C'\fR will enable the feature. Before 5.28, it was still
337 experimental and would emit a warning in the "experimental::bitwise"
338 category.
339 .SS "The 'declared_refs' feature"
340 .IX Subsection "The 'declared_refs' feature"
341 \&\fBWARNING\fR: This feature is still experimental and the implementation may
342 change or be removed in future versions of Perl. For this reason, Perl will
343 warn when you use the feature, unless you have explicitly disabled the warning:
344 .PP
345 .Vb 1
346 \& no warnings "experimental::declared_refs";
347 .Ve
348 .PP
349 This allows a reference to a variable to be declared with \f(CW\*(C`my\*(C'\fR, \f(CW\*(C`state\*(C'\fR,
350 or \f(CW\*(C`our\*(C'\fR, or localized with \f(CW\*(C`local\*(C'\fR. It is intended mainly for use in
351 conjunction with the "refaliasing" feature. See "Declaring a
352 Reference to a Variable" in perlref for examples.
353 .PP
354 This feature is available from Perl 5.26 onwards.
355 .SS "The 'isa' feature"
356 .IX Subsection "The 'isa' feature"
357 This allows the use of the \f(CW\*(C`isa\*(C'\fR infix operator, which tests whether the
358 scalar given by the left operand is an object of the class given by the
359 right operand. See "Class Instance Operator" in perlop for more details.
360 .PP
361 This feature is available from Perl 5.32 onwards. From Perl 5.32 to 5.34,
362 it was classed as experimental, and Perl emitted a warning for its usage,
363 except when explicitly disabled:
364 .PP
365 .Vb 1
366 \& no warnings "experimental::isa";
367 .Ve
368 .PP
369 As of Perl 5.36, use of this feature no longer triggers a warning (though the
370 \&\f(CW\*(C`experimental::isa\*(C'\fR warning category still exists for compatibility with
371 code that disables it). This feature is now considered stable, and is enabled
372 automatically by \f(CW\*(C`use v5.36\*(C'\fR (or higher).
373 .SS "The 'indirect' feature"
374 .IX Subsection "The 'indirect' feature"
375 This feature allows the use of indirect object
376 syntax for method calls, e.g. \f(CW\*(C`new
377 Foo 1, 2;\*(C'\fR. It is enabled by default, but can be turned off to
378 disallow indirect object syntax.
379 .PP
380 This feature is available under this name from Perl 5.32 onwards. In
381 previous versions, it was simply on all the time. To disallow (or
382 warn on) indirect object syntax on older Perls, see the indirect
383 CPAN module.
384 .SS "The 'multidimensional' feature"
385 .IX Subsection "The 'multidimensional' feature"
386 This feature enables multidimensional array emulation, a perl 4 (or
387 earlier) feature that was used to emulate multidimensional arrays with
388 hashes. This works by converting code like \f(CW$foo{$x, $y}\fR into
389 \&\f(CW$foo{join($;, $x, $y)}\fR. It is enabled by default, but can be
390 turned off to disable multidimensional array emulation.
391 .PP
392 When this feature is disabled the syntax that is normally replaced
393 will report a compilation error.
394 .PP
395 This feature is available under this name from Perl 5.34 onwards. In
396 previous versions, it was simply on all the time.
397 .PP
398 You can use the multidimensional module on CPAN to disable
399 multidimensional array emulation for older versions of Perl.
400 .SS "The 'bareword_filehandles' feature"
401 .IX Subsection "The 'bareword_filehandles' feature"
402 This feature enables bareword filehandles for builtin functions
403 operations, a generally discouraged practice. It is enabled by
404 default, but can be turned off to disable bareword filehandles, except
405 for the exceptions listed below.
406 .PP
407 The perl built-in filehandles \f(CW\*(C`STDIN\*(C'\fR, \f(CW\*(C`STDOUT\*(C'\fR, \f(CW\*(C`STDERR\*(C'\fR, \f(CW\*(C`DATA\*(C'\fR,
408 \&\f(CW\*(C`ARGV\*(C'\fR, \f(CW\*(C`ARGVOUT\*(C'\fR and the special \f(CW\*(C`_\*(C'\fR are always enabled.
409 .PP
410 This feature is available under this name from Perl 5.34 onwards. In
411 previous versions it was simply on all the time.
412 .PP
413 You can use the bareword::filehandles module on CPAN to disable
414 bareword filehandles for older versions of perl.
415 .SS "The 'try' feature"
416 .IX Subsection "The 'try' feature"
417 \&\fBWARNING\fR: This feature is still partly experimental, and the implementation
418 may change or be removed in future versions of Perl.
419 .PP
420 This feature enables the \f(CW\*(C`try\*(C'\fR and \f(CW\*(C`catch\*(C'\fR syntax, which allows exception
421 handling, where exceptions thrown from the body of the block introduced with
422 \&\f(CW\*(C`try\*(C'\fR are caught by executing the body of the \f(CW\*(C`catch\*(C'\fR block.
423 .PP
424 This feature is available starting in Perl 5.34. Before Perl 5.40 it was
425 classed as experimental, and Perl emitted a warning for its usage, except when
426 explicitly disabled:
427 .PP
428 .Vb 1
429 \& no warnings "experimental::try";
430 .Ve
431 .PP
432 As of Perl 5.40, use of this feature without a \f(CW\*(C`finally\*(C'\fR block no longer
433 triggers a warning. The optional \f(CW\*(C`finally\*(C'\fR block is still considered
434 experimental and emits a warning, except when explicitly disabled as above.
435 .PP
436 For more information, see "Try Catch Exception Handling" in perlsyn.
437 .SS "The 'defer' feature"
438 .IX Subsection "The 'defer' feature"
439 \&\fBWARNING\fR: This feature is still experimental and the implementation may
440 change or be removed in future versions of Perl. For this reason, Perl will
441 warn when you use the feature, unless you have explicitly disabled the warning:
442 .PP
443 .Vb 1
444 \& no warnings "experimental::defer";
445 .Ve
446 .PP
447 This feature enables the \f(CW\*(C`defer\*(C'\fR block syntax, which allows a block of code
448 to be deferred until when the flow of control leaves the block which contained
449 it. For more details, see "defer" in perlsyn.
450 .PP
451 This feature is available starting in Perl 5.36.
452 .SS "The 'extra_paired_delimiters' feature"
453 .IX Subsection "The 'extra_paired_delimiters' feature"
454 \&\fBWARNING\fR: This feature is still experimental and the implementation may
455 change or be removed in future versions of Perl. For this reason, Perl will
456 warn when you use the feature, unless you have explicitly disabled the warning:
457 .PP
458 .Vb 1
459 \& no warnings "experimental::extra_paired_delimiters";
460 .Ve
461 .PP
462 This feature enables the use of more paired string delimiters than the
463 traditional four, \f(CW\*(C`<\ \ >\*(C'\fR, \f(CW\*(C`(\ )\*(C'\fR, \f(CW\*(C`{\ }\*(C'\fR, and \f(CW\*(C`[\ ]\*(C'\fR. When
464 this feature is on, for example, you can say \f(CW\*(C`qr«pat»\*(C'\fR.
465 .PP
466 As with any usage of non-ASCII delimiters in a UTF\-8\-encoded source file, you
467 will want to ensure the parser will decode the source code from UTF\-8 bytes
468 with a declaration such as \f(CW\*(C`use utf8\*(C'\fR.
469 .PP
470 This feature is available starting in Perl 5.36.
471 .PP
472 For a full list of the available characters, see
473 "List of Extra Paired Delimiters" in perlop.
474 .SS "The 'module_true' feature"
475 .IX Subsection "The 'module_true' feature"
476 This feature removes the need to return a true value at the end of a module
477 loaded with \f(CW\*(C`require\*(C'\fR or \f(CW\*(C`use\*(C'\fR. Any errors during compilation will cause
478 failures, but reaching the end of the module when this feature is in effect
479 will prevent \f(CW\*(C`perl\*(C'\fR from throwing an exception that the module "did not return
480 a true value".
481 .SS "The 'class' feature"
482 .IX Subsection "The 'class' feature"
483 \&\fBWARNING\fR: This feature is still experimental and the implementation may
484 change or be removed in future versions of Perl. For this reason, Perl will
485 warn when you use the feature, unless you have explicitly disabled the warning:
486 .PP
487 .Vb 1
488 \& no warnings "experimental::class";
489 .Ve
490 .PP
491 This feature enables the \f(CW\*(C`class\*(C'\fR block syntax and other associated keywords
492 which implement the "new" object system, previously codenamed "Corinna".
493 .SH "FEATURE BUNDLES"
494 .IX Header "FEATURE BUNDLES"
495 It's possible to load multiple features together, using
496 a \fIfeature bundle\fR. The name of a feature bundle is prefixed with
497 a colon, to distinguish it from an actual feature.
498 .PP
499 .Vb 1
500 \& use feature ":5.10";
501 .Ve
502 .PP
503 The following feature bundles are available:
504 .PP
505 .Vb 4
506 \& bundle features included
507 \& \-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
508 \& :default indirect multidimensional
509 \& bareword_filehandles
510 \&
511 \& :5.10 bareword_filehandles indirect
512 \& multidimensional say state switch
513 \&
514 \& :5.12 bareword_filehandles indirect
515 \& multidimensional say state switch
516 \& unicode_strings
517 \&
518 \& :5.14 bareword_filehandles indirect
519 \& multidimensional say state switch
520 \& unicode_strings
521 \&
522 \& :5.16 bareword_filehandles current_sub evalbytes
523 \& fc indirect multidimensional say state
524 \& switch unicode_eval unicode_strings
525 \&
526 \& :5.18 bareword_filehandles current_sub evalbytes
527 \& fc indirect multidimensional say state
528 \& switch unicode_eval unicode_strings
529 \&
530 \& :5.20 bareword_filehandles current_sub evalbytes
531 \& fc indirect multidimensional say state
532 \& switch unicode_eval unicode_strings
533 \&
534 \& :5.22 bareword_filehandles current_sub evalbytes
535 \& fc indirect multidimensional say state
536 \& switch unicode_eval unicode_strings
537 \&
538 \& :5.24 bareword_filehandles current_sub evalbytes
539 \& fc indirect multidimensional postderef_qq
540 \& say state switch unicode_eval
541 \& unicode_strings
542 \&
543 \& :5.26 bareword_filehandles current_sub evalbytes
544 \& fc indirect multidimensional postderef_qq
545 \& say state switch unicode_eval
546 \& unicode_strings
547 \&
548 \& :5.28 bareword_filehandles bitwise current_sub
549 \& evalbytes fc indirect multidimensional
550 \& postderef_qq say state switch unicode_eval
551 \& unicode_strings
552 \&
553 \& :5.30 bareword_filehandles bitwise current_sub
554 \& evalbytes fc indirect multidimensional
555 \& postderef_qq say state switch unicode_eval
556 \& unicode_strings
557 \&
558 \& :5.32 bareword_filehandles bitwise current_sub
559 \& evalbytes fc indirect multidimensional
560 \& postderef_qq say state switch unicode_eval
561 \& unicode_strings
562 \&
563 \& :5.34 bareword_filehandles bitwise current_sub
564 \& evalbytes fc indirect multidimensional
565 \& postderef_qq say state switch unicode_eval
566 \& unicode_strings
567 \&
568 \& :5.36 bareword_filehandles bitwise current_sub
569 \& evalbytes fc isa postderef_qq say signatures
570 \& state unicode_eval unicode_strings
571 \&
572 \& :5.38 bitwise current_sub evalbytes fc isa
573 \& module_true postderef_qq say signatures
574 \& state unicode_eval unicode_strings
575 \&
576 \& :5.40 bitwise current_sub evalbytes fc isa
577 \& module_true postderef_qq say signatures
578 \& state try unicode_eval unicode_strings
579 .Ve
580 .PP
581 The \f(CW\*(C`:default\*(C'\fR bundle represents the feature set that is enabled before
582 any \f(CW\*(C`use feature\*(C'\fR or \f(CW\*(C`no feature\*(C'\fR declaration.
583 .PP
584 Specifying sub-versions such as the \f(CW0\fR in \f(CW5.14.0\fR in feature bundles has
585 no effect. Feature bundles are guaranteed to be the same for all sub-versions.
586 .PP
587 .Vb 2
588 \& use feature ":5.14.0"; # same as ":5.14"
589 \& use feature ":5.14.1"; # same as ":5.14"
590 .Ve
591 .PP
592 You can also do:
593 .PP
594 .Vb 1
595 \& use feature ":all";
596 .Ve
597 .PP
598 or
599 .PP
600 .Vb 1
601 \& no feature ":all";
602 .Ve
603 .PP
604 but the first may enable features in a later version of Perl that
605 change the meaning of your code, and the second may disable mechanisms
606 that are part of Perl's current behavior that have been turned into
607 features, just as \f(CW\*(C`indirect\*(C'\fR and \f(CW\*(C`bareword_filehandles\*(C'\fR were.
608 .SH "IMPLICIT LOADING"
609 .IX Header "IMPLICIT LOADING"
610 Instead of loading feature bundles by name, it is easier to let Perl do
611 implicit loading of a feature bundle for you.
612 .PP
613 There are two ways to load the \f(CW\*(C`feature\*(C'\fR pragma implicitly:
614 .IP \(bu 4
615 By using the \f(CW\*(C`\-E\*(C'\fR switch on the Perl command-line instead of \f(CW\*(C`\-e\*(C'\fR.
616 That will enable the feature bundle for that version of Perl in the
617 main compilation unit (that is, the one-liner that follows \f(CW\*(C`\-E\*(C'\fR).
618 .IP \(bu 4
619 By explicitly requiring a minimum Perl version number for your program, with
620 the \f(CW\*(C`use VERSION\*(C'\fR construct. That is,
621 .Sp
622 .Vb 1
623 \& use v5.36.0;
624 .Ve
625 .Sp
626 will do an implicit
627 .Sp
628 .Vb 2
629 \& no feature \*(Aq:all\*(Aq;
630 \& use feature \*(Aq:5.36\*(Aq;
631 .Ve
632 .Sp
633 and so on. Note how the trailing sub-version
634 is automatically stripped from the
635 version.
636 .Sp
637 But to avoid portability warnings (see "use" in perlfunc), you may prefer:
638 .Sp
639 .Vb 1
640 \& use 5.036;
641 .Ve
642 .Sp
643 with the same effect.
644 .Sp
645 If the required version is older than Perl 5.10, the ":default" feature
646 bundle is automatically loaded instead.
647 .Sp
648 Unlike \f(CW\*(C`use feature ":5.12"\*(C'\fR, saying \f(CW\*(C`use v5.12\*(C'\fR (or any higher version)
649 also does the equivalent of \f(CW\*(C`use strict\*(C'\fR; see "use" in perlfunc for details.
650 .SH "CHECKING FEATURES"
651 .IX Header "CHECKING FEATURES"
652 \&\f(CW\*(C`feature\*(C'\fR provides some simple APIs to check which features are enabled.
653 .PP
654 These functions cannot be imported and must be called by their fully
655 qualified names. If you don't otherwise need to set a feature you will
656 need to ensure \f(CW\*(C`feature\*(C'\fR is loaded with:
657 .PP
658 .Vb 1
659 \& use feature ();
660 .Ve
661 .IP feature_enabled($feature) 4
662 .IX Item "feature_enabled($feature)"
663 .PD 0
664 .ie n .IP "feature_enabled($feature, $depth)" 4
665 .el .IP "feature_enabled($feature, \f(CW$depth\fR)" 4
666 .IX Item "feature_enabled($feature, $depth)"
667 .PD
668 .Vb 6
669 \& package MyStandardEnforcer;
670 \& use feature ();
671 \& use Carp "croak";
672 \& sub import {
673 \& croak "disable indirect!" if feature::feature_enabled("indirect");
674 \& }
675 .Ve
676 .Sp
677 Test whether a named feature is enabled at a given level in the call
678 stack, returning a true value if it is. \f(CW$depth\fR defaults to 1,
679 which checks the scope that called the scope calling
680 \&\fBfeature::feature_enabled()\fR.
681 .Sp
682 croaks for an unknown feature name.
683 .IP \fBfeatures_enabled()\fR 4
684 .IX Item "features_enabled()"
685 .PD 0
686 .IP features_enabled($depth) 4
687 .IX Item "features_enabled($depth)"
688 .PD
689 .Vb 5
690 \& package ReportEnabledFeatures;
691 \& use feature "say";
692 \& sub import {
693 \& say STDERR join " ", feature::features_enabled();
694 \& }
695 .Ve
696 .Sp
697 Returns a list of the features enabled at a given level in the call
698 stack. \f(CW$depth\fR defaults to 1, which checks the scope that called
699 the scope calling \fBfeature::features_enabled()\fR.
700 .IP \fBfeature_bundle()\fR 4
701 .IX Item "feature_bundle()"
702 .PD 0
703 .IP feature_bundle($depth) 4
704 .IX Item "feature_bundle($depth)"
705 .PD
706 Returns the feature bundle, if any, selected at a given level in the
707 call stack. \f(CW$depth\fR defaults to 1, which checks the scope that called
708 the scope calling \fBfeature::feature_bundle()\fR.
709 .Sp
710 Returns an undefined value if no feature bundle is selected in the
711 scope.
712 .Sp
713 The bundle name returned will be for the earliest bundle matching the
714 selected bundle, so:
715 .Sp
716 .Vb 3
717 \& use feature ();
718 \& use v5.12;
719 \& BEGIN { print feature::feature_bundle(0); }
720 .Ve
721 .Sp
722 will print \f(CW5.11\fR.
723 .Sp
724 This returns internal state, at this point \f(CW\*(C`use v5.12;\*(C'\fR sets the
725 feature bundle, but \f(CW\*(C` use feature ":5.12"; \*(C'\fR does not set the feature
726 bundle. This may change in a future release of perl.