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

## 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

Copyright © 2003 O'Reilly & Associates. All rights reserved.