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

NAME

6       Lexical::Var - static variables without namespace pollution
7

SYNOPSIS

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

DESCRIPTION

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
21       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
33       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
41       you must use the "&" sigil, as in ""&foo(123)"".
42
43       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
49       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.  These lexical definitions propagate into string "eval"s,
55       on Perl versions that support it (5.9.3 and later).
56
57       This module only manages variables of static duration (the kind of
58       duration that "our" and "state" variables have).  To get a fresh
59       variable for each invocation of a function, use "my".
60

PACKAGE METHODS

62       These methods are meant to be invoked on the "Lexical::Var" package.
63
64       Lexical::Var->import(NAME => REF, ...)
65           Sets up lexical variable declarations, in the lexical environment
66           that is currently compiling.  Each NAME must be a variable name
67           (e.g., "$foo") including sigil, and each REF must be a reference to
68           a variable/value of the appropriate type.  The name is lexically
69           associated with the referenced variable/value.
70
71           Scalar::Construct can be helpful in generating appropriate REFs,
72           especially to create constants.  There are Perl core bugs to beware
73           of around compile-time constants; see "BUGS".
74
75       Lexical::Var->unimport(NAME [=> REF], ...)
76           Sets up negative lexical variable declarations, in the lexical
77           environment that is currently compiling.  Each NAME must be a
78           variable name (e.g., "$foo") including sigil.  If the name is given
79           on its own, it is lexically dissociated from any value.  Within the
80           resulting scope, the variable name will not be recognised.  If a
81           REF (which must be a reference to a value of the appropriate type)
82           is specified with a name, the name will be dissociated if and only
83           if it is currently associated with that value.
84

BUGS

86       Subroutine invocations without the "&" sigil cannot be correctly
87       processed on Perl versions earlier than 5.11.2.  This is because the
88       parser needs to look up the subroutine early, in order to let any
89       prototype affect parsing, and it looks up the subroutine by a different
90       mechanism than is used to generate the call op.  (Some forms of
91       sigilless call have other complications of a similar nature.)  If an
92       attempt is made to call a lexical subroutine via a bareword on an older
93       Perl, this module will probably still be able to intercept the call op,
94       and will throw an exception to indicate that the parsing has gone
95       wrong.  However, in some cases compilation goes further wrong before
96       this module can catch it, resulting in either a confusing parse error
97       or (in rare situations) silent compilation to an incorrect op sequence.
98       On Perl 5.11.2 and later, sigilless subroutine calls work correctly,
99       except for an issue noted below.
100
101       Subroutine calls that have neither sigil nor parentheses (around the
102       argument list) are subject to an ambiguity with indirect object syntax.
103       If the first argument expression begins with a bareword or a scalar
104       variable reference then the Perl parser is liable to interpret the call
105       as an indirect method call.  Normally this syntax would be interpreted
106       as a subroutine call if the subroutine exists, but the parser doesn't
107       look at lexically-defined subroutines for this purpose.  The call
108       interpretation can be forced by prefixing the first argument expression
109       with a "+", or by wrapping the whole argument list in parentheses.
110
111       On Perls built for threading (even if threading is not actually used),
112       scalar constants that are defined by literals in the Perl source don't
113       reliably maintain their object identity.  What appear to be multiple
114       references to a single object can end up behaving as references to
115       multiple objects, in surprising ways.  The multiple objects all
116       initially have the correct value, but they can be writable even though
117       the original object is a constant.  See Perl bug reports [perl #109744]
118       and [perl #109746].  This can affect objects that are placed in the
119       lexical namespace, just as it can affect those in package namespaces or
120       elsewhere.  "Lexical::Var" avoids contributing to the problem itself,
121       but certain ways of building the parameters to "Lexical::Var" can
122       result in the object in the lexical namespace not being the one that
123       was intended, or can damage the named object so that later referencing
124       operations on it misbehave.  Scalar::Construct can be used to avoid
125       this problem.
126
127       Bogus redefinition warnings occur in some cases when "our" declarations
128       and "Lexical::Var" declarations shadow each other.
129
130       Package hash entries get created for subroutine and glob names that are
131       used, even though the subroutines and globs are not actually being
132       stored or looked up in the package.  This can occasionally result in a
133       "used only once" warning failing to occur when it should.
134
135       On Perls prior to 5.15.5, if this package's "import" or "unimport"
136       method is called from inside a string "eval" inside a "BEGIN" block, it
137       does not have proper access to the compiling environment, and will
138       complain that it is being invoked outside compilation.  Calling from
139       the body of a "require"d or "do"ed file causes the same problem on the
140       same Perl versions.  Other kinds of indirection within a "BEGIN" block,
141       such as calling via a normal function, do not cause this problem.
142

SEE ALSO

144       Attribute::Lexical, Lexical::Import, Lexical::Sub, Scalar::Construct
145

AUTHOR

147       Andrew Main (Zefram) <zefram@fysh.org>
148
150       Copyright (C) 2009, 2010, 2011, 2012, 2013 Andrew Main (Zefram)
151       <zefram@fysh.org>
152

LICENSE

154       This module is free software; you can redistribute it and/or modify it
155       under the same terms as Perl itself.
156
157
158
159perl v5.34.0                      2021-07-22                   Lexical::Var(3)
Impressum