Recipe 12.1 Defining a Module's Interface

12.1.1 Problem

You want the standard Exporter module to define the external interface to your module.

12.1.2 Solution

In module file YourModule.pm, place the following code. Fill in the ellipses as explained in the Discussion section.

package YourModule;
use strict;
our (@ISA, @EXPORT, @EXPORT_OK, %EXPORT_TAGS, $VERSION);

use Exporter;
$VERSION = 1.00;              # Or higher
@ISA = qw(Exporter);

@EXPORT      = qw(...);       # Symbols to autoexport (:DEFAULT tag)
@EXPORT_OK   = qw(...);       # Symbols to export on request
%EXPORT_TAGS = (              # Define names for sets of symbols
    TAG1 => [...],
    TAG2 => [...],
    ...
);

########################
# your code goes here
########################

1;                            # this should be your last line

In other files where you want to use YourModule, choose one of these lines:

use YourModule;               # Import default symbols into my package
use YourModule qw(...);       # Import listed symbols into my package
use YourModule ( );            # Do not import any symbols
use YourModule qw(:TAG1);     # Import whole tag set

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.4 See Also

The "Creating Modules" section of Chapter 11 of Programming Perl; the documentation for the standard Exporter module, also found in Chapter 32 of Programming Perl; Recipe 12.8; Recipe 12.22