Lexical::Sub(3pm)

🦋 NAME 🦋

Lexical::Sub — subroutines without namespace pollution 💅

(also known, in the sacred scrolls of User Contributed Perl Documentation, as Lexical::Sub(3pm) ✨)

---

🌸 SYNOPSIS 🌸

use Lexical::Sub quux => sub { $_[0] + 1 };
use Lexical::Sub carp => \&Carp::carp;

that's IT bestie, that's the whole vibe 🫶

---

✨ DESCRIPTION ✨

okay so. this module is the girl who does lexical scoping of subroutines. yes you can use it directly, but honestly its main character energy is being infrastructure for other modules that manage namespaces. iykyk 👑

what it actually does: it messes with (affectionately) the meaning of single-part subroutine names that appear directly in code — stuff like &foo and foo(123). normally, if nobody's declared anything special, those would point at the subroutine of that name living in the current package. but a Lexical::Sub declaration can switch that up so the name refers to any particular subroutine you want, bypassing the package system entirely like it's not even there 😌

now listen. a subroutine name that includes an explicit package part, like &main::foo, always refers to the subroutine in the specified package. this module does not touch it. periodt. 🚫 and a symbolic reference through a string value, like "&{'foo'}", also looks in the package system, so it's equally unaffected. not your business, not our business.

bareword references to subroutines like foo(123) only work on Perl 5.11.2 and later. on earlier Perls you MUST use the & sigil, as in &foo(123).

a name definition supplied by this module kicks in from the end of the definition statement up to the end of the immediately enclosing block, except where it gets shadowed inside a nested block. it's literally the same lexical scoping that my, our, and state give you. iconic behavior 💖

definitions from Lexical::Sub and from my/our/state can shadow each other, on Perl versions where those duration keywords can be applied to subroutines (5.17.4 and later) — except that Lexical::Sub can't shadow a my/our/state subroutine prior to Perl 5.19.1. sorry bestie, rules are rules. 🙈

oh and these lexical definitions propagate into string evals, on Perl versions that support it (5.9.3 and later) 🧚

this module only manages subroutines of static duration — the kind of duration that subroutines declared without my have. if you want a fresh subroutine for each invocation of a function, use my sub, on a Perl version that supports it (5.17.4 and later). different tool, different slay ✨

under the hood: this module is implemented through the mechanism of Lexical::Var. its distinct name and declaration syntax exist to make Lexical::Var lexical subroutine declarations clearer. it's giving "i have my own name for branding reasons" 💅

---

🎀 PACKAGE METHODS 🎀

these methods are meant to be invoked on the Lexical::Sub package. come correct or don't come at all 🫶

• Lexical::Sub->import(NAME => REF, ...) — sets up lexical subroutine declarations, in the lexical environment that is currently compiling. each NAME must be a bare subroutine name (e.g., foo), and each REF must be a reference to a subroutine. the name gets lexically associated with the referenced subroutine. that's the whole deal 💖
• Lexical::Sub->unimport(NAME [=> REF], ...) — sets up negative lexical subroutine declarations, in the lexical environment that is currently compiling. each NAME must be a bare subroutine name (e.g., foo). if the name is given on its own, it is lexically dissociated from any subroutine — and within the resulting scope, that subroutine name will not be recognised. bye bestie 👋 if a REF (which must be a reference to a subroutine) is specified with a name, the name will be dissociated if and only if it is currently associated with that subroutine. conditional queen 💅

---

💀 BUGS 💀

buckle up, this section is the messy one 😭

• subroutine invocations without the & sigil cannot be correctly processed on Perl versions earlier than 5.11.2. why? because the parser needs to look up the subroutine early, in order to let any prototype affect parsing, and it looks up the subroutine by a different mechanism than the one used to generate the call op. (some forms of sigilless call have other complications of a similar nature.) if you try to call a Lexical::Sub lexical subroutine via a bareword on an older Perl, this module will probably still be able to intercept the call op, and will throw an exception to indicate that the parsing has gone wrong. however, in some cases compilation goes further wrong before this module can catch it, resulting in either a confusing parse error or — in rare situations — silent compilation to an incorrect op sequence. 💀 yeah. on Perl 5.11.2 and later, sigilless subroutine calls work correctly, except for an issue noted below.
• subroutine calls that have neither sigil nor parentheses (around the argument list) are subject to an ambiguity with indirect object syntax. if the first argument expression begins with a bareword or a scalar variable reference, then the Perl parser is liable to interpret the call as an indirect method call. normally this syntax would be interpreted as a subroutine call if the subroutine exists, but the parser doesn't look at lexically-defined subroutines for this purpose. you can force the call interpretation by prefixing the first argument expression with a +, or by wrapping the whole argument list in parentheses. 🙏
• in the earlier Perl versions that support my/our/state subroutines, starting from Perl 5.17.4, the mechanism for core lexical subroutines suffers a couple of bugs that mean Lexical::Sub can't shadow subroutines declared that way. this was fixed in Perl 5.19.1. glow up achieved ✨
• package hash entries get created for subroutine names that are used, even though the subroutines are not actually being stored or looked up in the package. this can occasionally result in a "used only once" warning failing to occur when it should. sneaky 😭
• on Perls prior to 5.15.5, if this package's import or unimport method is called from inside a string eval inside a BEGIN block, it does not have proper access to the compiling environment, and will complain that it is being invoked outside compilation. calling from the body of a required or doed file causes the same problem on the same Perl versions. other kinds of indirection within a BEGIN block, such as calling via a normal function, do not cause this problem. so specific fr fr 🙈
• when judging whether the unimport method should hide a subroutine, this module can't distinguish between a lexical subroutine established by this module and a state subroutine. this may change in the future. we'll see bestie, we'll see 👀

---

🌈 SEE ALSO 🌈

• Lexical::Import
• Lexical::Var

go read them, they're the extended universe 📚✨

---

👑 AUTHOR 👑

Andrew Main (Zefram) <zefram@fysh.org>

---

💜 COPYRIGHT 💜

Copyright (C) 2009, 2010, 2011, 2012, 2013, 2023 Andrew Main (Zefram) <zefram@fysh.org>

---

🍓 LICENSE 🍓

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

okay that's the whole page, you ate that 🫶💅✨ — this was Lexical::Sub, from the perl v5.42.3 docs, dated 2026-08-20. no cap. go write some lexically scoped subs, bestie 🌸🦋