NAME¶
Lexical::Sub - subroutines without namespace pollution
SYNOPSIS¶
use Lexical::Sub quux => sub { $_[0] + 1 };
use Lexical::Sub carp => \&Carp::carp;
DESCRIPTION¶
This module implements lexical scoping of subroutines. Although it can be used
directly, it is mainly intended to be infrastructure for modules that manage
namespaces.
This module influences the meaning of single-part subroutine names that appear
directly in code, such as "&foo" and
""foo(123)"". Normally, in the absence of any particular
declaration, these would refer to the subroutine of that name located in the
current package. A "Lexical::Sub" declaration can change this to
refer to any particular subroutine, bypassing the package system entirely. A
subroutine name that includes an explicit package part, such as
"&main::foo", always refers to the subroutine in the specified
package, and is unaffected by this module. A symbolic reference through a
string value, such as ""&{'foo'}"", also looks in the
package system, and so is unaffected by this module.
Bareword references to subroutines, such as ""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 takes effect from the end of the
definition statement up to the end of the immediately enclosing block, except
where it is shadowed within a nested block. This is the same lexical scoping
that the "my", "our", and "state" keywords
supply. These lexical definitions propagate into string "eval"s, on
Perl versions that support it (5.9.3 and later).
This module is implemented through the mechanism of Lexical::Var. Its distinct
name and declaration syntax exist to make lexical subroutine declarations
clearer.
PACKAGE METHODS¶
These methods are meant to be invoked on the "Lexical::Sub" package.
- 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 is lexically associated with the referenced
subroutine.
- 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. Within the
resulting scope, the subroutine name will not be recognised. 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.
BUGS¶
Subroutine invocations without the "&" sigil cannot be correctly
processed on Perl versions earlier than 5.11.2. This is 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 is used
to generate the call op. (Some forms of sigilless call have other
complications of a similar nature.) If an attempt is made to call a 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.
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. The call interpretation can be forced by
prefixing the first argument expression with a "+", or by wrapping
the whole argument list in parentheses.
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.
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 "require"d or
"do"ed 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.
SEE ALSO¶
Lexical::Import, Lexical::Var
AUTHOR¶
Andrew Main (Zefram) <zefram@fysh.org>
COPYRIGHT¶
Copyright (C) 2009, 2010, 2011, 2012, 2013 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.