NAME¶
Lexical::Var - static variables without namespace pollution
SYNOPSIS¶
use Lexical::Var '$foo' => \$Remote::foo;
use Lexical::Var '$const' => \123;
use Lexical::Var '@bar' => [];
use Lexical::Var '%baz' => { a => 1, b => 2 };
use Lexical::Var '&quux' => sub { $_[0] + 1 };
use Lexical::Var '*wibble' => Symbol::gensym();
DESCRIPTION¶
This module implements lexical scoping of static variables and 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 variable names that appear
directly in code, such as "$foo". Normally, in the absence of any
particular declaration, or under the effect of an "our" declaration,
this would refer to the scalar variable of that name located in the current
package. A "Lexical::Var" declaration can change this to refer to
any particular scalar, bypassing the package system entirely. A variable name
that includes an explicit package part, such as "$main::foo", always
refers to the variable 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.
The types of name that can be influenced are scalar ("$foo"), array
("@foo"), hash ("%foo"), subroutine
("&foo"), and glob ("*foo"). A definition for any of
these names also affects code that logically refers to the same entity, even
when the name is spelled without its usual sigil. For example, any definition
of "@foo" affects element references such as "$foo[0]".
Barewords in filehandle context actually refer to the glob variable. 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)"".
Where a scalar name is defined to refer to a constant (read-only) scalar,
references to the constant through the lexical namespace can participate in
compile-time constant folding. This can avoid the need to check configuration
values (such as whether debugging is enabled) at runtime.
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. Definitions from Lexical::Var and from
"my"/"our"/"state" can shadow each other. These
lexical definitions propagate into string "eval"s, on Perl versions
that support it (5.9.3 and later).
This module only manages variables of static duration (the kind of duration that
"our" and "state" variables have). To get a fresh variable
for each invocation of a function, use "my".
PACKAGE METHODS¶
These methods are meant to be invoked on the "Lexical::Var" package.
- Lexical::Var->import(NAME => REF, ...)
- Sets up lexical variable declarations, in the lexical environment that is
currently compiling. Each NAME must be a variable name (e.g.,
" $foo") including sigil, and each
REF must be a reference to a variable/value of the appropriate
type. The name is lexically associated with the referenced variable/value.
Scalar::Construct can be helpful in generating appropriate REFs,
especially to create constants. There are Perl core bugs to beware of
around compile-time constants; see "BUGS".
- Lexical::Var->unimport(NAME [=> REF], ...)
- Sets up negative lexical variable declarations, in the lexical environment
that is currently compiling. Each NAME must be a variable name
(e.g., " $foo") including sigil. If the
name is given on its own, it is lexically dissociated from any value.
Within the resulting scope, the variable name will not be recognised. If a
REF (which must be a reference to a value of the appropriate type)
is specified with a name, the name will be dissociated if and only if it
is currently associated with that value.
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.
On Perls built for threading (even if threading is not actually used), scalar
constants that are defined by literals in the Perl source don't reliably
maintain their object identity. What appear to be multiple references to a
single object can end up behaving as references to multiple objects, in
surprising ways. The multiple objects all initially have the correct value,
but they can be writable even though the original object is a constant. See
Perl bug reports [perl #109744] and [perl #109746]. This can affect objects
that are placed in the lexical namespace, just as it can affect those in
package namespaces or elsewhere. "Lexical::Var" avoids contributing
to the problem itself, but certain ways of building the parameters to
"Lexical::Var" can result in the object in the lexical namespace not
being the one that was intended, or can damage the named object so that later
referencing operations on it misbehave. Scalar::Construct can be used to avoid
this problem.
Bogus redefinition warnings occur in some cases when "our"
declarations and "Lexical::Var" declarations shadow each other.
Package hash entries get created for subroutine and glob names that are used,
even though the subroutines and globs 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¶
Attribute::Lexical, Lexical::Import, Lexical::Sub, Scalar::Construct
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.
