- Packages
- Modules
- Exporting symbols
- Some example modules
- Documenting modules with POD
- Conclusion
This chapter is from the book
This chapter is from the book
This chapter is from the book
6.3 Exporting symbols
As we saw earlier, Perl programs have full access to variables and subroutines defined within imported modules. However, it quickly becomes tedious to use fully qualified names for every variable and subroutine that a module defines.
Perl's Exporter module allows modules to "export" identifiers (i.e., variable and subroutine names) into the calling program's namespace. Once exported, an identifier has two names—one in the module's package and another in the importing program's package.
Importing symbols is potentially dangerous: A module that exports $x will trample $x in the calling program's package. This is known as namespace pollution, and we will soon see how Perl helps us to avoid such problems.
6.3.1 Basic export functionality
For a module to export one or more identifiers into a caller's namespace, it must:
-
use the Exporter module, which is part of the standard Perl distribution,
-
declare the module to inherit Exporter's capabilities, by setting the variable @ISA (see Section 7.3.1) to equal ('Exporter'), and
-
indicate under which circumstances identifiers should be exported, by setting one or more of the variables @EXPORT, @EXPORT OK, and %EXPORT TAGS.
@ EXPORT is the easiest way to export identifiers, but also the most dangerous: Any identifier in @EXPORT will be exported to the calling program's namespace, unless the caller indicates otherwise. For example, the following defines MyModule, which exports $a and @b by default:
package MyModule; use Exporter; # Gain export capabilities our (@EXPORT, @ISA); # Global variables ISA = qw(Exporter); # Take advantage of Exporter's capabilities EXPORT = qw($a @b); # Export $a and @b by default $a = 5; # Assign some values @b = (1, 2, 3); 1; # Always return a true value
When a program invokes use MyModule, the variables $a and @b will be available as $MyModule::a and @MyModule::b, and also as $main::a and @main::b. (This assumes, of course, that the default package when executing use is main.) Any existing values for $main::a and @main::b are overwritten.
A calling program can override the value of @EXPORT by explicitly passing a list of identifiers that should be exported. For example:
use MyModule qw($a); # Only imports $a
The preceding code imports $a, but not @b, from MyModule. We can import a module without any of its identifiers by passing an empty list:
use MyModule (); # Don't import into the current package
To avoid potential namespace pollution, place exportable identifiers in @EXPORT OK. @EXPORT OK is just like @EXPORT, except that its contents are only exported when explicitly requested.
A module can also create named groups of identifiers that can be exported in a single chunk. Group names are known as export tags, and these form the keys of %EXPORT TAGS. The value associated with each key is an array reference listing the identifiers belonging to that group. Identifiers named in %EXPORT TAGS must appear in either @EXPORT or @EXPORT OK.
For example, the below Conversions module shown here declares four subroutines (inch2cm, gal2liter, dollar2pound, and dollar2mark) as exportable, by listing them in @EXPORT OK:
package Conversions;
use Exporter; # Gain export capabilities
our (@ISA, @EXPORT, # Declare some global variables
@EXPORT_OK, %EXPORT_TAGS,
$inch2cm, $gal2liter, $dollar2pound, $dollar2mark);
@ISA =qw(Exporter); # Take advantage of Exporter's capabilities
@EXPORT_OK = # Exported, if explicitly requested
qw($inch2cm $gal2liter $dollar2pound $dollar2mark);
%EXPORT_TAGS = # Tag groups
("metric" =>[qw($inch2cm $ gal2liter)],
"currency" =>[qw($dollar2pound $dollar2mark)]);
# Subroutine definitions go here
1; # Always return a true value
We can import dollar2pound and dollar2mark by naming their their tag group in our use statement, preceding the tag name with a colon (:):
use Conversions qw(:currency); # Imports 'currency' tag group
perldoc Exporter describes the Exporter module more thoroughly, including advanced ways to selectively import symbols.