Debian Codegraph @

upstream/opensuse-tumbleweed/man3/feature.3pm

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