5.2 Modules

A module is just a reusable package that is defined in a library file whose name is the same as the name of the package (with a .pm on the end). A module may provide a mechanism for exporting some of its symbols into the symbol table of any other package using it. Or it may function as a class definition and make its operations available implicitly through method calls on the class and its objects, without explicitly exporting any symbols. Or it can do a little of both.

Most exporter modules rely on the customary exportation semantics supplied by the Exporter module. For example, to create an exporting module called Fred, create a file called Fred.pm and put this at the start of it:

package      Fred;
require      Exporter;
@ISA       = qw(Exporter);
@EXPORT    = qw(func1 func2);
@EXPORT_OK = qw($sally @listabob %harry func3);

Then go on to declare and use your variables and functions without any qualifications. See the Exporter module documentation in Chapter 7, The Standard Perl Library for further information on the mechanics and style issues in module creation.

Perl modules are included in your program by saying:

use Module;

or:

use Module LIST;

This preloads Module at compile time, and then imports from it the symbols you've requested, either implicitly or explicitly. If you do not supply a list of symbols in a LIST, then the list from the module's @EXPORT array is used. (And if you do supply a LIST, all your symbols should be mentioned in either @EXPORT or @EXPORT_OK, or an error will result.) The two declarations above are exactly equivalent to:

BEGIN {
    require "Module.pm";
    Module->import();
}

or:

BEGIN {
    require "Module.pm";
    Module->import(LIST);
}

(We said that the first example above defaults to using the module's @EXPORT list, but that is a bit of a fib. It does this if the module uses the standard Exporter semantics. But a module can do anything it jolly well pleases when you do an import, since use just calls the ordinary import( ) method for the module, as above, and that method can be defined to do anything. Well, almost anything.)

Sometimes you might not wish to import anything from a module that exports things by default. As a special case, you can say:

use Module ();

which is exactly equivalent to

BEGIN { require "Module.pm"; }

Note that any initialization code in the Module is still run, as it would be for an ordinary require. It's only the import that is suppressed. If you really don't care whether the module is pulled in at compile-time or run-time, you can just say:

require Module;

This is slightly preferred over require `Module.pm`; because it introduces Module as a package, which can clarify certain error messages that the parser might emit.

All Perl module files have the extension .pm. Both use and require will assume this (as well as the quotes) so that you don't have to spell out "Module.pm". This helps to differentiate new modules from the .pl and .ph files used by prior versions of Perl. Module names are also capitalized unless they're functioning as pragmas. Pragmas are in effect compiler directives, and such modules are sometimes called "pragmatic modules"--or even "pragmata" if you're a classicist.

Because the use declaration (in any form) implies a BEGIN block, the module is loaded (and any executable initialization code in it run) as soon as the use declaration is compiled, before the rest of the file is compiled. This is how use is able to function as a pragma mechanism to change the compiler's behavior, and also how modules are able to declare subroutines that are then visible as (unqualified) list operators for the rest of the current file. If, on the other hand, you invoke require instead of use, you must explicitly qualify any invocation of routines within the required package.

require Cwd;    # make Cwd:: accessible with qualification
$here = Cwd::getcwd();
use Cwd;        # import names from Cwd:: -- no qualification necessary
$here = getcwd();

In general, use is recommended over require because you get your error messages sooner. But require is useful for pulling in modules lazily at run-time.

Perl packages may be nested inside other packages, so we can have package names containing "::". But such compound names don't work well as filenames on many systems. Therefore, if a module's name is, say, Text::Soundex, then its definition is actually found in the library file Text/Soundex.pm (or whatever the equivalent pathname is on your system).

Perl modules always load a .pm file, but there may also be dynamically linked executables or autoloaded subroutine definitions associated with the module. If so, these will be entirely transparent to the user of the module. It is the responsibility of the .pm file to load (or arrange to autoload) any additional functionality. The POSIX module happens to do both dynamic loading and autoloading, but the user can just say

use POSIX;

to get it all.

use RedefineTheWorld;

use subs qw(chdir chroot chmod chown);
chdir $somewhere;
sub chdir { ... }

use Module 'open';

use Module;