{ "content": [ { "type": "text", "text": "# feature (man)\n\n## NAME\n\nfeature - Perl pragma to enable new features\n\n## SYNOPSIS\n\nuse feature qw(fc say);\n# Without the \"use feature\" above, this code would not be able to find\n# the built-ins \"say\" or \"fc\":\nsay \"The case-folded version of $x is: \" . fc $x;\n# set features to match the :5.10 bundle, which may turn off or on\n# multiple features (see below)\nuse feature ':5.10';\n# implicitly loads :5.10 feature bundle\nuse v5.10;\n\n## DESCRIPTION\n\nIt is usually impossible to add new syntax to Perl without breaking some existing programs.\nThis pragma provides a way to minimize that risk. New syntactic constructs, or new semantic\nmeanings to older constructs, can be enabled by \"use feature 'foo'\", and will be parsed only\nwhen the appropriate feature pragma is in scope. (Nevertheless, the \"CORE::\" prefix provides\naccess to all Perl keywords, regardless of this pragma.)\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION** (2 subsections)\n- **AVAILABLE FEATURES** (11 subsections)\n- **FEATURE BUNDLES**\n- **IMPLICIT LOADING**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "feature", "section": "", "mode": "man", "summary": "feature - Perl pragma to enable new features", "synopsis": "use feature qw(fc say);\n# Without the \"use feature\" above, this code would not be able to find\n# the built-ins \"say\" or \"fc\":\nsay \"The case-folded version of $x is: \" . fc $x;\n# set features to match the :5.10 bundle, which may turn off or on\n# multiple features (see below)\nuse feature ':5.10';\n# implicitly loads :5.10 feature bundle\nuse v5.10;", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 15, "subsections": [] }, { "name": "DESCRIPTION", "lines": 6, "subsections": [ { "name": "Lexical effect", "lines": 10 }, { "name": "\"no feature\"", "lines": 13 } ] }, { "name": "AVAILABLE FEATURES", "lines": 1, "subsections": [ { "name": "The 'say' feature", "lines": 6 }, { "name": "The 'state' feature", "lines": 6 }, { "name": "The 'switch' feature", "lines": 59 }, { "name": "The 'fc' feature", "lines": 45 }, { "name": "The 'signatures' feature", "lines": 16 }, { "name": "The 'refaliasing' feature", "lines": 20 }, { "name": "The 'bitwise' feature", "lines": 24 }, { "name": "The 'isa' feature", "lines": 12 }, { "name": "The 'indirect' feature", "lines": 7 }, { "name": "The 'multidimensional' feature", "lines": 28 }, { "name": "The 'try' feature.", "lines": 12 } ] }, { "name": "FEATURE BUNDLES", "lines": 78, "subsections": [] }, { "name": "IMPLICIT LOADING", "lines": 36, "subsections": [] } ], "sections": { "NAME": { "content": "feature - Perl pragma to enable new features\n", "subsections": [] }, "SYNOPSIS": { "content": "use feature qw(fc say);\n\n# Without the \"use feature\" above, this code would not be able to find\n# the built-ins \"say\" or \"fc\":\nsay \"The case-folded version of $x is: \" . fc $x;\n\n\n# set features to match the :5.10 bundle, which may turn off or on\n# multiple features (see below)\nuse feature ':5.10';\n\n\n# implicitly loads :5.10 feature bundle\nuse v5.10;\n", "subsections": [] }, "DESCRIPTION": { "content": "It is usually impossible to add new syntax to Perl without breaking some existing programs.\nThis pragma provides a way to minimize that risk. New syntactic constructs, or new semantic\nmeanings to older constructs, can be enabled by \"use feature 'foo'\", and will be parsed only\nwhen the appropriate feature pragma is in scope. (Nevertheless, the \"CORE::\" prefix provides\naccess to all Perl keywords, regardless of this pragma.)\n", "subsections": [ { "name": "Lexical effect", "content": "Like other pragmas (\"use strict\", for example), features have a lexical effect. \"use feature\nqw(foo)\" will only make the feature \"foo\" available from that point to the end of the\nenclosing block.\n\n{\nuse feature 'say';\nsay \"say is available here\";\n}\nprint \"But not here.\\n\";\n" }, { "name": "\"no feature\"", "content": "Features can also be turned off by using \"no feature \"foo\"\". This too has lexical effect.\n\nuse feature 'say';\nsay \"say is available here\";\n{\nno feature 'say';\nprint \"But not here.\\n\";\n}\nsay \"Yet it is here.\";\n\n\"no feature\" with no features specified will reset to the default group. To disable all\nfeatures (an unusual request!) use \"no feature ':all'\".\n" } ] }, "AVAILABLE FEATURES": { "content": "", "subsections": [ { "name": "The 'say' feature", "content": "\"use feature 'say'\" tells the compiler to enable the Raku-inspired \"say\" function.\n\nSee \"say\" in perlfunc for details.\n\nThis feature is available starting with Perl 5.10.\n" }, { "name": "The 'state' feature", "content": "\"use feature 'state'\" tells the compiler to enable \"state\" variables.\n\nSee \"Persistent Private Variables\" in perlsub for details.\n\nThis feature is available starting with Perl 5.10.\n" }, { "name": "The 'switch' feature", "content": "WARNING: This feature is still experimental and the implementation may change or be removed\nin future versions of Perl. For this reason, Perl will warn when you use the feature, unless\nyou have explicitly disabled the warning:\n\nno warnings \"experimental::smartmatch\";\n\n\"use feature 'switch'\" tells the compiler to enable the Raku given/when construct.\n\nSee \"Switch Statements\" in perlsyn for details.\n\nThis feature is available starting with Perl 5.10.\n\nThe 'unicodestrings' feature\n\"use feature 'unicodestrings'\" tells the compiler to use Unicode rules in all string\noperations executed within its scope (unless they are also within the scope of either \"use\nlocale\" or \"use bytes\"). The same applies to all regular expressions compiled within the\nscope, even if executed outside it. It does not change the internal representation of\nstrings, but only how they are interpreted.\n\n\"no feature 'unicodestrings'\" tells the compiler to use the traditional Perl rules wherein\nthe native character set rules is used unless it is clear to Perl that Unicode is desired.\nThis can lead to some surprises when the behavior suddenly changes. (See \"The \"Unicode Bug\"\"\nin perlunicode for details.) For this reason, if you are potentially using Unicode in your\nprogram, the \"use feature 'unicodestrings'\" subpragma is strongly recommended.\n\nThis feature is available starting with Perl 5.12; was almost fully implemented in Perl 5.14;\nand extended in Perl 5.16 to cover \"quotemeta\"; was extended further in Perl 5.26 to cover\nthe range operator; and was extended again in Perl 5.28 to cover special-cased whitespace\nsplitting.\n\nThe 'unicodeeval' and 'evalbytes' features\nTogether, these two features are intended to replace the legacy string \"eval\" function, which\nbehaves problematically in some instances. They are available starting with Perl 5.16, and\nare enabled by default by a \"use 5.16\" or higher declaration.\n\n\"unicodeeval\" changes the behavior of plain string \"eval\" to work more consistently,\nespecially in the Unicode world. Certain (mis)behaviors couldn't be changed without breaking\nsome things that had come to rely on them, so the feature can be enabled and disabled.\nDetails are at \"Under the \"unicodeeval\" feature\" in perlfunc.\n\n\"evalbytes\" is like string \"eval\", but operating on a byte stream that is not UTF-8 encoded.\nDetails are at \"evalbytes EXPR\" in perlfunc. Without a \"use feature 'evalbytes'\" nor a\n\"use v5.16\" (or higher) declaration in the current scope, you can still access it by instead\nwriting \"CORE::evalbytes\".\n\nThe 'currentsub' feature\nThis provides the \"SUB\" token that returns a reference to the current subroutine or\n\"undef\" outside of a subroutine.\n\nThis feature is available starting with Perl 5.16.\n\nThe 'arraybase' feature\nThis feature supported the legacy $[ variable. See \"$[\" in perlvar. It was on by default\nbut disabled under \"use v5.16\" (see \"IMPLICIT LOADING\", below) and unavailable since perl\n5.30.\n\nThis feature is available under this name starting with Perl 5.16. In previous versions, it\nwas simply on all the time, and this pragma knew nothing about it.\n" }, { "name": "The 'fc' feature", "content": "\"use feature 'fc'\" tells the compiler to enable the \"fc\" function, which implements Unicode\ncasefolding.\n\nSee \"fc\" in perlfunc for details.\n\nThis feature is available from Perl 5.16 onwards.\n\nThe 'lexicalsubs' feature\nIn Perl versions prior to 5.26, this feature enabled declaration of subroutines via \"my sub\nfoo\", \"state sub foo\" and \"our sub foo\" syntax. See \"Lexical Subroutines\" in perlsub for\ndetails.\n\nThis feature is available from Perl 5.18 onwards. From Perl 5.18 to 5.24, it was classed as\nexperimental, and Perl emitted a warning for its usage, except when explicitly disabled:\n\nno warnings \"experimental::lexicalsubs\";\n\nAs of Perl 5.26, use of this feature no longer triggers a warning, though the\n\"experimental::lexicalsubs\" warning category still exists (for compatibility with code that\ndisables it). In addition, this syntax is not only no longer experimental, but it is enabled\nfor all Perl code, regardless of what feature declarations are in scope.\n\nThe 'postderef' and 'postderefqq' features\nThe 'postderefqq' feature extends the applicability of postfix dereference syntax so that\npostfix array and scalar dereference are available in double-quotish interpolations. For\nexample, it makes the following two statements equivalent:\n\nmy $s = \"[@{ $h->{a} }]\";\nmy $s = \"[$h->{a}->@*]\";\n\nThis feature is available from Perl 5.20 onwards. In Perl 5.20 and 5.22, it was classed as\nexperimental, and Perl emitted a warning for its usage, except when explicitly disabled:\n\nno warnings \"experimental::postderef\";\n\nAs of Perl 5.24, use of this feature no longer triggers a warning, though the\n\"experimental::postderef\" warning category still exists (for compatibility with code that\ndisables it).\n\nThe 'postderef' feature was used in Perl 5.20 and Perl 5.22 to enable postfix dereference\nsyntax outside double-quotish interpolations. In those versions, using it triggered the\n\"experimental::postderef\" warning in the same way as the 'postderefqq' feature did. As of\nPerl 5.24, this syntax is not only no longer experimental, but it is enabled for all Perl\ncode, regardless of what feature declarations are in scope.\n" }, { "name": "The 'signatures' feature", "content": "WARNING: This feature is still experimental and the implementation may change or be removed\nin future versions of Perl. For this reason, Perl will warn when you use the feature, unless\nyou have explicitly disabled the warning:\n\nno warnings \"experimental::signatures\";\n\nThis enables unpacking of subroutine arguments into lexical variables by syntax such as\n\nsub foo ($left, $right) {\nreturn $left + $right;\n}\n\nSee \"Signatures\" in perlsub for details.\n\nThis feature is available from Perl 5.20 onwards.\n" }, { "name": "The 'refaliasing' feature", "content": "WARNING: This feature is still experimental and the implementation may change or be removed\nin future versions of Perl. For this reason, Perl will warn when you use the feature, unless\nyou have explicitly disabled the warning:\n\nno warnings \"experimental::refaliasing\";\n\nThis enables aliasing via assignment to references:\n\n\\$a = \\$b; # $a and $b now point to the same scalar\n\\@a = \\@b; # to the same array\n\\%a = \\%b;\n\\&a = \\&b;\nforeach \\%hash (@arrayofhashrefs) {\n...\n}\n\nSee \"Assigning to References\" in perlref for details.\n\nThis feature is available from Perl 5.22 onwards.\n" }, { "name": "The 'bitwise' feature", "content": "This makes the four standard bitwise operators (\"& | ^ ~\") treat their operands consistently\nas numbers, and introduces four new dotted operators (\"&. |. ^. ~.\") that treat their\noperands consistently as strings. The same applies to the assignment variants (\"&= |= ^= &.=\n|.= ^.=\").\n\nSee \"Bitwise String Operators\" in perlop for details.\n\nThis feature is available from Perl 5.22 onwards. Starting in Perl 5.28, \"use v5.28\" will\nenable the feature. Before 5.28, it was still experimental and would emit a warning in the\n\"experimental::bitwise\" category.\n\nThe 'declaredrefs' feature\nWARNING: This feature is still experimental and the implementation may change or be removed\nin future versions of Perl. For this reason, Perl will warn when you use the feature, unless\nyou have explicitly disabled the warning:\n\nno warnings \"experimental::declaredrefs\";\n\nThis allows a reference to a variable to be declared with \"my\", \"state\", our \"our\", or\nlocalized with \"local\". It is intended mainly for use in conjunction with the \"refaliasing\"\nfeature. See \"Declaring a Reference to a Variable\" in perlref for examples.\n\nThis feature is available from Perl 5.26 onwards.\n" }, { "name": "The 'isa' feature", "content": "WARNING: This feature is still experimental and the implementation may change or be removed\nin future versions of Perl. For this reason, Perl will warn when you use the feature, unless\nyou have explicitly disabled the warning:\n\nno warnings \"experimental::isa\";\n\nThis allows the use of the \"isa\" infix operator, which tests whether the scalar given by the\nleft operand is an object of the class given by the right operand. See \"Class Instance\nOperator\" in perlop for more details.\n\nThis feature is available from Perl 5.32 onwards.\n" }, { "name": "The 'indirect' feature", "content": "This feature allows the use of indirect object syntax for method calls, e.g. \"new Foo 1,\n2;\". It is enabled by default, but can be turned off to disallow indirect object syntax.\n\nThis feature is available under this name from Perl 5.32 onwards. In previous versions, it\nwas simply on all the time. To disallow (or warn on) indirect object syntax on older Perls,\nsee the indirect CPAN module.\n" }, { "name": "The 'multidimensional' feature", "content": "This feature enables multidimensional array emulation, a perl 4 (or earlier) feature that was\nused to emulate multidimensional arrays with hashes. This works by converting code like\n$foo{$x, $y} into $foo{join($;, $x, $y)}. It is enabled by default, but can be turned off to\ndisable multidimensional array emulation.\n\nWhen this feature is disabled the syntax that is normally replaced will report a compilation\nerror.\n\nThis feature is available under this name from Perl 5.34 onwards. In previous versions, it\nwas simply on all the time.\n\nYou can use the multidimensional module on CPAN to disable multidimensional array emulation\nfor older versions of Perl.\n\nThe 'barewordfilehandles' feature.\nThis feature enables bareword filehandles for builtin functions operations, a generally\ndiscouraged practice. It is enabled by default, but can be turned off to disable bareword\nfilehandles, except for the exceptions listed below.\n\nThe perl built-in filehandles \"STDIN\", \"STDOUT\", \"STDERR\", \"DATA\", \"ARGV\", \"ARGVOUT\" and the\nspecial \"\" are always enabled.\n\nThis feature is enabled under this name from Perl 5.34 onwards. In previous versions it was\nsimply on all the time.\n\nYou can use the bareword::filehandles module on CPAN to disable bareword filehandles for\nolder versions of perl.\n" }, { "name": "The 'try' feature.", "content": "WARNING: This feature is still experimental and the implementation may change or be removed\nin future versions of Perl. For this reason, Perl will warn when you use the feature, unless\nyou have explicitly disabled the warning:\n\nno warnings \"experimental::try\";\n\nThis feature enables the \"try\" and \"catch\" syntax, which allows exception handling, where\nexceptions thrown from the body of the block introduced with \"try\" are caught by executing\nthe body of the \"catch\" block.\n\nFor more information, see \"Try Catch Exception Handling\" in perlsyn.\n" } ] }, "FEATURE BUNDLES": { "content": "It's possible to load multiple features together, using a feature bundle. The name of a\nfeature bundle is prefixed with a colon, to distinguish it from an actual feature.\n\nuse feature \":5.10\";\n\nThe following feature bundles are available:\n\nbundle features included\n--------- -----------------\n:default indirect multidimensional\nbarewordfilehandles\n\n:5.10 barewordfilehandles indirect\nmultidimensional say state switch\n\n:5.12 barewordfilehandles indirect\nmultidimensional say state switch\nunicodestrings\n\n:5.14 barewordfilehandles indirect\nmultidimensional say state switch\nunicodestrings\n\n:5.16 barewordfilehandles currentsub evalbytes\nfc indirect multidimensional say state\nswitch unicodeeval unicodestrings\n\n:5.18 barewordfilehandles currentsub evalbytes\nfc indirect multidimensional say state\nswitch unicodeeval unicodestrings\n\n:5.20 barewordfilehandles currentsub evalbytes\nfc indirect multidimensional say state\nswitch unicodeeval unicodestrings\n\n:5.22 barewordfilehandles currentsub evalbytes\nfc indirect multidimensional say state\nswitch unicodeeval unicodestrings\n\n:5.24 barewordfilehandles currentsub evalbytes\nfc indirect multidimensional postderefqq\nsay state switch unicodeeval\nunicodestrings\n\n:5.26 barewordfilehandles currentsub evalbytes\nfc indirect multidimensional postderefqq\nsay state switch unicodeeval\nunicodestrings\n\n:5.28 barewordfilehandles bitwise currentsub\nevalbytes fc indirect multidimensional\npostderefqq say state switch unicodeeval\nunicodestrings\n\n:5.30 barewordfilehandles bitwise currentsub\nevalbytes fc indirect multidimensional\npostderefqq say state switch unicodeeval\nunicodestrings\n\n:5.32 barewordfilehandles bitwise currentsub\nevalbytes fc indirect multidimensional\npostderefqq say state switch unicodeeval\nunicodestrings\n\n:5.34 barewordfilehandles bitwise currentsub\nevalbytes fc indirect multidimensional\npostderefqq say state switch unicodeeval\nunicodestrings\n\nThe \":default\" bundle represents the feature set that is enabled before any \"use feature\" or\n\"no feature\" declaration.\n\nSpecifying sub-versions such as the 0 in 5.14.0 in feature bundles has no effect. Feature\nbundles are guaranteed to be the same for all sub-versions.\n\nuse feature \":5.14.0\"; # same as \":5.14\"\nuse feature \":5.14.1\"; # same as \":5.14\"\n", "subsections": [] }, "IMPLICIT LOADING": { "content": "Instead of loading feature bundles by name, it is easier to let Perl do implicit loading of a\nfeature bundle for you.\n\nThere are two ways to load the \"feature\" pragma implicitly:\n\n• By using the \"-E\" switch on the Perl command-line instead of \"-e\". That will enable the\nfeature bundle for that version of Perl in the main compilation unit (that is, the one-\nliner that follows \"-E\").\n\n• By explicitly requiring a minimum Perl version number for your program, with the \"use\nVERSION\" construct. That is,\n\nuse v5.10.0;\n\nwill do an implicit\n\nno feature ':all';\nuse feature ':5.10';\n\nand so on. Note how the trailing sub-version is automatically stripped from the version.\n\nBut to avoid portability warnings (see \"use\" in perlfunc), you may prefer:\n\nuse 5.010;\n\nwith the same effect.\n\nIf the required version is older than Perl 5.10, the \":default\" feature bundle is\nautomatically loaded instead.\n\nUnlike \"use feature \":5.12\"\", saying \"use v5.12\" (or any higher version) also does the\nequivalent of \"use strict\"; see \"use\" in perlfunc for details.\n\n\n\nperl v5.34.0 2025-07-25 feature(3perl)", "subsections": [] } } } }