1Lexical::Sub(3)       User Contributed Perl Documentation      Lexical::Sub(3)
2
3
4

NAME

6       Lexical::Sub - subroutines without namespace pollution
7

SYNOPSIS

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

DESCRIPTION

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
17       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
29       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
33       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       These lexical definitions propagate into string "eval"s, on Perl
38       versions that support it (5.9.3 and later).
39
40       This module is implemented through the mechanism of Lexical::Var.  Its
41       distinct name and declaration syntax exist to make lexical subroutine
42       declarations clearer.
43

PACKAGE METHODS

45       These methods are meant to be invoked on the "Lexical::Sub" package.
46
47       Lexical::Sub->import(NAME => REF, ...)
48           Sets up lexical subroutine declarations, in the lexical environment
49           that is currently compiling.  Each NAME must be a bare subroutine
50           name (e.g., "foo"), and each REF must be a reference to a
51           subroutine.  The name is lexically associated with the referenced
52           subroutine.
53
54       Lexical::Sub->unimport(NAME [=> REF], ...)
55           Sets up negative lexical subroutine declarations, in the lexical
56           environment that is currently compiling.  Each NAME must be a bare
57           subroutine name (e.g., "foo").  If the name is given on its own, it
58           is lexically dissociated from any subroutine.  Within the resulting
59           scope, the subroutine name will not be recognised.  If a REF (which
60           must be a reference to a subroutine) is specified with a name, the
61           name will be dissociated if and only if it is currently associated
62           with that subroutine.
63

BUGS

65       Subroutine invocations without the "&" sigil cannot be correctly
66       processed on Perl versions earlier than 5.11.2.  This is because the
67       parser needs to look up the subroutine early, in order to let any
68       prototype affect parsing, and it looks up the subroutine by a different
69       mechanism than is used to generate the call op.  (Some forms of
70       sigilless call have other complications of a similar nature.)  If an
71       attempt is made to call a lexical subroutine via a bareword on an older
72       Perl, this module will probably still be able to intercept the call op,
73       and will throw an exception to indicate that the parsing has gone
74       wrong.  However, in some cases compilation goes further wrong before
75       this module can catch it, resulting in either a confusing parse error
76       or (in rare situations) silent compilation to an incorrect op sequence.
77       On Perl 5.11.2 and later, sigilless subroutine calls work correctly,
78       except for an issue noted below.
79
80       Subroutine calls that have neither sigil nor parentheses (around the
81       argument list) are subject to an ambiguity with indirect object syntax.
82       If the first argument expression begins with a bareword or a scalar
83       variable reference then the Perl parser is liable to interpret the call
84       as an indirect method call.  Normally this syntax would be interpreted
85       as a subroutine call if the subroutine exists, but the parser doesn't
86       look at lexically-defined subroutines for this purpose.  The call
87       interpretation can be forced by prefixing the first argument expression
88       with a "+", or by wrapping the whole argument list in parentheses.
89
90       Package hash entries get created for subroutine names that are used,
91       even though the subroutines are not actually being stored or looked up
92       in the package.  This can occasionally result in a "used only once"
93       warning failing to occur when it should.
94
95       On Perls prior to 5.15.5, if this package's "import" or "unimport"
96       method is called from inside a string "eval" inside a "BEGIN" block, it
97       does not have proper access to the compiling environment, and will
98       complain that it is being invoked outside compilation.  Calling from
99       the body of a "require"d or "do"ed file causes the same problem on the
100       same Perl versions.  Other kinds of indirection within a "BEGIN" block,
101       such as calling via a normal function, do not cause this problem.
102

SEE ALSO

104       Lexical::Import, Lexical::Var
105

AUTHOR

107       Andrew Main (Zefram) <zefram@fysh.org>
108
110       Copyright (C) 2009, 2010, 2011, 2012, 2013 Andrew Main (Zefram)
111       <zefram@fysh.org>
112

LICENSE

114       This module is free software; you can redistribute it and/or modify it
115       under the same terms as Perl itself.
116
117
118
119perl v5.34.0                      2022-01-21                   Lexical::Sub(3)
Impressum