12.6 What use Is Doing

So, just what is that use doing? How does the import list come in to action? Perl interprets the use list as a particular form of BEGIN block wrapped around a require and a method call. For example, the following two operations are equivalent:

use Island::Plotting::Maps qw( load_map scale_map draw_map );

BEGIN {
  require Island::Plotting::Maps;
  Island::Plotting::Maps->import( qw( load_map scale_map draw_map ) );
}

Break this code down piece by piece. First, the require. This require is a package-name require, rather than the string-expression require from earlier chapters. The colons are turned into the native directory separator (such as / for Unix-like systems), and the name is suffixed with .pm (for "perl module"). For this example on a Unix-like system, you end up with:

require "Island/Plotting/Maps.pm";

Recalling the operation of require from earlier, this means you look in the current value of @INC, checking through each directory for a subdirectory named Island that contains a further subdirectory named Plotting that contains the file named Maps.pm.^[7]

^[7] The .pm portion is defined by the interface and can't be changed. Thus, all module filenames must end in dot-p-m.

If an appropriate file isn't found after looking at all of @INC, the program dies.^[8] Otherwise, the first file found is read and evaluated. As always with require, the last expression evaluated must be true (or the program dies),^[9] and once a file has been read, it will not be reread if requested again.^[10]

^[8] Trappable with an eval, of course.

^[9] Again trappable with eval.

^[10] Thanks to the %INC hash.

In the module interface, the require'd file is expected to define subroutines in the same-named package, not the caller's package. So, for example, a portion of the File::Basename file might look something like this, if you took out all the good stuff:

package File::Basename;
sub dirname { ... }
sub basename { ... }
sub fileparse { ... }
1;

These three subroutines are then defined in the File::Basename package, not the package in which the use occurs. A require'd file must return a true value, so it's traditional to use 1; as the last line of a module's code.

How are these subroutines imported from the module's package to the user's package? That's the second step inside the BEGIN block. A routine called import in the module's package is called, passing along the entire import list.The module author is responsible for providing an appropriate import routine. It's easier than it sounds, as discussed later in this chapter.

Finally, the whole thing is wrapped in a BEGIN block. This implies that the use operation happens at compile time, rather than runtime, and indeed it does. Thus, subroutines are associated with those defined in the module, prototypes are properly defined, and so on.