Building a Module

To understand how a module is put together, let's walk through a simple example: a small statistics library. This will re-use functions from the end of Hour 8, abbreviated for space. The sample module, which we're going to call TYPStats, is shown in Listing 17.1.

Listing 17.1. Statistics Module

1: #!/usr/bin/perl -w
2: use strict;
3: package TYPStats;
4: 
5: sub mean {
6:        my(@data) = @_;
7:        my $sum;
8:        $sum += $_ foreach(@data);
9:        return @data ? ($sum / @data) : 0;
10: }
11: sub median {
12:       my(@data)=sort { $a <=> $b} @_;
13:       if (scalar(@data) % 2) {
14:               return($data[@data / 2]);
15:       }
16:       return(mean($data[@data / 2], 
17:            $data[@data / 2 - 1]));
18: }
19: 1;

This should be saved into a file called TYPStats.pm in the same directory as the Perl scripts that are going to use this module. The filename is important, so be sure you get that right. (You can put modules elsewhere, but for simplicity, put it there for now.) Perl modules always end with the extension .pm. A couple of things to note:

• The package declaration at the beginning will be explained shortly. This should match the module name.

• There's no real code to run in the module. Just a 1;. Perl modules must return a true value when executed and 1; is the shortest way to accomplish this. Thus, it's traditional to end a Perl module with this statement.

Calling the Module

To use this module, create a small Perl program and call it process_stats.pl as shown in Listing 17.2.

Listing 17.2. Program to Use Statistics Module

1: #!/usr/bin/perl -w
2:
3: use strict;
4: use TYPStats;
5:
6: print TYPStats::mean(3, 6, 10, 51, 3, 99);

Line 3: The use statement causes the Perl interpreter to find a TYPStats.pm file and load it into the current program.

Line 6: The mean function from the TYPStat's module is called. Notice that the function name is prefixed by the module name. This is explained in Namespaces below.

Running this program should give you the result 28.6.

If you had written

print mean(3, 6, 10, 51, 3, 99);

Perl would have given the following error:

Undefined subroutine &main::mean called at process_stats.pl

Because there's no mean subroutine in the program, you must explicitly specify that it's in the TYPStats module.

Namespaces

Every Perl subroutine (and variable not declared with my) exists in a namespace. A namespace is a way of fully qualifying the name of the subroutine.

For example, in my department of 13 people there are three people named Patrick and two named David. This gets very confusing at times. Most of the time, we have to resort to using their fully qualified names “Patrick Smith,” “Patrick Connor,” or “Patrick Jones.” In my department, each person's given name (Patrick, David) is unique within their respective namespace (family name).

The package statement allows you to declare that all the functions that follow should be placed in that namespace. The fully qualified name of the subroutine is the namespace, followed by the subroutine. So within your TYPStats module, you've actually defined the two subroutines, TYPStats::mean and TYPStats::median.

Defined subroutines without a package declaration appear in a special package called main.

Why have namespaces at all? Primarily, it's so that if someone uses the TYPStats module in a program that has its own mean subroutine, Perl knows whether to use the module's mean subroutine or the local one. With thousands of modules available for Perl, avoiding namespace collisions is very important.