view release on metacpan or  search on metacpan

lib/Lexical/Var.pm  view on Meta::CPAN

This module only manages variables of static duration (the kind of
duration that C<our> and C<state> variables have).  To get a fresh
variable for each invocation of a function, use C<my>.

=cut

package Lexical::Var;

{ use 5.006; }
use Lexical::SealRequireHints 0.006;
use warnings;
use strict;

our $VERSION = "0.009";

require XSLoader;
XSLoader::load(__PACKAGE__, $VERSION);

=head1 PACKAGE METHODS

These methods are meant to be invoked on the C<Lexical::Var> package.

=over

=item Lexical::Var->import(NAME => REF, ...)

Sets up lexical variable declarations, in the lexical environment that
is currently compiling.  Each I<NAME> must be a variable name (e.g.,
"B<$foo>") including sigil, and each I<REF> must be a reference to a
variable/value of the appropriate type.  The name is lexically associated
with the referenced variable/value.

L<Scalar::Construct> can be helpful in generating appropriate I<REF>s,
especially to create constants.  There are Perl core bugs to beware of
around compile-time constants; see L</BUGS>.

=item Lexical::Var->unimport(NAME [=> REF], ...)

Sets up negative lexical variable declarations, in the lexical environment
that is currently compiling.  Each I<NAME> must be a variable name
(e.g., "B<$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 I<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.

=back

=head1 BUGS

Subroutine invocations without the C<&> 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 C<+>,
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.
C<Lexical::Var> avoids contributing to the problem itself, but certain
ways of building the parameters to C<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.  L<Scalar::Construct> can be used to avoid this problem.

Bogus redefinition warnings occur in some cases when C<our> declarations
and C<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 C<import> or C<unimport> method is called from inside
a string C<eval> inside a C<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 C<require>d
or C<do>ed file causes the same problem
on the same Perl versions.  Other kinds of indirection
within a C<BEGIN> block, such as calling via a normal function, do not
cause this problem.

=head1 SEE ALSO

L<Attribute::Lexical>,
L<Lexical::Import>,
L<Lexical::Sub>,
L<Scalar::Construct>

=head1 AUTHOR

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