Copyright Notice
This text is copyright by CMP Media, LLC, and is used with their permission. Further distribution or use is not permitted.This text has appeared in an edited form in Perl Journal magazine. However, the version you are reading here is as the author originally submitted the article for publication, not after their editors applied their creativity.
Please read all the information in the table of contents before using this article.
Perl Journal Column 13 (Jun 2004)
[Suggested title: ``Hey, 'use' guys! Import this!'']
Unless this is your first day of programming in Perl, I think it would
be safe to say that you've used use at least once, and probably
with some module that imports subroutines into your current package
namespace. Let's take a look at precisely how that works.
As an example, let's look at the LWP::Simple module. By default, having:
use LWP::Simple;
at the top of my program means I can safely invoke get, head,
getprint, getstore, and mirror, as well as a series of
HTTP::Status constants, treating them as if I had written the program
directly. I can narrow down that namespace pollution with a direct
specification of things to import:
use LWP::Simple qw(mirror RC_OK RC_NOT_MODIFIED);
And now I get only the mirror routine and its two likely return
statuses.
These invocations act as if I had included a BEGIN block wrapped
around a require operation followed by a method call. For example,
that latter invocation looks like this:
BEGIN {
require LWP::Simple;
LWP::Simple->import(qw(mirror RC_OK RC_NOT_MODIFIED));
}
Notice first that because it's a BEGIN block, we're talking about
an operation that happens at compile time, not deferred until runtime.
As the package name of LWP::Simple is fed to require, it is
converted into an appropriate directory/subdirectory path for the
architecture running the program, with a .pm extension
automatically tacked on, as if we had said:
require "LWP/Simple.pm";
on a Unix architecture machine.
Because we're using require, the @INC path is automatically
consulted to locate the file. By default, this includes the system
directories where Perl was installed, and the current directory. We
can alter the @INC path permanently by recompiling Perl, or
temporarily through a combination of setting the PERL5LIB
environment variable, adding a -I command-line switch, or preceding
this use with either a use lib setting or something else that
alters @INC at compile time.
Also, because we're using require, the .pm file must have a
true value as the last expression evaluated. This is typically provided
with a simple:
1;
at the end of the file, although if you were being perverse, you could change that to:
"this line intentionally left true";
or something else, as long as it was true.
Up to this point, we simply have a require operator that runs at
compile-time instead of run-time, with a consistent name-management
scheme to find the file. But the final step of use is the implicit
method call, and this is where we get our subroutine name imports.
A typical module brought in with use will define subroutines in the
package namespace appropriate to that module. For example,
LWP::Simple defines LWP::Simple::get, LWP::Simple::mirror,
and so on. The method call to import within LWP::Simple's class
causes these names to be aliased to their same name within the
invoker's namespace (typically main). This is the result of
LWP::Simple inheriting from Exporter, a core Perl module that
provides a relatively flexible and smart import method to handle
the aliasing.
This means that LWP::Simple, like most modules, begins with
something like:
package LWP::Simple; use base qw(Exporter);
or equivalently, but backward-compatible for fairly old Perl versions:
package LWP::Simple; use vars qw/@ISA/; require Exporter; @ISA = qw(Exporter);
But now we've just moved the problem around a bit. The author of
LWP::Simple doesn't have to write import, but
Exporter::import still needs to know what to do. The
Exporter::import routine looks at the @EXPORT and @EXPORT_OK
variables in the current package to determine the permitted exports.
For example, LWP::Simple starts with something like:
use vars qw(@EXPORT @EXPORT_OK); @EXPORT = qw(get head getprint getstore mirror); @EXPORT_OK = qw($ua);
This means that by default, the five subroutines are imported into the
caller's namespace. However, any specific list of imports must come
from all six names (everything in both @EXPORT and
@EXPORT_OK). (In truth, the exports of HTTP::Status are also
added to @EXPORT, but let's ignore them for a second.)
So, if I ask for:
use LWP::Simple;
I get the default list (everything in @EXPORT).
If I ask for just get and mirror explictly:
use LWP::Simple qw(get mirror);
then that's all I get. If I ask for something not in the list:
use LWP::Simple qw(head tail);
then Exporter::import aborts because tail is not one of
@EXPORT or @EXPORT_OK.
We can completely skip the invocation of import with an empty set of
parenthesis:
use LWP::Simple ();
The $ua member of @EXPORT_OK here is actually a package
variable, initially defined as $LWP::Simple::ua, but available for
import into my namespace. As a rule of thumb, generally it's better
to export behavior (subroutines or objects) rather than data
(variables), because once your data format is ``out there'', it's hard
to change it for future releases.
What if we want ``all the default, plus this one'' or ``all the default,
except for that one''? It turns out that Exporter::import is actually
fairly flexible. We can use:
use LWP::Simple qw(:DEFAULT $ua);
to mean ``all the default and $ua''. Similarly, we can use:
use LWP::Simple qw(:DEFAULT !getprint !getstore);
to mean ``all the default without these two listed names''. Additionally, we can use regular expressions, such as:
use LWP::Simple qw(:DEFAULT !/^get/);
to mean ``all the default without any name beginning with get''.
An expression that begins with ! appearing at the beginning
of the list implies a :DEFAULT ahead of it, so we can write that
last one more simply as:
use LWP::Simple qw(!/^get/);
We could even ask for:
use LWP::Simple qw(/^/);
to mean ``everything that can possibly be exported'' (because the regular
expression of /^/ matches all possible strings).
We can define additional shortcut keywords like :DEFAULT if subsets
of our export list are frequently desired. For example, if the get
routines are frequently selected or deselected as a group, we can group
them as the :GET group like so:
package LWP::Simple; use base qw(Exporter);
use vars qw(@EXPORT @EXPORT_OK %EXPORT_TAGS);
@EXPORT = qw(get head getprint getstore mirror);
@EXPORT_OK = qw($ua);
%EXPORT_TAGS = ("GET" => [qw(getprint getstore)]);
And now we can include them or exclude them easily:
use LWP::Simple qw(:GET);
which brings in only getprint and getstore, or:
use LWP::Simple qw(!:GET);
which gives us the default list, minus getprint and getstore, or
even:
use LWP::Simple qw(/^/ !:GET);
which is all possible exports, except for getprint and getstore.
If /^/ is a bit mystical to explain to your users, you can help them
along with an :ALL tag:
%EXPORT_TAGS = (
"ALL" => [@EXPORT, @EXPORT_OK],
"GET" => [qw(getprint getstore)]
);
which permits us to say:
use LWP::Simple qw(:ALL);
and get all possible exports and:
use LWP::Simple qw(:ALL !:GET);
to get everything except the getprint and getstore routines.
You can also go the other way, defining your symbols primarily in
%EXPORT_TAGS, and then adding them to the @EXPORT and
@EXPORT_OK variables:
package My::Package;
use base qw(Exporter);
use vars qw(%EXPORT_TAGS);
%EXPORT_TAGS = (
"CORE" => [qw(core_enable core_disable)],
"FIRE" => [qw(halt_and_catch_fire)],
"VARS" => [qw($core_heat $core_fire)],
);
Exporter::export_tags('CORE', 'FIRE'); # default list
Exporter::export_ok_tags('VARS'); # optional list
Another feature of Exporter and use is the ability to check
version numbers. If we include a version number before the (optional)
import list, the $VERSION variable of the package will be checked
to ensure that it is not smaller than the requested version. For example,
if My::Package is defined as:
package My::Package; use base qw(Exporter); use vars qw($VERSION @EXPORT @EXPORT_OK); $VERSION = 1.02; @EXPORT = ...; @EXPORT_OK = ...;
and I try to invoke it with:
use My::Package 1.05;
I will get a complaint that the version number is not sufficient.
This feature is provided by the Exporter::require_version method,
and compares the numbers as floating point values. If you want a
different sort of comparison, you should write your own.
Because Exporter exports a half-dozen routines into the current
namespace, you might want to narrow it down to just import:
package My::Package; use Exporter qw(import);
and now we don't have to worry about other name collisions. However, we just broke version checking, as described above, so be careful with this.
So far, we've seen most of the standard things you can do with
Exporter::import. But we can also write our own import routine
to do non-standard tasks. For example, the use lib module takes
the import list and adds it to @INC. The code is roughly something
like:
package lib;
sub import {
unshift @INC, @_;
}
which simply takes the arguments passed to lib::import, and
prepends them to the @INC path. (The actual lib module also
deals with architecture-specific path additions.)
Another example of a very complex import routine is the core CGI
module, which supports a version of colon-prefixed keywords as well as
some other flags to trigger various actions.
You can, of course, create your own import routines as well:
package My::Package;
sub import {
my $filename = shift;
open MY_LOG, ">>$filename" or die;
}
and now use this as:
use My::Package qw(/my/log/file);
The indicated filename will be opened as the (package-based) filehandle for logging.
Well, I think this about wraps it up for now. Hopefully, you've seen
a few new ways to use your import list. Until next time, enjoy!