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. 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 <firstname.lastname@example.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.
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.