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.