Ubuntu Manpage: Lexical::Var - static variables without namespace pollution

Provided by: liblexical-var-perl_0.010-1build3_amd64

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 (except that Lexical::Var can't shadow a
       "my"/"our"/"state" subroutine prior to Perl 5.19.1).  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::Var 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.

In the earlier Perl versions that support "my"/"our"/"state" subroutines, starting from Perl 5.17.4, the
mechanism for core lexical subroutines suffers a couple of bugs that mean that Lexical::Var can't shadow
subroutines declared that way. This was fixed in Perl 5.19.1.

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.

When judging whether the "unimport" method should hide a subroutine, this module can't distinguish
between a lexical subroutine established by this module and a "state" subroutine. This may change in the
future.

AUTHOR

       Andrew Main (Zefram) <zefram@fysh.org>

COPYRIGHT

       Copyright (C) 2009, 2010, 2011, 2012, 2013, 2023 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.

perl v5.38.2                                       2024-03-31                                  Lexical::Var(3pm)