Perldoc
Learn about the perldoc utility in Perl.
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:
perldoc List::Utilperldoc perltocperldoc 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
CPAN distribution; it displays the pure-documentation manual.Moose Moose provides many features beyond Perl’s default OO system. It provides constructors, destructors, accessors, and encapsulation.
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
andperldoc 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.
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?
perldoc -f sort
The
-f
option shows the documentation for a built-in Perl function, such asperldoc -f sort
. If we don’t know the name of the function we want, we can browse the list of available built-ins inperldoc perlfunc
.
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.
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.)
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: