NAME

Lexical::Import - clean imports from package-exporting modules

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

This module allows functions and other items, from a separate module, to be imported into the lexical namespace (as implemented by Lexical::Var), when the exporting module exports non-lexically to a package in the traditional manner. This is a translation layer, to help code written in the new way to use modules written in the old way.

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

These methods are meant to be invoked on the Lexical::Import package.

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

BUGS

Only scalars, arrays, hashes, and subroutines can be translated from the package namespace to the lexical namespace. If a module exports more exotic items, such as bareword I/O handles or formats, they will be lost.

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

Lexical::Var, Sub::Import

AUTHOR

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

COPYRIGHT

Copyright (C) 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.