NAME

SYNOPSIS

        use Lexical::Import "Carp";

        use Lexical::Import qw(Time::HiRes time sleep);

        use Lexical::Import qw(Fcntl-1.01 :flock);

        use Lexical::Import (
                ["Carp"],
                [qw(Time::HiRes time sleep)],
                [qw(Fcntl-1.01 :flock)],
        );

DESCRIPTION

A lexically-imported item 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. Within its scope, any use of the single-part name of the item (e.g., "$foo") refers directly to that item, regardless of what is in any package. Explicitly package-qualified names (e.g., "$main::foo") still refer to the package. There is no conflict between a lexical name definition and the same name in any package.

This mechanism only works on Perl 5.11.2 and later. Prior to that, it is impossible for lexical subroutine imports to work for bareword subroutine calls. (See "BUGS" in Lexical::Var for details.) Other kinds of lexical importing are possible on earlier Perls, but because this is such a critical kind of usage in most code, this module will ensure that it works, for convenience. If the limited lexical importing is desired on earlier Perls, use Lexical::Var directly.

PACKAGE METHODS

Lexical::Import->import(MODULE_NAME, ARGS ...)

MODULE_NAME must be a Perl module name, in bareword syntax with "::" separators. The named module is loaded, and its "import" method is called with the supplied ARGS. It is expected to insert some set of functions and other items to the package from which its "import" method was called. Whatever scalars, arrays, hashes, and subroutines it thus exported are added to the lexical environment that is currently compiling.

The overall effect, when this is performed at compile time (usually via "use"), is that a "use" is performed on the MODULE_NAME and ARGS, with all of the module's package-based exporting being turned into lexical exporting. If the exporting module does some lexical exporting of its own, that will still work correctly when done by this indirect mechanism, but there is no point to the indirection if the exporting module uses lexical exporting exclusively.

Optionally, MODULE_NAME may be suffixed with a version number, separated from the module name by a ""-"". The version number must conform to the "strict" syntax (see version::Internals). If this is done, then after loading the module it will be checked that what was loaded is at least the specified version. For example, ""Fcntl-1.01"" requests the "Fcntl" module, version 1.01 or later. This check is actually performed by calling the "VERSION" method of the module, so the module can redefine it to have effects other than version checking, which some modules do even though it shows poor taste. Any items exported by "VERSION" into the calling package will be picked up and added to the lexical environment, just as if they had been exported by "import".

Optionally, MODULE_NAME may be prefixed with a ""-"", in which case the module's "unimport" method is called instead of "import". This effectively performs a "no" instead of a "use". This is meant to handle the few modules which, in poor taste, switch the conventional meanings of "use" and "no".

Lexical::Import->import(IMPORT_LIST, ...)

There must be one or more IMPORT_LIST, each of which is a reference to an array containing a MODULE_NAME and ARGS as described for the preceding form of "import". Each such list is processed in turn for importing. This is a shorthand for where several invocations of this module would otherwise be required.

Lexical::Import->unimport

Unimportation is not supported by this module, so this method just "die"s.

BUGS

If an exporting module does anything more complex than just inserting items into the calling package, this is liable to fail. For example, if it records the name of the calling package for some functional purpose then this won't work as intended: it will get the name of a temporary package that doesn't exist once the importing is complete.

If an exporting module tries to read a variable in the calling package, this will fail in two ways. Firstly, because it sees a temporary package, it won't pick up any variable from the real caller. Secondly, it is liable to bring the variable into existence (with an empty value), which looks like it exported the variable, so the empty variable will be lexically imported by the real caller.

Subroutine calls, to lexically-imported subroutines, 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.

If this package's "import" 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. 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

AUTHOR

COPYRIGHT

LICENSE