March 15, 2001, 12:00 AM — Building a module really doesn't involve much, just a few basic steps
and a rule about naming your module. For this example, we will build a
module named Cool.pm that will contain one function called cool(). The
basic outline of our module follows:
package Cool; # your package/module name
require Exporter; # setting to use Exporter's import()
@ISA = qw(Exporter); # routine
@EXPORT = qw(); # Defining how and what to export
@EXPORT_OK = qw(cool);
# your code here
sub cool {
print "Hey, cool!\n";
}
1; # end with a true statement
__END__
# your POD documentation
=head1 NAME
Cool -- a useless example module
=head1 SYNOPSIS
use Cool qw(cool);
cool();
=head1 DESCRIPTION
This example module merely illustrates the basic components
of a module. If it were a real module we would document it
properly.
Building a module entails six basics steps: 1) declare the package; 2)
set up exportation; 3) what to export and how; 4) the actual code; 5)
end with a true statement; 6) include the module's POD documentation.
Pretty simple right? Let's go through each step in turn.
Step 1: Declaring the Package Name
The package name will mimic (case sensitive) the filename where the
module is stored (save the file's .pm extension). According to the
naming rule, our module will exist in a file called 'Cool.pm'. What if
we build a nested package, like Cool::Kewler? Well, we would declare
that package name and store it as Kewler.pm under a directory in our
@INC path named Cool. It then would be in a file named 'Cool/Kewler.pm'
(we'll address where to put module files more next week).
Step 2: Set up Exportation
To set up exportation, we pull in Perl's Exporter module via the require
() statement and include it in our @ISA array. This gives us a default
import() routine, inherited from Exporter, so we don't have to build
our own (a subject to deep for the present article).
Step 3: What to Export and How
Next, we define what we want to export and how to export it. The
@EXPORT array holds whatever functions and variables we want
automatically exported in the calling script. The @EXPORT_OK array
holds whatever we want exported by demand. What does that mean? Well,
take a calling script that starts like this:
#!/usr/bin/perl -w
use strict;
use Cool;
Such a calling script will only receive the functions specified in the
@EXPORT array. Contrast this with the following caller:
#!/usr/bin/perl -w
use strict;
use Cool qw(cool);
This caller is asking to import the cool() function from the @EXPORT_OK
array. Our module is setup to use the @EXPORT_OK array because that is
generally nicer. The caller decides what they want imported without
worrying about a whole bunch of functions importing by default.
Step 4: The Code
At this point, we define our actual code; in this case a single
function named cool() that merely prints a string.
Step 5: End with a True Statement
A very simple, but important, step. The last statement evaluated by a
module must return a true value to indicate that all went well. Using
just a '1;' is the standard way of doing this.
Step 6: Include the Module's POD Documentation
Also very important! If you are going to build a module, then you
should document it with POD. Documenting it allows users of your module
to find out what it does and how to use it. The perlpod manpage
(perldoc perlpod) explains the POD markup language for documenting
modules and scripts.
OK, save the above module in a file named 'Cool.pm' and you can test it
out using the following script (in the same directory):
#!/usr/bin/perl -w
use strict;
use Cool qw(cool);
cool();
__END__
You may also type 'perldoc Cool' to bring up the modules POD (again, in
the same directory).
Next Week: Installing our Module (building a module part 2)
________________________________________________________________________
CORRECTION TO LAST WEEK'S NEWSLETTER:
Due to a technical error, portion of code and text were deleted from
last week's mailing. Follows is the missing code and text:
The operator context, another very different kind of context, sometimes
causes people problems. Perl variables are not typed according to the
kind of data they hold.
