[ Perl tips index ]
[ Subscribe to Perl tips ]
While opinions vary about the elegance and beauty of Perl, many people agree that Perl is one of the most well documented programming language in use today. Better still, much of that documentation is freely available and comes standard with Perl.
Most of Perl's documentation is accessible through the perldoc utility. Perldoc reads POD (plain old documentation) out of .pod files or from within the source of modules and programs themselves. This Perl tip is going to discuss some of the documents and perldoc switches that we find invaluable.
To learn more about how to write your own POD documentation read perldoc perlpod.
To read the documentation from any installed module we can write:
perldoc <module_name>
for example:
perldoc CGI
For multi-part module names, such as Scalar::Util, we can type either of
the following:
perldoc Scalar::Util;
perldoc Scalar/Util;
although the first form is more regularly seen.
Sometimes we want to browse the source of a module without having to find out where the module is installed. To do this, we can use the -m switch to Perldoc:
perldoc -m CGI
Be aware that under older versions of perldoc this will display the source
of the file containing the POD. For modules that separate code and pod,
perldoc -m may not do what you expect.
To find out which modules were installed with Perl by default read:
perldoc perlmodlib
To see a list of the modules you've installed since Perl was installed read:
perldoc perllocal
Note that this page may not always be accurate. Modules installed into
user directories are not typically added to the perllocal list. Further,
the perllocal list may not writable by the user at the time of module
installation. Finally, modules installed using your operating
system's packaging system (eg, RedHat RPM files, or Debian .deb files)
rarely appear in perllocal.
Perhaps the most used switch to Perldoc is -f. This provides a full description of any Perl function. Thus, to find out all we could ever want to know about print, we'd type:
perldoc -f print
These pages provide information about what arguments our functions take, what they return, example uses, caveats and more.
To find the documentation for the file test operations type:
perldoc -f -x
The -f switch pulls its data from the perlfunc page. Thus if you wish to
browse Perl's functions you may wish to start there.
Perl has a number of FAQ files. These range from general questions through to quite specific topics.
perldoc perlfaq
Perl has a great focus on laziness. As a result you can search the FAQs with a regular expression, from the command line. To do this, provide a regular expression (or a string of interest) to perldoc with the -q flag:
perldoc -q 'CGI script'
perldoc -q 'CGI script.*browser'
This then searches the headings (questions) of the entries in the FAQs for your matches. You can also pass in keywords which interest you:
perldoc -q CGI script
which returns more results than the previous search.
Well beyond the few uses above, Perl has a great many more pages. To find a list of all of these read:
perldoc perl
or (to find these broken into more meaningful sections):
perldoc perltoc
In particular, the tutorials are well written and a great place to start to learn about new topics. Popular tutorials include:
perldoc perlreftut (References)
perldoc perlopentut (Open)
perldoc perldebtut (Debugging)
perldoc perlretut (Regular expressions)
perldoc perlboot (OO for beginners)
perldoc perltoot (OO part 1)
perldoc perltootc (OO part 2)
perldoc perlthrtut (Threads)
perldoc perlxstut (XS)
[ Perl tips index ]
[ Subscribe to Perl tips ]
This Perl tip and associated text is copyright Perl Training Australia. You may freely distribute this text so long as it is distributed in full with this Copyright noticed attached.
If you have any questions please don't hesitate to contact us:
| Email: | contact@perltraining.com.au |
| Phone: | 03 9354 6001 (Australia) |
| International: | +61 3 9354 6001 |
Copyright Perl Training Australia. Contact us at contact@perltraining.com.au
