Chapter 11. Modules

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 Chapter 32, "Standard Modules", and Chapter 31, "Pragmatic Modules". All the standard modules also have extensive online documentation, which (horrors) may be more up-to-date than this book. 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 Chapter 22, "CPAN". See also http://www.cpan.org.

11.1. 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 Chapter 12, "Objects". Some modules do both.

Perl modules are typically included in your program by saying:

use MODULE LIST;

or just:

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 Chapter 29, "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 "MODULE.pm". 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 Chapter 31, "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;

In general, however, use is preferred over require because it looks for modules during compilation, so you learn about any mistakes sooner.

These two statements do almost the same thing:

require MODULE;
require "MODULE.pm";

They differ in two ways, however. In the first statement, require translates any double colons in the module name into your system's directory separator, just as use does. The second case does no translation, forcing you to specify the pathname of your module literally, which is less portable. The other difference is that the first require tells the compiler that the expressions with indirect object notation involving "MODULE" (such as $ob = purgeMODULE) are method calls, not function calls. (Yes, this really can make a difference, if there's a conflicting definition of purge in your own module.)

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;

to get all the exported functions and variables.

Chapter 11. Modules

Contents:

11.1. Using Modules