Many programming languages offer support for libraries much as Perl does. Libraries are collections of (mostly) subroutines for a given purpose. In modern Perl, though, it’s more common to use modules than libraries.

A module is a “smart library”. A module will typically offer a collection of subroutines that act as if they were built in functions, for the most part. Modules are smart in that they keep their details in a separate package, only importing what you request. This keeps a module from stomping on your code’s symbols.

Although many useful modules are written in pure Perl, others are written using a language like C. For example, the MD5 algorithm is sort of like a high-powered checksum.^[3] It uses a lot of low-level bit-twiddling that could be done in Perl, but hundreds of times more slowly;^[4] it’s an algorithm that was designed to be efficiently implemented in C. So, the Digest::MD5 module is made to use the compiled C code. When you use that module, it’s as if your Perl had a built in function to calculate MD5 digests.

Maybe your system already has the module you need. But how can you find out which modules are installed? You can use the program inside, which should be available for download from CPAN in the directory http://www.cpan.org/authors/id/P/PH/PHOENIX/.

If none of the modules already available on your system suits your needs, you can search for Perl modules on CPAN at http://search.cpan.org/. To install a module on your system, see the perlmodinstall manpage.

When using a module, you’ll generally put the required use directives at the top of your program. That makes it easy for someone who is installing your program on a new system to see at a glance which modules it needs.

In the rare case that there’s no module to do what you need, an advanced programmer can write a new one, either in Perl or in another language (often C). See the perlmod and perlmodlib manpages for more information.

Many people use Perl to write programs that a web server will run, generally called CGI programs. The CGI module comes with Perl, while the CGI_Lite module is available separately from CPAN. See Section B.16 later in this appendix.

Sometimes you need to know what the current working directory’s name is. (Well, you could often use ".“, but maybe you need to save the name so that you can change back to this directory later.) The Cwd module, which comes with Perl, provides the cwd function, which you can use to determine the current working directory.

use Cwd;

my $directory = cwd;

If you get tired of writing "or die" after every invocation of open or chdir, then maybe the Fatal module is for you. Just tell it which functions to work with, and those will be automatically checked for failure, as if you’d written "or die" and a suitable message after each one. This won’t affect such calls in someone else’s package (that is, code contained within a module you’re using, for example), so don’t use this to fix up poorly written code. It’s just a timesaver, mostly for simple programs in which you don’t need direct control over the error message itself. For example:

use Fatal qw/ open chdir /;

chdir '/home/merlyn';  # "or die" is now supplied automatically

We covered this module in Chapter 13. It’s primary uses are to portably pull the basename or directory name from a full filename:

use File::Basename;

for (@ARGV) {
  my $basename = basename $_;
  my $dirname = dirname $_;
  print "That's file $basename in directory $dirname.
";
}

When you need to copy or move files, the File::Copy module is for you. (It’s often tempting to simply call a system program to do these things, but that’s not portable.) This module provides the functions move and copy, which may be used much as the corresponding system programs would be used:

use File::Copy;

copy("source", "destination")
  or die "Can't copy 'source' to 'destination': $!";

When you need to manipulate a filename (more formally called a "file specification”), it’s generally more portable and reliable to use the File::Spec module than to do the work yourself from Perl. For example, you can use the catfile function to put together a directory name and a filename to produce a long filename (as we saw in Chapter 13), but you don’t have to know whether the system your program is running on uses a forward slash or some other character to separate those. Or you could use the curdir function to get the name of the current directory (”.“, on Unix systems).

The File::Spec module is object-oriented, but you don’t need to understand objects to use it. Just call each function (“method”, really) by using File::Spec and a small arrow before the function’s name, like this:

use File::Spec;

my $current_directory = File::Spec->curdir;
opendir DOT, $current_directory
  or die "Can't open current directory '$current_directory': $!";

When you have an image file, you’ll often want to know what its height and width are. (This is handy for making programs that write HTML, if you wish for an IMG tag to indicate the image’s dimensions.) The Image::Size module, which is available from CPAN, understands the common GIF, JFIF (JPEG), and PNG image types, and some others. For example:

use Image::Size;

# Get the size of fred.png
my($fred_height, $fred_width) = imgsize("fred.png");
die "Couldn't get the size of the image"
  unless defined $fred_height;

If you want your program to be able to send email through an SMTP server (which is the way most of us send email these days, whether you knew that or not), you may use the Net::SMTP module to do the work.^[7] This module, which is available from CPAN, is object-oriented, but you may simply follow the syntax to use it. You will need to change the name of your SMTP host and the other items to make this work on your system. Your system administrator or local expert can tell you what to use. For example:

use Net::SMTP;

my $from = 'YOUR_ADDRESS_GOES_HERE';         # maybe [email protected]
my $site = 'YOUR_SITE_NAME_GOES_HERE';       # maybe bedrock.edu
my $smtp_host = 'YOUR_SMTP_HOST_GOES_HERE';  # maybe mail or mailhost
my $to = '[email protected]';

my $smtp = Net::SMTP->new($smtp_host, Hello => $site);

$smtp->mail($from);
$smtp->to($to);
$smtp->data( );

$smtp->datasend("To: $to
");
$smtp->datasend("Subject: A message from my Perl program.
");
$smtp->datasend("
");
$smtp->datasend("This is just to let you know,
");
$smtp->datasend("I don't care what those other people say about you,
");
$smtp->datasend("I still think you're doing a great job.
");
$smtp->datasend("
");
$smtp->datasend("Have you considered enacting a law naming Perl 
");
$smtp->datasend("the national programming language?
");

$smtp->dataend( );                             # Not datasend!
$smtp->quit;

If you need access to the POSIX (IEEE Std 1003.1) functions, the POSIX module is for you. It provides many functions that C programmers may be used to, such as trigonometric functions (asin, cosh), general mathematical functions (floor, frexp), character-identification functions (isupper, isalpha), low-level IO functions (creat, open), and some others (asctime, clock). You’ll probably want to call each of these with its “full” name; that is, with POSIX and a pair of colons as a prefix to the function’s name:

use POSIX;

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

$! = 0;  # Clear out the error indicator
my($num, $leftover) = POSIX::strtod($str);

if ($str eq '') {
  print "That string was empty!
";
} elsif ($leftover) {
  my $remainder = substr $str, -$leftover;
  print "The string '$remainder' was left after the number $num.
";
} elsif ($!) {
  print "The conversion function complained: $!
";
} else {
  print "The seemingly-valid number was $num.
";
}

The Sys::Hostname module provides the hostname function, which will be the network name of your machine, if that can be determined. (If it can’t be determined, perhaps because your machine is not on the Internet or not properly configured, the function will die automatically; there’s no point in using or die here.) For example:

use Sys::Hostname;
my $host = hostname;
print "This machine is known as '$host'.
";

The Text::Wrap module supplies the wrap function, which lets you implement simple word-wrapping. The first two parameters specify the indentation of the first line and the others, respectively; the remaining parameters make up the paragraph’s text:

use Text::Wrap;

my $message = "This is some sample text which may be longer " .
  "than the width of your output device, so it needs to " .
  "be wrapped to fit properly as a paragraph. ";
$message x= 5;

print wrap("	", "", "$message
");

If you have a time (for example, from the time function) that needs to be converted to a list of year, month, day, hour, minute, and second values, you can do that with Perl’s built-in localtime function in a list context.^[8] (In a scalar context, that gives a nicely formatted string representing the time, which is more often what you’d want.) But if you need to go in the other direction, you may use the timelocal function from the Time::Local module instead. It’s important to note that the value of $mon and $year for January 2004 are not 1 and 2004 as you might expect, so be sure to read the documentation before you use this module. For example:

use Time::Local;

my $time = timelocal($sec, $min, $hr, $day, $mon, $year);

If you’ve used other languages, you’ve probably seen the ability to declare constants in one way or another. Constants are handy for making a setting just once, near the beginning of a program, but that can be easily updated if the need arises. Perl can do this with the package-scoped constant pragma, which tells the compiler that a given identifier has a constant value, which may thus be optimized wherever it appears. For example:

use constant DEBUGGING => 0;
use constant ONE_YEAR => 365.2425 * 24 * 60 * 60;

if (DEBUGGING) {
  # This code will be optimized away unless DEBUGGING is turned on
  ...
}

Perl’s diagnostic messages often seem somewhat cryptic, at least the first time you see them. But you can always look them up in the perldiag manpage to find out what they mean, and often a little about what’s likely to be the problem and how to fix it. But you can save yourself the trouble of searching that manpage if you use the diagnostics pragma, which tells Perl to track down and print out the related information for any message. Unlike most pragmas, though, this one is not intended for everyday use, as it makes your program read the entire perldiag manpage just to get started. (This is potentially a significant amount of overhead, both in terms of time and memory.) Use this pragma only when you’re debugging and expecting to get error message you don’t yet understand. It affects your entire program. The syntax is:

use diagnostics;

It’s nearly always best to install modules in the standard directories, so that they’re available for everyone, but only the system administrator can do that. If you install your own modules, you’ll have to store them in your own directories—so, how will Perl know where to find them? That’s what the lib pragma is all about. It tells Perl that the given directory is the first place to look for modules. (That means that it’s also useful for trying out a new release of a given module.) It affects all modules loaded from this point on. The syntax is:

use lib '/home/rootbeer/experimental';

Be sure to use a nonrelative pathname as the argument, since there’s no telling what will be the current working directory when your program is run. This is especially important for CGI programs (that is, programs run by a web server).

You’ve been using use strict for a while already without having to understand that it’s a pragma. It’s lexically scoped, and it enforces some good programming rules. See its documentation to learn what restrictions are available in your release of Perl.

In the rare case that you truly need a global variable while use strict is in effect, you may declare it with the vars pragma.^[9] This package-scoped pragma tells Perl that you are intentionally using one or more global variables:

use strict;
use vars qw/ $fred $barney /;

$fred = "This is a global variable, but that's all right.
";

Starting in Perl version 5.6, you may choose to have lexically scoped warnings with the warnings pragma.^[10] That is, rather than using the -w option crudely to turn warnings on or off for the entire program at once, you may specify that you want no warnings about undefined values in just one section of code, while other warnings should be available. This also serves as a signal to the maintenance programmer that says, “I know that this code would produce warnings, but I know what I’m doing anyway.” See the documentation for this pragma to learn about the categories of warnings available in your release of Perl.

Perl can directly access some system databases, sometimes with the help of a module. These are databases like the Windows Registry (which holds machine-level settings), or the Unix password database (which lists which username corresponds to which number, and related information), as well as the domain-name database (which lets you translate an IP number into a machine name, and vice versa).

If you’d like to access your own flat-file databases from Perl, there are modules to help you with doing that (seemingly a new one every month or two, so any list here would be out of date). You can even do quite a bit without a module, with what we give in Chapter 16.

Relational databases include Sybase, Oracle, Informix, mysql, and others. These are complex enough that you generally do need to know about modules to use them. But if you use the DBI module, whose name stands for “database-independent,” you can minimize your dependence upon any one type of database—then, if you have to move from mysql to Oracle, say, you might not even need to change anything at all in your program.

The tr/// operator looks like a regular expression, but it’s really for transliterating one group of characters into another. It can also efficiently count selected characters. See the perlop manpage.

Here documents are a useful form of multiline string quoting; see the perldata manpage.

All of the basic mathematical functions (square root, cosine, logarithm, absolute value, and many others) are available as built in functions; see the perlfunc manpage for details. Some others (like tangent or base-10 logarithm) are omitted, but those may be easily created from the basic ones, or loaded from a simple module that does so. (See the POSIX module for many common math functions.)

Although the core of Perl doesn’t directly support them, there are modules available for working with complex numbers. These overload the normal operators and functions, so that you can still multiply with * and get a square root with sqrt, even when using complex numbers. See the Math::Complex module.

You can do math with arbitrarily large numbers with an arbitrary number of digits of accuracy. For example, you could calculate the factorial of two thousand, or determine π to ten-thousand digits. See the Math::BigInt and Math::BigFloat modules.

We mentioned (in Chapter 17) the map and grep list-processing operators. They can do more than we could include here; see the perlfunc manpage for more information and examples.

With the splice operator, you can add items to the middle of an array, or remove them, letting the array grow or shrink as needed. (Roughly, this is like what substr lets you do with strings.) This effectively eliminates the need for linked lists in Perl. See the perlfunc manpage.

The standard functions for System V IPC (interprocess communication) are all supported by Perl, so you can use message queues, semaphores, and shared memory. Of course, an array in Perl isn’t stored in a chunk of memory in the same way^[11] that an array is stored in C, so shared memory can’t share Perl data as-is. But there are modules that will translate data, so that you can pretend that your Perl data is in shared memory. See the perlfunc manpage and the perlipc module.

Perl has full support for TCP/IP sockets, which means that you could write a web server in Perl, or a web browser, Usenet news server or client, finger daemon or client, FTP daemon or client, SMTP or POP or SOAP server or client, or either end of pretty much any other kind of protocol in use on the Internet. Of course, there’s no need to get into the low-level details yourself; there are modules available for all of the common protocols. For example, you can make a web server or client with the LWP module and one or two lines of additional code.^[12] The LWP module (actually, a tightly integrated set of modules, which together implement nearly everything that happens on the Web) is also a great example of high-quality Perl code, if you’d like to copy from the best. For other protocols, search for a module with the protocol’s name.

References allow us to make complex data structures in Perl. For example, suppose you want a two-dimensional array? You can do that,^[18] or you can do something much more interesting, like have an array of hashes, a hash of hashes, or a hash of arrays of hashes.^[19] See the perldsc (data-structures cookbook) and perllol (lists of lists) manpages.

Yes, Perl has objects; it’s buzzword-compatible with all of those other languages. Object-oriented (OO) programming lets you create your own user-defined datatypes with associated abilities, using inheritance, overriding, and dynamic method lookup.^[20]

Unlike some object-oriented languages, though, Perl doesn’t force you to use objects. (Even many object-oriented modules can be used without understanding objects.) But if your program is going to be larger than N lines of code, it may be more efficient for the programmer (if a tiny bit slower at runtime) to make it object-oriented. No one knows the precise value of N, but we estimate it’s around a few thousand or so. See the perlobj and perlboot manpages for a start, and Damian Conway’s excellent Object-Oriented Perl (Manning Press) for more advanced information.

Odd as it may sound at first, it can be useful to have a subroutine without a name. Such subroutines can be passed as parameters to other subroutines, or they can be accessed via arrays or hashes to make jump tables.

Closures are a powerful concept that comes to Perl from the world of Lisp. A closure is (roughly speaking) an anonymous subroutine with its own private data.