There isn’t really a whole lot involved when building a module, just a few basic steps and a rule about naming your module. For this example we will building a module named Cool.pm which will contain one function called cool().

The basic outline of our module is as 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.

So we have six basics things to do in building a module: 1) declare the package; 2) set up exportation; 3) what to export, and how; 4) our actual code; 5) end with a true statement; 6) include our POD documentation for the module. Pretty simple right? Let’s look at each of the steps in turn.

Step one is declaring our package name. The rule is, our package name will be the same (case sensitive) as the filename we store this in (except that we put a .pm extension on the file). So our module will exist in a file called ‘Cool.pm’. If we build a nested package like Cool::Kewler, we would declare that package name and store it in a file name Kewler.pm under a directory in our @INC path named Cool, so it would be in a file named ‘Cool/Kewler.pm’ (we’ll talk more about where to put module files next week).

Step two is pulling in Perl’s Exporter module via the require() statement, and including it in our @ISA array. What this does is gives us a default import() routine (we inherit it from Exporter) so we do not have to build our own (a subject to deep for the present article).

Step three defines what we want to export and how to export it. The @EXPORT array holds whatever functions and variables we want to automatically export in the calling script. The @EXPORT_OK array holds whatever we want to export by demand. What does that mean? Well, if the calling script starts of like:

    #!/usr/bin/perl -w
    use strict;
    use Cool;

It will only receive the functions specified in the @EXPORT array. If the caller does this:

    #!/usr/bin/perl -w
    use strict;
    use Cool qw(cool);

It 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 — that way the caller decides what they want to import and doesn’t have to worry about a whole bunch of functions being imported by default.

Step four defines our actual code — in this case a single function named cool() that merely prints a string.

Step five is very simple, but very important — the last statement evaluated by a module must return a true value as an indicator that all has gone well. Using just a ‘1;’ is the standard way of doing this.

Step six is also very important — if you are going to build a module, you should document it with POD so users of it can find out what it does and how to use it. The perlpod manpage (perldoc perlpod) explains the POD markup language we use for documenting modules and scripts.

OK, if you save the above module in a file named ‘Cool.pm’, 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__

And, you may also type ‘perldoc Cool’ to bring up the modules POD (again, in the same directory).

*****