A Tour of the Perl Library (Programming Perl)

30.2. A Tour of the Perl Library

You'll save an enormous amount of time if you make the effort to familiarize yourself with the standard Perl library, because there's no reason to reinvent those particular wheels. You should be aware, however, that this collection contains a wide range of material. Although some libraries may be extremely helpful, others might be completely irrelevant to your needs. For example, if you're only writing in 100% pure Perl, those modules that support the dynamic loading of C and C++ extensions aren't going to help you much.

Perl expects to find library modules somewhere in its library "include" path, @INC. This array specifies the ordered list of directories Perl searches when you load in some library code using the keywords do, require, or use. You can easily list out those directories by calling Perl with the -V switch for Very Verbose Version information, or with this simple code:

% perl -le "print foreach @INC"
/usr/libdata/perl5/sparc-openbsd/5.00503
/usr/local/libdata/perl5/sparc-openbsd/5.00503
/usr/libdata/perl5
/usr/local/libdata/perl5
/usr/local/libdata/perl5/site_perl/sparc-openbsd
/usr/libdata/perl5/site_perl/sparc-openbsd
/usr/local/libdata/perl5/site_perl
/usr/libdata/perl5/site_perl
.

That's only one sample of possible output. Every installation of Perl uses its own paths. The important thing is that, although contents will vary depending upon your vendor's and your site's installation policy, you can rely upon all standard libraries being installed with Perl. If you want to find out where a file was actually loaded from, consult the %INC variable. For a module file, you can find exactly where Perl is getting it from with this command:

% perldoc -l MODULE

If you look through the directories in @INC and their subdirectories, you'll find several different kinds of files installed. Most have names ending in .pm, but some end in .pl, .ph, .al, or .so. The ones that most interest you are the first set, because a suffix of .pm indicates that the file is a proper Perl module. More on those in a minute.

The few files you see there ending in .pl are those old Perl libraries we mentioned earlier. They are included for compatibility with ancient releases of Perl from the 80s and early 90s. Because of this, Perl code that worked back in, say, 1990, should continue to behave properly without any fuss even if you have a modern version of Perl installed. When writing new code that makes use of the standard Perl library, you should always elect to use the .pm version over any .pl, where possible. That's because modules don't pollute your namespace the way many of the old .pl files do.

One note on the use of the .pl extension: it means Perl library, not Perl program. Although .pl is sometimes used to identify Perl programs on web servers that need to distinguish executable programs from static content in the same directory, we suggest that you use a suffix of .plx instead to indicate an executable Perl program. (Similar advice holds for operating systems that choose interpreters based on filename extensions.)

Files with extensions of .al are small pieces of larger modules will be automatically loaded when you use their parent .pm file. If you build your module layout using the standard h2xs tool that comes with Perl (and if you haven't used Perl's -A flag), the make install procedure will use the AutoLoader module to create these little .al files for you.

The .ph files were made by the standard h2ph program, a somewhat aging but still occasionally necessary tool that does its best to translate C preprocessor directives into Perl. The resulting .ph files contain constants sometimes needed by low-level functions like ioctl, fcntl, or syscall. (Nowadays most of these values are more conveniently and portably available in standard modules such as the POSIX, Errno, Fcntl, or Socket modules.) See perlinstall for how to install these optional but sometimes important components.

One last file extension you might encounter while poking around is .so (or whatever your system uses for shared libraries). These .so files are platform-dependent portions of extension modules. Originally written in C or C++, these modules have been compiled into dynamically relocatable object code. The end user doesn't need to be aware of their existence, however, because the module interface hides them. When the user code says require Module or use Module, Perl loads Module.pm and executes it, which lets the module pull in any other necessary pieces, such as Module.so or any autoloaded .al components. In fact, the module could load anything it jolly well pleases, including 582 other modules. It could download all of CPAN if it felt like it, and maybe the last two years of freshmeat.net archives.

A module is not just a static chunk of code in Perl. It's an active agent that figures out how to implement an interface on your behalf. It may follow all the standard conventions, or it may not. It's allowed to do anything to warp the meaning of the rest of your program, up to and including translating the rest of your program into SPITBOL. This sort of chicanery is considered perfectly fair as long as it's well documented. When you use such a Perl module, you're agreeing to its contract, not a standard contract written by Perl.

So you'd best read the fine print.