Lexical::Util - utilities for lexical item manipulation

	use Lexical::Util qw(frame_to_cvref lexalias ref_to_lexical);

	$cvref = frame_to_cvref($level);
	lexalias($cvref, '$name', \$variable);
	$err = lexical_alias($cvref, '$name', \$variable);
	$ref = ref_to_lexical($cvref, '$name');

Lexical::Util is a module containing some common routines used by modules dealing with the lexical variables of routines other than their own. They are taken from various sources, including PadWalker, Perl6::Binding, and Lexical::Alias. This module is used in version 0.7 and greater of Perl6::Binding, as well as in the Object::Variables (Object::Variables) and Sub::Declaration (Sub::Declaration) packages, to prevent duplication of code.

This package should not be needed or used by end users.

Note: this module uses the CvPADLIST (CvPADLIST in perlintern) and CvDEPTH macros, which are listed in perlintern (perlintern) and not part of the perl API. They work in the versions I've been able to test on (5.6.1 and 5.8.4), but may change in the future. To avoid possible problems, this module tests to see that the Perl version is less than 5.9.0.

Nothing is exported by default, but you can request the following:

frame_to_cvref

$cvref = frame_to_cvref($level);

Finds the code reference (subroutine) for the stack frame indicated by $level, which is similar to the argument for caller in perlfunc. If the return value is true, the function succeeded.

lexalias

lexalias($cvref, '$name', \$value);

Creates a lexical alias for a variable called $name pointing to the variable $value. $cvref is a code reference returned by "frame_to_cvref". If $cvref is undef, this routine dies.

lexical_alias

$errmsg = lexical_alias($cvref, '$name', \$value);

Same as above, but instead of dying on error, it returns an error message. If the return value is false, the function succeeded. This can allow more useful error messages from modules that call it.

ref_to_lexical

$ref = ref_to_lexical($cvref, '$name');

Returns a reference to the named lexical variable in the specified stack frame. $cvref is a code reference returned by "frame_to_cvref". If $cvref is undef or the specified name isn't found, this routine dies.

• If $cvref is the scalar 0, then lexalias must have been called from the top level of the program (outside of any subroutines) and the variable being aliased must also exist at the top level. This doesn't appear to work under the debugger, however. I hope to eliminate this restriction with more research.

Perl6::Binding, PadWalker, Lexical::Alias

Copyright 2004 Kevin Michael Vail

This program is free software. It may be copied and/or redistributed under the same terms as Perl itself.

Kevin Michael Vail <kvail@cpan.org>