[Chapter 5] 5.2 Modules
Author: Larry Wall, Tom Christiansen & Randal L. Schwartz
Date: 1999-07-02T01:58:27Z

#

| Chapter 5 Packages, Modules, and Object Classes |

## 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 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.

### 5.2.1 Access to Modules

Perl does not patrol private/public borders within its modules - unlike languages such as C++, Ada, and Modula-17, Perl isn't infatuated with enforced privacy. As we mentioned at the beginning of the chapter, a Perl module would prefer that you stayed out of its living room because you weren't invited, not because it has a shotgun.

The module and its user have a contract, part of which is common law and part of which is written. Part of the common law contract is that a module doesn't pollute any namespace it wasn't asked to pollute. The written contract for the module (that is, the documentation) may make other provisions. But then, having read the written contract, you presumably know that when you say:

    use RedefineTheWorld;

you're redefining the world, and you're willing to take the consequences. The next section talks about one way to redefine parts of the world.

### 5.2.2 Overriding Built-in Functions

Many built-in functions may be overridden, although (like knocking holes in your walls) you should only try this occasionally and for good reason. Typically, this might be done by a package attempting to emulate missing built-in functionality on a non-UNIX system. (Do not confuse overriding with overloading, which adds additional object-oriented meanings to built-in operators, but doesn't override much of anything. See the discussion of the overload module in Chapter 7 for more on that.)

Overriding may be done only by importing the name from a module - ordinary predeclaration isn't good enough. To be perfectly forthcoming, it's the assignment of a code reference to a typeglob that triggers the override, as in `*open = \&myopen`, which is how importing of functions is implemented. Furthermore, the assignment must occur in some other package; this makes unintentional overriding through typeglob aliasing more difficult. However, if you really want to do your own overriding, don't despair, because the `subs` pragma lets you predeclare subroutines via the import syntax, and these names may then override the built-in ones:

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

Library modules should not in general export built-in names like open or chdir as part of their default `@EXPORT` list, since these names may sneak into someone else's namespace and change the semantics unexpectedly. Instead, if the module adds the name to the `@EXPORT_OK` list, then it's possible for users to import the name explicitly, but not implicitly. That is, they could say

    use Module 'open';

and it would import the open override, but if they said

    use Module;

they would get the default imports without the overrides.

The original versions of the built-in functions are always accessible via the `CORE` pseudopackage. Therefore, `CORE::chdir()` will always be the version that Perl was compiled with, even if the regular chdir function has been overridden.

5.1 Packages |  | 5.3 Objects