CGI and Perl

The Perl5 Module: Form and Function

The typical Perl module is a file that lives in the Perl library directories, @INC, and has Perl code that can be imported into your Perl program, through the use or require statements. If you've used Perl4, then you're probably familiar with require. The use() statement implies a BEGIN{} block, and thus the importation of the module's symbols occurs immediately. In general, the use() statement gives preferred functionality over the require statement, but they're each used widely. See PERLMOD for more details.

After the code from the module is loaded into your Perl program, it can be used as if it were part of your program. Thus, a module typically provides useful subroutines (methods) that you can call, possibly passing in Perl variables and receiving back a simple result or modified or new variables. Such behavior is typical of both Perl modules and libraries. A Simple Extension Module A typical Perl5 module that provides an extension to an external API looks something like
Listing 2.1.

Listing 2.1. A simple extension module.

package Foo;
 =head1 NAME
 Foo - Perl module that simplifies and standardizes the
 process of accessing the Foo API.
 =head1 SYNOPSIS
     use Foo;
     Foo::FooPrint(args);
     Foo::FooGet(args);
     FooEvery(args);
 =head1 DESCRIPTION
 This module may be used to access the FooLoad(), Print(),
 and Get() functions of the Foo API.
 =head1 AUTHOR
 I. B. Guru <guru@gurus.org>
 =cut
 require 5.000;
 require Exporter;
 require DynaLoader;
 @ISA = qw(Exporter DynaLoader);
 @EXPORT = qw(FooLoad);
 @EXPORT_OK = qw(Print Get);
 bootstrap Foo;
 1;
 __END__

At the top of Listing 2.1, the package name is specified. All the symbols that reside in the module live in this namespace, unless another package name is specified farther down into the module, in which case everything following that package statement will live in the newly declared package. A module can declare as many package statements internally as it wants, but the name of the file where the module lives must correspond to a component of the first use() statement in the program that uses it.

Ideally, the package statement is followed by an embedded POD section, which documents the functionality and use of the package's subroutines and variables. Every well-written module should have some documentation, minimally describing usage of the internal methods and hopefully providing at least one example.

Next, you get to the initialization statements, which cause the module to import methods and/or instantiate objects from other modules. The most commonly used module within other modules is the Exporter. The Exporter defines a standard set of methods that give a module the ability to export its methods and variables into Perl programs, or other Perl modules that use or require it. After the methods from the Exporter are imported, this module then defines which of its internal methods and variables will be exported to other modules by default via the @EXPORT or, on request, via the @EXPORT_OK array.

Note:

The process of importing, exporting, autoloading, dynaloading, and bootstrapping in external modules is complex. You must understand a number of implicit and explicit methods and techniques to use these processes in the development of new modules. See the Module List, PERLMOD, Exporter, AutoLoader, and DynaLoader for an in-depth discussion. See any CPAN site for the latest version of the module list.

Perl Modules: Usage and Invocation Syntax If a particular method is exported from a module, it means that when you use the module in your Perl program, the method will be accessible in the main:: package namespace, just like an ordinary Perl function, or a subroutine that lives in main::. If you declare the use() statement with the preceding Foo module, for example, and because it exports a single method, FooLoad() through @EXPORT array, you could write a short Perl program like Listing 2.2.