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