Format of Perl Modules

Recall that a Perl module is a .pm file that contains a package statement together with some other items, including documentation. Perl documentation is typically called POD (Plain Old Documentation). Before we present the categories of modules found on CPAN, we discuss what you can expect to find in any of the CPAN modules that you might download.

Building a Module

To illustrate the different pieces of information that you may find in any module, we will build one of our own. The first step is to create a .pm file. All .pm files need to have the package specifier as the first line of the file. The name of the file and the name of the package need to be the same (except for the suffix .pm).

Suppose we wish to build a package that handles complex numbers. We would create a file named Complex.pm whose first line has a package statement.

% type Complex.pm
package Complex;
1;
%

Remember that this module will be used by other applications, so the last line evaluated when this modules is imported must be nonzero.

Adding Functions to a Module

A module contains a set of related functions. In the case of the Complex module, we start with a function to create a complex number and a function to print one.

% type Complex.pm
package Complex;
sub create
{
        my ($r, $i) = @_;
        my ($complex) = {
                        real => $r,
                        imag => $i
                        };
        $complex;
}
sub display
{
        my($ref) = @_;
        print $ref->{real}, "+", $ref->{imag}, "i";

}
1;

Any application needing the functionality of the Complex module would proceed as follows.

use Complex;
$x = Complex::create(2,3);
Complex::display($x);             #  prints 2+3i

If there are many references to the functions in the Complex module, it may be both tiresome and error prone to continuously have to use the Complex prefix. There is a way around this dilemma.

Exporting Symbols

Any module that allows its functions or other symbols to be exported must inherit from the Exporter module. The following code would typically be placed immediately after the package statement.

use Exporter;
@ISA = (Exporter);
@EXPORT = (create, display);

Recall that the @ISA array is used to create an inheritance relationship. In this case, Complex inherits from Exporter. The Exporter module has an import function that is called automatically whenever Perl processes a use statement for a module.

The @EXPORT array holds the name of the symbols that can be used without the package specifier. In other words, given the three lines above, the application using the Complex module can be coded as

use Complex;
$x = create(2,3);
display($x);                       #  prints 2+3i

Even though this strategy works fine, the more names that are entered into a namespace, the less efficiently your program will run. Thus, there is an alternative way to import symbols.

If the module writer uses the @EXPORT_OK array instead of the @EXPORT array, the symbols contained in @EXPORT_OK become candidates for exporting. The user of the Complex module must then explicitly arrange to import them.

#   Complex.pm
package Complex;
use Exporter;
@ISA = (Exporter);
@EXPORT_OK = (create, display);

#   Complex.pl
use Complex (create, display);
$x = create(2,3);
display($x);                       #  prints 2+3i

Our Complex module is for illustrative purposes. Were it real, we would have methods to perform the normal calculations on complex numbers, such as adding, subtracting, multiplying, and dividing them. Here is an example of the multiplication of two complex numbers.

sub mult
{
    my ($r1, $r2) = @_;
    my ($rr, $ir);
    $rr=$r1->{real}*$r2->{real} – $r1->{imag}*$r2->{imag};
    $ir=$r1->{real}*$r2->{imag} + $r2->{real}*$r1->{imag};
    my ($hash) = { real => $rr,
                   imag => $ir
                 };
    $hash;
}

The mult method would be invoked as in the following program. See the folder Complex.

% type Complex.pl
#
#   Complex.pl
#
use Complex (create, display, mult);
$x = create(2,3);
$y = create(3,4);
display($x);                      #  prints 2+3i
print "
";
display($y);                      #  prints 3+4i
print "
";
$z = mult($x, $y);
display($z);                      #  prints –6+17i
% perl Complex.pl
2+3i
3+4i
-6+17i
%

Note that the Perl distribution comes with a Complex module.