 |  |
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 lineIn 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
|  | |
| 12. Packages, Libraries, and Modules |  | 12.2. Trapping Errors in require or use |
Copyright © 2003 O'Reilly & Associates. All rights reserved.