Modules

Contents:

Using Modules
Creating Modules
Overriding Built-in Functions

The module is the fundamental unit of code reuse in Perl. Under the hood, it's just a package defined in a file of the same name (with pm on the end). Now, we'll explore how you can use other people's modules and create your own.

Perl comes bundled with a large number of modules, which you can find in the lib directory of your Perl distribution. Many of those modules are described in "Standard Modules", and "Pragmatic Modules". All the standard modules also have extensive online documentation, which (horrors) may be more up-to-date than this tutorial. Try the perldoc command if your man command doesn't work.

The Comprehensive Perl Archive Network (CPAN) contains a worldwide repository of modules contributed by the Perl community, and is discussed in "CPAN". See also http://www.cpan.org.

Using Modules

Modules come in two flavors: traditional and object-oriented. Traditional modules define subroutines and variables for the caller to import and use. Object-oriented modules function as class definitions and are accessed through method calls, described in "Objects". Some modules do both.

Perl modules are typically included in your program by saying:

use MODULE LIST;

use MODULE;

MODULE must be an identifier naming the module's package and file. (The syntax descriptions here are meant to be suggestive; the full syntax of the use statement is given in "Functions".)

The use statement does a preload of MODULE at compile time and then an import of the symbols you've requested so that they'll be available for the rest of the compilation. If you do not supply a LIST of symbols that you want, the symbols named in the module's internal @EXPORT array are used--assuming you're using the Exporter module, described in "Module Privacy and the Exporter" later in this chapter. (If you do supply a LIST, all your symbols must be mentioned in the module's @EXPORT or @EXPORT_OK arrays, or an error will result.)

Since modules use the Exporter to import symbols into the current package, you can use symbols from the module without providing a package qualifier:

use Fred; # If Fred.pm has @EXPORT = qw(flintstone) flintstone(); # ...this calls Fred::flintstone().

All Perl module files have the extension pm. Both use and require assume this (as well as the quotes) so that you don't have to spell out "MODULEpm". Using the bare identifier helps to differentiate new modules from pl and ph libraries used in old versions of Perl. It also introduces MODULE as an official module name, which helps the parser in certain ambiguous situations. Any double colons in the module name are translated into your system's directory separator, so if your module is named Red::Blue::Green, Perl might look for it as Red/Blue/Green.pm.

Perl will search for modules in each of the directories listed in the @INC array. Since use loads modules at compile time, any modifications to @INC need to occur at compile time as well. You can do this with the lib pragma described in "Pragmatic Modules" or with a BEGIN block. Once a module is included, a key/value pair will be added to the %INC hash. The key will be the module filename (Red/Blue/Green.pm in our example) and the value will be the full pathname, which might be something like C:/perl/site/lib/Red/Blue/Green.pm for a properly installed module on a Windows system.

Module names should be capitalized unless they're functioning as pragmas. Pragmas are in effect compiler directives (hints for the compiler), so we reserve the lowercase pragma names for future use.

When you use a module, any code inside the module is executed, just as it would be for an ordinary require. If you really don't care whether the module is pulled in at compile time or run time, you can just say:

require MODULE;

These two statements do almost the same thing:

require MODULE; require "MODULE.pm";

Because the use declaration and the related no declaration imply a BEGIN block, the compiler loads the module (and runs any executable initialization code in it) as soon as it encounters that declaration, before it compiles the rest of the file. This is how pragmas can change the compiler's behavior, and also how modules are able to declare subroutines that are then visible as list operators for the remainder of compilation. This will not work if you use require instead of use. Just about the only reason to use require is if you have two modules that each need a function from the other. (And we're not sure that's a good reason.)

Perl modules always load a pm file, but that file may in turn load associated files, such as dynamically linked C or C++ libraries or autoloaded Perl subroutine definitions. If so, the additional shenanigans will be entirely transparent to the module user. It is the responsibility of the pm file to load (or arrange to autoload) any additional functionality. The POSIX module happens to perform both dynamic loading and autoloading, but the user can say just:

use POSIX;