Defining a Module's Interface (Perl Cookbook, 2nd Edition)

12.1.3. Discussion

The standard Exporter module handles the module's external interface. Although you could define your own import method for your package, almost no one does this.

When someone says use YourModule, this does a require "YourModule.pm" statement followed a YourModule->import( ) method call, both during compile time. The import method inherited from the Exporter package looks for global variables in your package to govern its behavior. Because they must be package globals, we've declared them with our to satisfy use strict. These variables are:

$VERSION

When a module is loaded, a minimal required version number can be supplied. If the version isn't at least this high, the use will raise an exception.

use YourModule 1.86;        # If $VERSION < 1.86, fail

@EXPORT

This array contains a list of functions and variables that will be exported into the caller's own namespace so they can be accessed without being fully qualified. Typically, a qw( ) list is used.

@EXPORT = qw(&F1 &F2 @List);
@EXPORT = qw( F1  F2 @List);        # same thing

With the simple use YourModule call the function &F1 can be called as F1( ) rather than YourModule::F1( ), and the array can be accessed as @List instead of @YourModule::List. The ampersand is optional in front of an exported function specification.

To load the module at compile time but request that no symbols be exported, use the special form use Exporter ( ), with empty parentheses.

@EXPORT_OK

This array contains symbols that can be imported if they're specifically asked for. If the array were loaded this way:

@EXPORT_OK = qw(Op_Func %Table);

then the user could load the module like so:

use YourModule qw(Op_Func %Table F1);

and import only the Op_Func function, the %Table hash, and the F1 function. The F1 function was listed in the @EXPORT array. Notice that this does not automatically import F2 or @List, even though they're in @EXPORT. To get everything in @EXPORT plus extras from @EXPORT_OK, use the special :DEFAULT tag, such as:

use YourModule qw(:DEFAULT %Table);

%EXPORT_TAGS

This hash is used by large modules like CGI or POSIX to create higher-level groupings of related import symbols. Its values are references to arrays of symbol names, all of which must be in either @EXPORT or @EXPORT_OK. Here's a sample initialization:

%EXPORT_TAGS = (
        Functions => [ qw(F1 F2 Op_Func) ],
        Variables => [ qw(@List %Table)  ],
);

An import symbol with a leading colon means to import a whole group of symbols. Here's an example:

use YourModule qw(:Functions %Table);

That pulls in all symbols from:

@{ $YourModule::EXPORT_TAGS{Functions} },

that is, it pulls in the F1, F2, and Op_Func functions and then the %Table hash.

Although you don't list it in %EXPORT_TAGS, the implicit tag :DEFAULT automatically means everything in @EXPORT.

You don't have to have all those variables defined in your module. You just need the ones that you expect people to be able to use.

12.1. Defining a Module's Interface

12.1.1. Problem

12.1.2. Solution

12.1.3. Discussion

12.1.4. See Also