Learning Perl Objects, References amp;amp; Modules [Electronic resources] نسخه متنی

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.[6]

[6] 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.[7]

[7] 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.