Perl Hacks

Hack #2. Put Perldoc to Work

Do more than just read the documentation.

Perl has a huge amount of documentation available through the perldoc utility—and not just from the command line. These docs cover everything from the core language and tutorials through the standard library and any additional modules you install or even write. perldoc can do more, though.

Here are a few switches and options to increase your productivity.

Find Operator Documentation

The perlfunc document lists every built-in operator in the language in alphabetical order. If you need to know the order of arguments to substr( ), you could type perldoc perlfunc, and then search for the correct occurrence of substr.

Tip

In a decent pager, such as less on a Unix-like system, use the forward slash (/) to begin a search. Type the rest of the name and hit Enter to begin searching. Press n to find the next occurrence and N to find the previous one.

Why search yourself, though? perldoc's -f switch searches perlfunc for you, presenting only the documentation for the named operator. Type instead:

$ perldoc -f substr
            

The program will launch your favorite pager, showing only the documentation for substr. Handy.

Answer a FAQ

The Perl FAQ is a very useful piece of the core documentation, with a table of contents in perlfaq and nine other documents (perlfaq1 through perlfaq9) full of frequently asked questions and their answers.

Searching every document for your question, however, is more tedious than searching perlfunc. (Do skim perlfaq once in a while to see what questions there are, though.) Fortunately, the -q switch allows you to specify a search pattern for FAQ keywords.

If you remember that somewhere the FAQ explains how to shuffle an array, but you can't remember where, try:

$ perldoc -q shuffle
            

As with the -f switch, this will launch your favorite pager to view every question with the term shuffle in the title.

-q also handles regular expressions, so if you want to search for every mention of Perl 6, with or without that blessed space, try:

$ perldoc -q "Perl ?6"
            

Tip

The quotes prevent the shell from interpreting the space as an argument separator.

Webify It

Maybe the command line isn't your thing. Maybe you work in a group of programmers who won't leave their comfortable IDEs long enough to type a few commands—and who certainly won't read documentation from anywhere but the IDE or a web page.

That's okay. perldoc can produce HTML (or any other type of output for which you have a POD translator installed), too. Use the -o switch with your preferred output format. To turn perltoc into HTML, use the command:

$ perldoc -oHTML -dperltoc.html perltoc
            

Tip

The -d switch specifies the destination filename.

Valid HTML formatters include any of Pod::Perldoc::HTML, Pod::Simple::HTML, and Pod::HTML. If you have another formatter of the appropriate name installed, you can use it.

Tip

If you have multiple potential formatters for a type installed, use -Mfull_module_name instead of -o to disambiguate.

Find that Module!

Maybe you already know how to find, slice, and dice the documentation. Have you ever run a program that picked up the wrong version of a module? Sure, you can modify the program to print %INC and @INC and crawl through the output to see what went wrong—but perldoc has to be able to figure out where the module lives to show its documentation. Exploit it!

The -l switch tells perldoc to find the named module (or document) and print its location instead of formatting and displaying the text. Here's where Test::Tutorial and perlunintro live on my system:

$ perldoc -l Test::Tutorial
/usr/lib/perl5/vendor_perl/5.8.7/Test/Tutorial.pod

$ perldoc -l perluniintro
/usr/lib/perl5/5.8.7/pod/perluniintro.pod

Tip

If you have multiple versions of Perl installed, be sure you use the correct version of perldoc; it uses the @INC path in its own version of Perl.

This can be much faster than doing a locate or find and grep from the command line.

Browse the Code

perldoc -l is pretty useful, especially if you want to know where a module is, so that you can look inside it. One more switch makes that even more useful, however. The -m option shows the plain, unrendered text of the named module or document in your favorite pager.

If you suspect that the author of Test::MockObject has hidden some useful methods from you,^[1] browse the source of the module with:

$ perldoc -m Test::MockObject
            

You can't edit the text of the module from here, but being able to read it—or being able to read the raw POD of a module with POD errors that cause its formatting to fail—can be very helpful.

Tip

Likewise, the -u option shows only the unformatted POD source, without the code.

---

^[1] He hasn't.