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 export particular objects.

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 cannot currently be handled by this module.

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 evals, 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.

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.

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.

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 required or doed file causes the same problem. Other kinds of indirection within a BEGIN block, such as calling via a normal function, do not cause this problem. Ultimately this is a problem with the Perl core, and may change in a future version.

SEE ALSO

Attribute::Lexical, Lexical::Import, Lexical::Sub

AUTHOR

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

COPYRIGHT

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