/ 
Lexical-Util-0.8
River stage zero No dependents
/ Lexical::Util

NAME

Lexical::Util - utilities for lexical item manipulation

SYNOPSIS

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');

DESCRIPTION

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 and 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 and CvDEPTH macros, which are listed in 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.

EXPORTABLE ROUTINES

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.

KNOWN ISSUES

  • 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.

SEE ALSO

Perl6::Binding, PadWalker, Lexical::Alias

COPYRIGHT AND LICENSE

Copyright 2004 Kevin Michael Vail

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

AUTHOR

Kevin Michael Vail <kvail@cpan.org>