Learning Perl Objects, References amp;amp; Modules [Electronic resources] نسخه متنی

12.9 @EXPORT and @EXPORT_OK

The
import provided by Exporter
examines the @EXPORT variable in the
module's package to determine which variables are
exported by default. For example, File::Basename
might do something like:

package File::Basename;
our @EXPORT = qw( basename dirname fileparse );
use Exporter;
our @ISA = qw(Exporter);

The @EXPORT list both defines a list of available
subroutines for export (the public interface) and provides a default
list to be used when no import list is specified. For example, these
two calls are equivalent:

use File::Basename;
BEGIN { require File::Basename; File::Basename->import }

No list is passed to import. In that case, the
Exporter->import routine looks at
@EXPORT and provides everything in the
list.[13]

[13] Remember, having no list is not the same as
having an empty list. If the list is empty, the
module's import method is simply
not called at all.

What if you had subroutines you
didn't want as part of the default import but would
still be available if requested? You can add those subroutines to the
@EXPORT_OK list in the module's
package. For example, suppose that Gilligan's module
provides the guess_direction_toward routine by
default but could also provide the
ask_the_skipper_about and
get_north_from_professor routines, if requested.
You can start it like this:

package Navigate::SeatOfPants;
our @EXPORT = qw(guess_direction_toward);
our @EXPORT_OK = qw(ask_the_skipper_about get_north_from_professor);
use Exporter;
our @ISA = qw(Exporter);

The following invocations would then be valid:

use Navigate::SeatOfPants;  # gets guess_direction_toward
use Navigate::SeatOfPants qw(guess_direction_toward); # same
use Navigate::SeatOfPants
qw(guess_direction_toward ask_the_skipper_about);
use Navigate::SeatOfPants
qw(ask_the_skipper_about get_north_from_professor);
## does NOT import guess_direction_toward!

If any names are specified, they must come from either
@EXPORT or @EXPORT_OK, so this
request is rejected by Exporter->import:

use Navigate::SeatOfPants qw(according_to_GPS);

because
according_to_GPS is in neither
@EXPORT nor
@EXPORT_OK.[14] Thus, with
those two arrays, you have control over your public interface. This
does not stop someone from saying
Navigate::SeatOfPants::according_to_GPS (if it
existed), but at least now it's obvious that
they're using something the module author
didn't intend to offer them.

[14] This check also
catches misspellings and mistaken subroutine names, keeping you from
wondering why the get_direction_from_professor
routine isn't working.

As described in the Exporter manpage, a few
shortcuts are available automatically. You can provide a list that is
the same as asking for the default:

use Navigate::SeatOfPants qw(:DEFAULT);

or the default plus some others:

use Navigate::SeatOfPants qw(:DEFAULT get_north_from_professor);

These
are rarely seen in practice. Why? The purpose of explicitly providing
an import list generally means you want to control the subroutine
names you use in your program. Those last examples do not insulate
you from future changes to the module, which may import additional
subroutines that could collide with your code.[15]

[15] For
this reason, it is generally considered a bad idea for an update to a
released module to introduce new default imports. If you know that
your first release is still missing a function, though,
there's no reason why you can't put
in a placeholder: sub according_to_GPS { die "not
implemented yet" }.

In a few cases, a module may supply dozens or hundreds of possible
symbols. These modules can use advanced techniques (described in the
Exporter documentation) to make it easy to import
batches of related symbols. For example, the core
Fcntl module makes the flock
constants available as a group with the :flock
tag:

use Fcntl qw( :flock );        # import all flock constants