1Lexical::Var(3pm) User Contributed Perl Documentation Lexical::Var(3pm)
2
6 Lexical::Var - static variables without namespace pollution
7
9 use Lexical::Var '$foo' => \$Remote::foo;
10 use Lexical::Var '$const' => \123;
11 use Lexical::Var '@bar' => [];
12 use Lexical::Var '%baz' => { a => 1, b => 2 };
13 use Lexical::Var '&quux' => sub { $_[0] + 1 };
14 use Lexical::Var '*wibble' => Symbol::gensym();
15
17 This module implements lexical scoping of static variables and
18 subroutines. Although it can be used directly, it is mainly intended
19 to be infrastructure for modules that manage namespaces.
20 This module influences the meaning of single-part variable names that
22 appear directly in code, such as "$foo". Normally, in the absence of
23 any particular declaration, or under the effect of an "our"
24 declaration, this would refer to the scalar variable of that name
25 located in the current package. A "Lexical::Var" declaration can
26 change this to refer to any particular scalar, bypassing the package
27 system entirely. A variable name that includes an explicit package
28 part, such as "$main::foo", always refers to the variable in the
29 specified package, and is unaffected by this module. A symbolic
30 reference through a string value, such as ""${'foo'}"", also looks in
31 the package system, and so is unaffected by this module.
32 The types of name that can be influenced are scalar ("$foo"), array
34 ("@foo"), hash ("%foo"), subroutine ("&foo"), and glob ("*foo"). A
35 definition for any of these names also affects code that logically
36 refers to the same entity, even when the name is spelled without its
37 usual sigil. For example, any definition of "@foo" affects element
38 references such as "$foo[0]". Barewords in filehandle context actually
39 refer to the glob variable. Bareword references to subroutines, such
40 as "foo(123)", only work on Perl 5.11.2 and later; on earlier Perls you
41 must use the "&" sigil, as in "&foo(123)".
42 Where a scalar name is defined to refer to a constant (read-only)
44 scalar, references to the constant through the lexical namespace can
45 participate in compile-time constant folding. This can avoid the need
46 to check configuration values (such as whether debugging is enabled) at
47 runtime.
48 A name definition supplied by this module takes effect from the end of
50 the definition statement up to the end of the immediately enclosing
51 block, except where it is shadowed within a nested block. This is the
52 same lexical scoping that the "my", "our", and "state" keywords supply.
53 Definitions from Lexical::Var and from "my"/"our"/"state" can shadow
54 each other (except that Lexical::Var can't shadow a "my"/"our"/"state"
55 subroutine prior to Perl 5.19.1). These lexical definitions propagate
56 into string "eval"s, on Perl versions that support it (5.9.3 and
57 later).
58 This module only manages variables of static duration (the kind of
60 duration that "our" and "state" variables have). To get a fresh
61 variable for each invocation of a function, use "my".
62
64 These methods are meant to be invoked on the "Lexical::Var" package.
65 Lexical::Var->import(NAME => REF, ...)
67 Sets up lexical variable declarations, in the lexical environment
68 that is currently compiling. Each NAME must be a variable name
69 (e.g., "$foo") including sigil, and each REF must be a reference to
70 a variable/value of the appropriate type. The name is lexically
71 associated with the referenced variable/value.
72 Scalar::Construct can be helpful in generating appropriate REFs,
74 especially to create constants. There are Perl core bugs to beware
75 of around compile-time constants; see "BUGS".
76 Lexical::Var->unimport(NAME [=> REF], ...)
78 Sets up negative lexical variable declarations, in the lexical
79 environment that is currently compiling. Each NAME must be a
80 variable name (e.g., "$foo") including sigil. If the name is given
81 on its own, it is lexically dissociated from any value. Within the
82 resulting scope, the variable name will not be recognised. If a
83 REF (which must be a reference to a value of the appropriate type)
84 is specified with a name, the name will be dissociated if and only
85 if it is currently associated with that value.
86
88 Subroutine invocations without the "&" sigil cannot be correctly
89 processed on Perl versions earlier than 5.11.2. This is because the
90 parser needs to look up the subroutine early, in order to let any
91 prototype affect parsing, and it looks up the subroutine by a different
92 mechanism than is used to generate the call op. (Some forms of
93 sigilless call have other complications of a similar nature.) If an
94 attempt is made to call a Lexical::Var lexical subroutine via a
95 bareword on an older Perl, this module will probably still be able to
96 intercept the call op, and will throw an exception to indicate that the
97 parsing has gone wrong. However, in some cases compilation goes
98 further wrong before this module can catch it, resulting in either a
99 confusing parse error or (in rare situations) silent compilation to an
100 incorrect op sequence. On Perl 5.11.2 and later, sigilless subroutine
101 calls work correctly, except for an issue noted below.
102 Subroutine calls that have neither sigil nor parentheses (around the
104 argument list) are subject to an ambiguity with indirect object syntax.
105 If the first argument expression begins with a bareword or a scalar
106 variable reference then the Perl parser is liable to interpret the call
107 as an indirect method call. Normally this syntax would be interpreted
108 as a subroutine call if the subroutine exists, but the parser doesn't
109 look at lexically-defined subroutines for this purpose. The call
110 interpretation can be forced by prefixing the first argument expression
111 with a "+", or by wrapping the whole argument list in parentheses.
112 In the earlier Perl versions that support "my"/"our"/"state"
114 subroutines, starting from Perl 5.17.4, the mechanism for core lexical
115 subroutines suffers a couple of bugs that mean that Lexical::Var can't
116 shadow subroutines declared that way. This was fixed in Perl 5.19.1.
117 On Perls built for threading (even if threading is not actually used),
119 scalar constants that are defined by literals in the Perl source don't
120 reliably maintain their object identity. What appear to be multiple
121 references to a single object can end up behaving as references to
122 multiple objects, in surprising ways. The multiple objects all
123 initially have the correct value, but they can be writable even though
124 the original object is a constant. See Perl bug reports [perl #109744]
125 and [perl #109746]. This can affect objects that are placed in the
126 lexical namespace, just as it can affect those in package namespaces or
127 elsewhere. "Lexical::Var" avoids contributing to the problem itself,
128 but certain ways of building the parameters to "Lexical::Var" can
129 result in the object in the lexical namespace not being the one that
130 was intended, or can damage the named object so that later referencing
131 operations on it misbehave. Scalar::Construct can be used to avoid
132 this problem.
133 Bogus redefinition warnings occur in some cases when "our" declarations
135 and "Lexical::Var" declarations shadow each other.
136 Package hash entries get created for subroutine and glob names that are
138 used, even though the subroutines and globs are not actually being
139 stored or looked up in the package. This can occasionally result in a
140 "used only once" warning failing to occur when it should.
141 On Perls prior to 5.15.5, if this package's "import" or "unimport"
143 method is called from inside a string "eval" inside a "BEGIN" block, it
144 does not have proper access to the compiling environment, and will
145 complain that it is being invoked outside compilation. Calling from
146 the body of a "require"d or "do"ed file causes the same problem on the
147 same Perl versions. Other kinds of indirection within a "BEGIN" block,
148 such as calling via a normal function, do not cause this problem.
149 When judging whether the "unimport" method should hide a subroutine,
151 this module can't distinguish between a lexical subroutine established
152 by this module and a "state" subroutine. This may change in the
153 future.
154
156 Attribute::Lexical, Lexical::Import, Lexical::Sub, Scalar::Construct
157
159 Andrew Main (Zefram) <zefram@fysh.org>
160
162 Copyright (C) 2009, 2010, 2011, 2012, 2013, 2023 Andrew Main (Zefram)
163 <zefram@fysh.org>
164
166 This module is free software; you can redistribute it and/or modify it
167 under the same terms as Perl itself.
168perl v5.38.0 2023-07-20 Lexical::Var(3pm)