1Lexical::Sub(3pm) User Contributed Perl Documentation Lexical::Sub(3pm)
2
6 Lexical::Sub - subroutines without namespace pollution
7
9 use Lexical::Sub quux => sub { $_[0] + 1 };
10 use Lexical::Sub carp => \&Carp::carp;
11
13 This module implements lexical scoping of subroutines. Although it can
14 be used directly, it is mainly intended to be infrastructure for
15 modules that manage namespaces.
16 This module influences the meaning of single-part subroutine names that
18 appear directly in code, such as "&foo" and "foo(123)". Normally, in
19 the absence of any particular declaration, these would refer to the
20 subroutine of that name located in the current package. A
21 "Lexical::Sub" declaration can change this to refer to any particular
22 subroutine, bypassing the package system entirely. A subroutine name
23 that includes an explicit package part, such as "&main::foo", always
24 refers to the subroutine in the specified package, and is unaffected by
25 this module. A symbolic reference through a string value, such as
26 ""&{'foo'}"", also looks in the package system, and so is unaffected by
27 this module.
28 Bareword references to subroutines, such as "foo(123)", only work on
30 Perl 5.11.2 and later. On earlier Perls you must use the "&" sigil, as
31 in "&foo(123)".
32 A name definition supplied by this module takes effect from the end of
34 the definition statement up to the end of the immediately enclosing
35 block, except where it is shadowed within a nested block. This is the
36 same lexical scoping that the "my", "our", and "state" keywords supply.
37 Definitions from Lexical::Sub and from "my"/"our"/"state" can shadow
38 each other, on Perl versions where these duration keywords can be
39 applied to subroutines (5.17.4 and later), except that Lexical::Sub
40 can't shadow a "my"/"our"/"state" subroutine prior to Perl 5.19.1.
41 These lexical definitions propagate into string "eval"s, on Perl
42 versions that support it (5.9.3 and later).
43 This module only manages subroutines of static duration (the kind of
45 duration that subroutines declared without "my" have). To get a fresh
46 subroutine for each invocation of a function, use "my sub", on a Perl
47 version that supports it (5.17.4 and later).
48 This module is implemented through the mechanism of Lexical::Var. Its
50 distinct name and declaration syntax exist to make Lexical::Var lexical
51 subroutine declarations clearer.
52
54 These methods are meant to be invoked on the "Lexical::Sub" package.
55 Lexical::Sub->import(NAME => REF, ...)
57 Sets up lexical subroutine declarations, in the lexical environment
58 that is currently compiling. Each NAME must be a bare subroutine
59 name (e.g., "foo"), and each REF must be a reference to a
60 subroutine. The name is lexically associated with the referenced
61 subroutine.
62 Lexical::Sub->unimport(NAME [=> REF], ...)
64 Sets up negative lexical subroutine declarations, in the lexical
65 environment that is currently compiling. Each NAME must be a bare
66 subroutine name (e.g., "foo"). If the name is given on its own, it
67 is lexically dissociated from any subroutine. Within the resulting
68 scope, the subroutine name will not be recognised. If a REF (which
69 must be a reference to a subroutine) is specified with a name, the
70 name will be dissociated if and only if it is currently associated
71 with that subroutine.
72
74 Subroutine invocations without the "&" sigil cannot be correctly
75 processed on Perl versions earlier than 5.11.2. This is because the
76 parser needs to look up the subroutine early, in order to let any
77 prototype affect parsing, and it looks up the subroutine by a different
78 mechanism than is used to generate the call op. (Some forms of
79 sigilless call have other complications of a similar nature.) If an
80 attempt is made to call a Lexical::Sub lexical subroutine via a
81 bareword on an older Perl, this module will probably still be able to
82 intercept the call op, and will throw an exception to indicate that the
83 parsing has gone wrong. However, in some cases compilation goes
84 further wrong before this module can catch it, resulting in either a
85 confusing parse error or (in rare situations) silent compilation to an
86 incorrect op sequence. On Perl 5.11.2 and later, sigilless subroutine
87 calls work correctly, except for an issue noted below.
88 Subroutine calls that have neither sigil nor parentheses (around the
90 argument list) are subject to an ambiguity with indirect object syntax.
91 If the first argument expression begins with a bareword or a scalar
92 variable reference then the Perl parser is liable to interpret the call
93 as an indirect method call. Normally this syntax would be interpreted
94 as a subroutine call if the subroutine exists, but the parser doesn't
95 look at lexically-defined subroutines for this purpose. The call
96 interpretation can be forced by prefixing the first argument expression
97 with a "+", or by wrapping the whole argument list in parentheses.
98 In the earlier Perl versions that support "my"/"our"/"state"
100 subroutines, starting from Perl 5.17.4, the mechanism for core lexical
101 subroutines suffers a couple of bugs that mean that Lexical::Sub can't
102 shadow subroutines declared that way. This was fixed in Perl 5.19.1.
103 Package hash entries get created for subroutine names that are used,
105 even though the subroutines are not actually being stored or looked up
106 in the package. This can occasionally result in a "used only once"
107 warning failing to occur when it should.
108 On Perls prior to 5.15.5, if this package's "import" or "unimport"
110 method is called from inside a string "eval" inside a "BEGIN" block, it
111 does not have proper access to the compiling environment, and will
112 complain that it is being invoked outside compilation. Calling from
113 the body of a "require"d or "do"ed file causes the same problem on the
114 same Perl versions. Other kinds of indirection within a "BEGIN" block,
115 such as calling via a normal function, do not cause this problem.
116 When judging whether the "unimport" method should hide a subroutine,
118 this module can't distinguish between a lexical subroutine established
119 by this module and a "state" subroutine. This may change in the
120 future.
121
123 Lexical::Import, Lexical::Var
124
126 Andrew Main (Zefram) <zefram@fysh.org>
127
129 Copyright (C) 2009, 2010, 2011, 2012, 2013, 2023 Andrew Main (Zefram)
130 <zefram@fysh.org>
131
133 This module is free software; you can redistribute it and/or modify it
134 under the same terms as Perl itself.
135perl v5.38.0 2023-07-20 Lexical::Sub(3pm)