@EXPORT and @EXPORT_OK (Learning Perl Objects, References & Modules)

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.[72]

[72]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.[73] 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.

[73]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.[74]

[74]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