Chapter 22. CPAN

CPAN (the Comprehensive Perl Archive Network) is the central repository for everything Perl. It contains the collected wisdom of the entire Perl community: hundreds of Perl modules and scripts, several books' worth of documentation, and the entire Perl distribution. If it's written in Perl, and it's helpful and free, it's probably on CPAN. CPAN is mirrored worldwide, and you can find a nearby mirror with the CPAN multiplexer at http://www.perl.com/CPAN. The multiplexer will remember which mirror you choose so that when you visit http://www.perl.com/CPAN/ (note the trailing slash) you'll be automatically redirected to that mirror. Alternatively, you can start at www.cpan.org. The interface is different, but the data is the same.

Once you get to the main CPAN directory, you'll see some subdirectories:

authors: This directory contains numerous subdirectories, one for each contributor of software. For example, if you wanted to find Lincoln Stein's great CGI module[1] and you happened to know for a fact that he wrote it, you could look in authors/Lincoln_Stein. If you didn't know he wrote it, you could look in the modules directory described below.

[1]Now part of the standard Perl distribution.
doc: This directory holds all manner of Perl documentation, including all of Perl's official manpages in several different arrangements and formats, such as text, HTML, PostScript, and Perl's native pod format, documented in Chapter 26, "Plain Old Documentation".
modules: This directory contains modules written either in Perl or in a combination of both Perl and C. See the discussion of the modules directory below.
ports: This directory contains the source code and sometimes also precompiled executable images of Perl ports to operating systems that are not directly supported in the standard distribution, or for which compilers are notoriously hard to come by. These ports are the individual efforts of their respective authors and may not all function precisely as described in this book. These days few systems should require special ports. The index document of this directory is interesting to look through anyway because it also includes information detailing when each system vendor began shipping Perl.
scripts: This directory contains a small collection of diverse Perl programs from all over the world. These are useful as standalone programs and perhaps as examples (although the code isn't subject to quality control checks). Right now, there aren't many programs listed, but we hope this area will become richer in time. The Perl Power Tools project (PPT) is also to be found here. PPT aims to recreate all the standard Unix utilities in Perl. Most of the standard ones are done already, plus some that aren't standard.
src: Within this directory, you will find the source code for the standard Perl distribution. Actually, for two standard Perl distributions. One is marked stable, and the other devel. (The index page for this directory explains the details.) These are really just links to the appropriate versions. As of this writing, stable.tar.gz is a symbolic link to perl-5.6.0.tar.gz,[2] but it will likely point to a higher version number by the time you read this. This giant file contains the full source code and documentation for Perl. Configuration and installation should be relatively straightforward on most platforms. If not, see ports described earlier.

[2] The general scheme is that if the second number in the version is even, it's a maintenance release; if it's odd, it's a development release. The trailing .tar.gz extension, which is sometimes written .tgz, indicates that it's in the standard Internet format of a GNU-zipped tar archive, commonly known as a "tarball".

22.1. The CPAN modules Directory

Although CPAN contains the complete source code for Perl, plus a few binary distributions for systems bereft of C compilers, as well as a smattering of programs, CPAN is best known for its collection of modules.

When we say "modules", we mean three things: 100% pure Perl modules (described in Chapter 11, "Modules", and Chapter 12, "Objects"), extensions (modules depending on C code, described in Chapter 21, "Internals and Externals"), and pragmas (modules containing special instructions for the Perl compiler, described in Chapter 31, "Pragmatic Modules"). There are also module bundles on CPAN. Bundles are collections of modules that interoperate somehow and are typically the result of a module developer wanting to provide a turnkey solution to a set of problems. If one module depends on another module (and possibly a particular version), developers will often bundle the modules together. See Bundle-XML, for instance.

One way to browse the CPAN modules is to visit http://search.cpan.org, which provides a search engine frontend to CPAN. Another way is to visit your local CPAN mirror and enter the modules directory, where you'll see three subdirectories: by-authors, by-category, and by-name. The by-name directory may be the most useful if your browser has search capabilities--although (lamentably) some modules are only available in the author directories. If you search by category, you'll have the following choices:

Perl core modules, language extensions, and documentation tools: This includes pragmas and other standard modules, modules that help you write Perl differently, modules related to the Perl compiler, source filters, and modules related to Perl's pod documentation format. This category also includes modules for generating Java bytecode.
Development support: This category includes modules for creating modules and examining how Perl runs programs.
Operating system interfaces and hardware drivers: Here you'll find modules for interacting with strange entities like operating systems, PalmPilots, and serial ports.
Networking, device control, and interprocess communication: This includes modules that implement network protocols, manipulate network data, operate modems, and control the appliances in your house.
Data types and data type utilities: This category has modules for math, statistics, algorithms, data structures (and their persistent storage), dates and times, object-oriented programming, PDL (the Perl Data Language, for serious number crunching), and POE (the Perl Object Environment, an object-oriented, event-driven scheduler).
Database interfaces: Here you'll find modules that let you operate several dozen database systems from Perl, most of them with Perl's DBI system. This includes the database-specific DBD modules.
User interfaces (character and graphical): This includes modules for manipulating user terminals (command-line editing and curses(3)-style character graphics), as well as Perl/Tk and bindings to Gtk, Gnome, Sx, and Qt for writing your own GUIs in Perl.
Interfaces to or emulations of other programming languages: This category has modules for using other programming languages from Perl or letting you pretend that Perl is something it isn't. If you're interested in using Perl from C or C from Perl, see Chapter 21, "Internals and Externals".
Filenames, filesystems, and file locking: This includes modules for inspecting, creating, locking, and otherwise manipulating files and directories.
String processing, language text processing, parsing, and searching: This category contains modules for manipulating text: hyphenating, wrapping, parsing, stemming, and searching. This includes modules for manipulating PostScript, fonts, XML, and RTF.
Option, argument, parameter, and configuration file processing: This category contains modules for processing command-line arguments (the -x in myperlprog -x) and for managing configuration files (like dot files).
Internationalization and locale: This includes modules for tailoring your Perl program for a particular country and language.
Authentication, security, and encryption: Here you'll find modules for managing user passwords, computing message digests, encrypting data, and authenticating users.
World Wide Web, HTML, HTTP, CGI, MIME: This category has modules that let you create CGI-based web pages, web robots, and web-based content management systems. Other modules let you manage cookies, parse HTML and MIME messages, and manipulate web caches. There is also a special section just for Perl modules that you can embed into the Apache web server.
Server and daemon utilities: This includes modules for creating network and event servers.
Archiving, compression, and conversion: Here you'll find modules for zipping and tarring files, and converting between file formats (even the Apple II file format).
Images, pixmap, and bitmap manipulation, drawing, and graphing: This category contains modules for creating graphs, GIFs, VRML, and for working with the Gimp.
Mail and Usenet news: In this category, you'll find modules for sending, receiving, and filtering mail and netnews.
Control flow utilities: This category contains modules for executing Perl code at odd times.
Filehandle, directory handle, and input/output stream utilities: Here are modules for input from and output to files, including log files. Includes all IO:: modules and an Expect module for automating conversations with network services or other interactive programs.
Microsoft Windows modules: This includes modules for manipulating the Windows registry, ASP, ODBC, OLE, and other technologies specific to Windows.
Miscellaneous modules: Here you'll find modules for astronomy, biology, chemistry, validating credit cards (or invalidating credit cards), mortgage amortizations, audio, video, MIDI, weather, and games.

Chapter 22. CPAN

Contents:

22.1. The CPAN modules Directory