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). In this chapter, 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 Chapter 32, and Glossary. 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. See also http://www.cpan.org.
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. Some modules do both.
Perl modules are typically included in your program by saying:
useMODULE
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.)
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 Glossary 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:
requireMODULE
; 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 =
purge
MODULE
) 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.