The Prototype Module Itself (Learning Perl Objects, References & Modules)

13.3. The Prototype Module Itself

Now you come to the most important part of the distribution: the module itself. Finally, actual code:

$ cat Maps.pm
package Island::Plotting::Maps;

It looks good so far. The module automatically starts with an appropriate package directive. Following that, you see:

use 5.008;
use strict;
use warnings;

Now you're declaring that the module is compatible with Perl 5.8.0 or later and that the compiler restrictions and warnings are enabled automatically. Good practices are encouraged here. Obviously, you're free to delete or modify anything inappropriate.

Then comes Exporter:

require Exporter;

our @ISA = qw(Exporter);

These lines support the import method call needed to make use work. This is fine for a nonobject-oriented module, but for an object-oriented module inheriting from a parent (base) class, you'll want to replace them with:

use base qw(Our::Parent::Class);

Resulting in more Exporter control:

our %EXPORT_TAGS = ( 'all' => [ qw(

) ] );

our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );

our @EXPORT = qw(

);

Every symbol you wish to possibly import as a result of the use operation should be placed into the first qw( ) list. This lets you say:

 use OurModule qw(:all)

to get all possible symbols.[81]

[81]Technically, you don't need :all because /^/ (include all symbols that match at least a beginning of string) does the same. Many people are familiar with typing :all, and it's far more self-documenting than /^/ is, so include it if you can.

Every symbol you wish to export by default on a missing import list should go into the last qw( ). (Any symbol in the @EXPORT list is automatically a member of the @EXPORT_OK list, but you'll want to list it again it the first qw( ) list so it comes in via the :all method.)

Recall from Chapter 12 that a typical object-oriented module exports nothing because the interface is entirely through class method calls and instance method calls, neither of which require subroutines in the invoker's package.

Next, you'll see the version number:

our $VERSION = '0.01';

This version number is important for many reasons:

Unique identification

The version number identifies a particular release of a particular module as it floats around the Internet.

Filename generation

The archive of the distribution includes the version number of the primary module by default.

Upgrade indication

Generally, numbers that increase numerically supersede previous versions. For this test, the number is considered a floating-point number, so 2.10 (which is really 2.1) is less than 2.9 (which must be the same as 2.90, by the same logic). To avoid confusion, if you've got two digits after the decimal point in one release, you shouldn't change it in the next without a very good reason.

Interface stability

Generally, numbers that begin with 0 are alpha or beta, with external interfaces that may still be in flux. Also, most people use a major version number change (from 1.x to 2.x, etc.) to indicate a potential break in upward compatibility.

Recognition by the various CPAN tools

The CPAN distribution management tools use the version number to track a particular release, and the CPAN installation tools can determine missing or out-of-date distributions.

Perl's own operators

The use operator can be given a version number in addition to (or instead of) the import list, forcing the use operation to fail if the imported module is not equal or greater to that version:

use Island::Plotting::Maps 1.10 qw{ map_debugger };

Generally, you can start with the 0.01 given by the template and increase it consistently with each new test release. Often, you can coordinate this version number with some source code control system.[82]

[82]The perlmod page includes an example that extracts the CVS/RCS version number for the module's version number.

Now you're past the header information and down to the core of your module. In the template, it is indicated by a simple comment:

# Preloaded methods go here.

What? You didn't think the h2xs tool would even write the module for you, now did you? Anyway, this is where the code goes, usually as a series of subroutines, possibly preceded by some shared module data (using my declarations), and perhaps a few package variables (using our declarations in recent Perl versions). Following the code, you'll find your necessary true value:

1;

so the require (inside the use) doesn't abort.