| 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. |