Using Your Own Directories

One of the common problems with Perl module installation is that by default, the CPAN tools want to install new modules into the same directories where perl is. You might not have the proper permissions to create new files in those directories.

The easiest way for beginners to keep additional Perl modules in their own directories is to use local::lib, which you’ll have to get from CPAN since it doesn’t come with perl (yet). This module sets the various environment variables that affect where CPAN clients install modules. You can see what they set by loading the module on the command line without anything else:

$ perl -Mlocal::lib
export PERL_LOCAL_LIB_ROOT="/Users/fred/perl5";
export PERL_MB_OPT="--install_base /Users/fred/perl5";
export PERL_MM_OPT="INSTALL_BASE=/Users/fred/perl5";
export PERL5LIB="...";
export PATH="/Users/fred/perl5/bin:$PATH";

The cpan client supports this if you use the -I switch to install modules:

$ cpan -I Set::CrossProduct

The cpanm tool is a bit smarter. If you’ve already set the same environment variables local::lib would set for you, it uses them. If not, it checks the default module directories for write permissions. If you don’t have write permissions, it automatically uses local::lib for you.

Advanced users can configure their CPAN clients to install into whatever directories that they like too. You can set this in your CPAN.pm configuration so that modules automatically install in your private library directory when you use the CPAN.pm shell. You need to configure two settings, one each for the ExtUtils::MakeMaker and Module::Build systems:

$ cpan
cpan> o conf makepl_arg INSTALL_BASE=/Users/fred/perl5
cpan> o conf mbuild_arg "--install_base /Users/fred/perl5"
cpan> o conf commit

Notice these are the same settings that local::lib created for you in the environment. By setting them in the CPAN.pm configuration, it adds them every time it tries to install a module.

Once you’ve chosen where you want to put your Perl modules, you have to tell your programs where to find them. If you are using local::lib, you simply load that module in your program:

# inside your Perl program
use local::lib;

If you installed them in some other location, you can use the lib pragma with a list of additional module directories:

# also inside your Perl program
use lib qw( /Users/fred/perl5 );

As of v5.26, the current directory is no longer part of the module search path. Prior to that, Perl would look for modules in the current working directory (which might not be where your program is!). If your program changed its working directory, loading more modules would look in that directory instead of where you started. This was a problem with security, so it’s no longer there.

Most people probably want to look for modules in the same directory as their program—usually when they have written those modules instead of downloading them. In that case, the FindBin module, which comes with Perl, can help. It knows how to find the directory of your program, which you can then use to add your module directory to the search path:

use FindBin qw($Bin);
use lib "$Bin/../lib";

This is just enough to get you started. We talk much more about this in Intermediate Perl, where you also learn to make your own modules. You can also read the entries in the perlfaq8 documentation.

The File::Basename Module

In the previous example, you found the basename of a filename in a way that’s not portable. Something that seemed straightforward was susceptible to subtle mistaken assumptions (here, the assumption was that newlines would never appear in file or directory names). And you were reinventing the wheel, solving a problem that others have solved (and debugged) many times before you. Not to worry; it happens to all of us.

Here’s a better way to extract the basename of a filename. Perl comes with a module called File::Basename. With the command perldoc File::Basename, or with your system’s documentation, you can read about what it does. That’s always the first step when using a new module. (It’s often the third and fifth steps, as well.)

Soon you’re ready to use it, so you declare it with a use directive near the top of your program:

use File::Basename;

During compilation, Perl sees that line and loads the module. Now it’s as if Perl has some new functions that you may use in the remainder of your program. The one we wanted in the earlier example is the basename function itself:

use File::Basename;

my $name = "/usr/local/bin/perl";
my $basename = basename $name;  # gives 'perl'

Well, that worked for Unix. What if your program runs on MacPerl or Windows or VMS, to name a few? There’s no problem—this module can tell which kind of machine you’re using, and it uses that machine’s filename rules by default. (Of course, you’d have that machine’s kind of filename string in $name, in that case.)

There are some related functions also provided by this module. One is the dirname function, which pulls the directory name from a full filename. The module also lets you separate a filename from its extension, or change the default set of filename rules.

Using Only Some Functions from a Module

Suppose you discovered that when you went to add the File::Basename module to your existing program, you already have a subroutine called &dirname—that is, you already have a subroutine with the same name as one of the module’s functions. Now there’s trouble because the new dirname is also implemented as a Perl subroutine (inside the module). What do you do?

In your use declaration, simply give File::Basename an import list showing exactly which function names it should give you, and it’ll supply those and no others. Here, you’ll get nothing but basename:

use File::Basename qw/ basename /;

And here, you ask for no new functions at all:

use File::Basename qw/ /;

This is also frequently written as an empty set of parentheses:

use File::Basename ();

Why would you want to do that? Well, this directive tells Perl to load File::Basename, just as before, but not to import any function names. Importing lets you use the short, simple function names like basename and dirname. But even if you don’t import those names, you can still use the functions. When they’re not imported, though, you have to call them by their full names:

use File::Basename qw/ /;      # import no function names

my $betty = &dirname($wilma);  # uses your own subroutine &dirname
                               # (not shown)

my $name = "/usr/local/bin/perl";
my $dirname = File::Basename::dirname $name;  # dirname from the module

As you see, the full name of the dirname function from the module is File::Basename::dirname. You can always use the function’s full name (once you’ve loaded the module), whether you’ve imported the short name dirname or not.

Most of the time, you’ll want to use a module’s default import list. But you can always override that with a list of your own, if you want to leave out some of the default items. Another reason to supply your own list would be if you wanted to import some function not on the default list, since most modules include some (infrequently needed) functions that are not on the default import list.

As you’d guess, some modules will, by default, import more symbols than others. Each module’s documentation should make it clear which symbols it exports, if any, but you are always free to override the default import list by specifying one of your own, just as we did with File::Basename. Supplying an empty list imports no symbols.

The File::Spec Module

Now you can find out a file’s basename. That’s useful, but you’ll often want to put that together with a directory name to get a full filename. For example, here you want to take a filename like /home/fred/ice-2.1.txt and add a prefix to the basename:

use File::Basename;

print "Please enter a filename: ";
chomp(my $old_name = <STDIN>);

my $dirname  = dirname $old_name;
my $basename = basename $old_name;

$basename =~ s/^/not/;  # Add a prefix to the basename
my $new_name = "$dirname/$basename";

rename($old_name, $new_name)
    or warn "Can't rename '$old_name' to '$new_name': $!";

Do you see the problem here? Once again, you’re making the assumption that filenames will follow the Unix conventions and use a forward slash between the directory name and the basename. Fortunately, Perl comes with a module to help with this problem too.

The File::Spec module is used for manipulating file specifications, which are the names of files, directories, and the other things that are stored on filesystems. Like File::Basename, it understands what kind of system it’s running on, and it chooses the right set of rules every time. But unlike File::Basename, File::Spec is an object-oriented (often abbreviated “OO”) module.

If you’ve never caught the fever of OO, don’t let that bother you. If you understand objects, that’s great; you can use this OO module. If you don’t understand objects, that’s OK, too. You just type the symbols as we show you, and it works just as if you knew what you were doing.

In this case, you learn from reading the documentation for File::Spec that you want to use a method called catfile. What’s a method? It’s just a different kind of function, as far as you’re concerned here. The difference is that you’ll always call the methods from File::Spec with their full names, like this:

use File::Spec;

.
.  # Get the values for $dirname and $basename as earlier
.

my $new_name = File::Spec->catfile($dirname, $basename);

rename($old_name, $new_name)
    or warn "Can't rename '$old_name' to '$new_name': $!";

As you can see, the full name of a method is the name of the module (called a class here), a small arrow (->), and the short name of the method. It is important to use the small arrow rather than the double-colon that we used with File::Basename.

Since you’re calling the method by its full name, though, what symbols does the module import? None of them. That’s normal for OO modules. So you don’t have to worry about having a subroutine with the same name as one of the many methods of File::Spec.

Should you bother using modules like these? It’s up to you, as always. If you’re sure your program will never be run anywhere but on a Unix machine, say, and you’re sure you completely understand the rules for filenames in Unix, then you may prefer to hardcode your assumptions into your programs. But these modules give you an easy way to make your programs more robust in less time—and more portable at no extra charge.

Path::Class

The File::Spec module does work with file paths from just about any platform, but the interface is a bit clunky. The Path::Class module, which doesn’t come with Perl, gives you a more pleasant interface:

my $dir     = dir( qw(Users fred lib) );
my $subdir  = $dir->subdir( 'perl5' );     # Users/fred/lib/perl5
my $parent  = $dir->parent;                # Users/fred

my $windir  = $dir->as_foreign( 'Win32' ); # Usersfredlib