Mastering Modern Perl: Writing Efficient and Maintainable Code/

...

/

Perldoc

Perldoc

Learn about the perldoc utility in Perl.

We'll cover the following...

Perl respects your time; Perl culture values documentation. The language ships with thousands of pages of core documentation. The perldoc utility is part of every complete Perl installation. This utility can display the core docs, as well as the documentation of every Perl module we have installed—whether a core module or one installed from CPAN.

Reading documentation

We can use perldoc to read the documentation for a module or part of the core documentation:

Press + to interact
perldoc List::Util
perldoc perltoc
perldoc Moose::Manual

  • The first example displays the documentation of the List::Util module; these docs are in the module itself.

  • The second example is the table of contents of the core docs. This file is pure documentation.

  • The third example requires us to install the MooseMoose provides many features beyond Perl’s default OO system. It provides constructors, destructors, accessors, and encapsulation. CPAN distribution; it displays the pure-documentation manual.

The perldoc utility hides all of these details for us; there’s no distinction between reading the documentation for a core library such as List::Util or one installed from the CPAN.

Note: Perldoc and CPAN modules host recent versions of their documentation. CPAN indexes can be searched here. Other distributions such as ActivePerl and Strawberry Perl provide local documentation in HTML formats.

Perl culture values documentation so much that even external libraries follow an excellent example of the core language documentation. The standard documentation template includes a description of the module, sample uses, and a detailed explanation of the module and its interface. While the amount of documentation varies by author, the form of the documentation is remarkably consistent.

How to read the documentation

Perl has lots of documentation. Where do we start? Here is a quick overview:

  • perldoc perltoc: This displays the table of contents of the core documentation.

  • perldoc perlfaq: This is the table of contents for Frequently Asked Questions about Perl.


  • perldoc perlop and perldoc perlsyn: These document Perl’s symbolic operators and syntactic constructs.

  • perldoc perldiag: This explains the meanings of Perl’s warning messages.


  • perldoc perlvar: This lists all of Perl’s symbolic variables.
  

We don’t have to memorize anything in these docs. We can skim them for a great language overview and come back to them when we have questions.

The perldoc utility

The perldoc utility can do much, much more.

Press + to interact
perldoc -q sort

  • Use the -q option with a keyword to search the Perl FAQ. For example, perldoc -q sort returns the following three questions: 

    • How do I sort an array by (anything)?

    • How do I sort a hash (optionally by value instead of key)? 

    • How can I always keep my hash sorted?

Press + to interact
perldoc -f sort

  • The -f option shows the documentation for a built-in Perl function, such as perldoc -f sort. If we don’t know the name of the function we want, we can browse the list of available built-ins in perldoc perlfunc.

Press + to interact
perldoc -v $PID

  • The -v option looks up a built-in variable. For example, perldoc -v $PID explains
    $PID, which is the variable containing the current program’s process id. Depending on our shell, we may have to quote the variable appropriately.

Press + to interact
perldoc -l sort

  • The -l option shows the path to the file containing the documentation. (A module may have a separate .pod file, in addition to its .pm file.)

Press + to interact
perldoc -m sort

  • The -m option displays the entire contents of the module, code, and all, without any special formatting.

Plain Old Documentation

Perl uses a documentation format called POD, short for Plain Old Documentation. perldoc perlpod describes how POD works. Other POD tools include the podchecker, which validates the structure of POD documents, and the Pod::Webserver CPAN module, which displays local POD as HTML through a minimal web server.

Try it yourself

Try the perldoc commands in the terminal below:

Terminal 1
Terminal
Loading...

Ask