The second hack in the book Perl Hacks (no link; if you download it and send me $2 and Ovid $0.50 via PayPal or wherever, we get a lot more money than we would if you bought a printed copy from the publisher, grumble grumble) talks about perldoc for a good reason. If you don't take advantage of Perl 5's copious documentation, you'll struggle learning Perl 5, far more than necessary.
(The first hack in the book is to look up distributions and documentation on
the CPAN. As mst says, CPAN
is my language.) Note that well-behaved CPAN distributions also include
copious documentation which integrates with
perldoc. I miss this
in other languages.
The examples here assume you use
perldoc from the command line. If that's not the case -- if you have them installed on your system in HTML form or if you prefer to browse them on perldoc.perl.org, the suggestions will still work with modifications.
Start by running
perldoc perltoc. You don't have to know or understand all of this, but it gives you an overview of all of the documentation included as part of a complete Perl 5 installation. If you've never read any of the documentation before -- if you're a novice to Perl 5 in general, perhaps -- then
perldoc perlintro is a quick survey of what you can do with Perl. It does presume some familiarity with programming, but if you're reading this I presume the same.
Other documentation worth skimming includes
perldoc perlglossary. The former will help you as a neophyte
understand what makes decent Perl and the latter explains several of the terms
of art in the Perl community. You should also read
perldoc, as it includes gems many Perl gurus don't know.
Operator and Builtin Documentation
The most useful
perldoc flag is
-f. After eleven
years with the language, syntax rarely fools me, but I still can't remember all
of the return values of
localtime in the
right order, and I can't always remember all of the arguments to
perldoc -f name looks through
perlfunc and displays the documentation of the builtin named
name. I use this regularly:
$ perldoc -f splice splice ARRAY,OFFSET,LENGTH,LIST splice ARRAY,OFFSET,LENGTH splice ARRAY,OFFSET splice ARRAY Removes the elements designated by OFFSET and LENGTH from an array, and replaces them with the elements of LIST, if any. In list context, returns the elements removed from the array. In scalar context, returns the last element removed, or "undef" if no elements are removed. The array grows or shrinks as necessary. If OFFSET is negative then it starts that far from the end of the array. If LENGTH is omitted, removes everything from OFFSET onward. If LENGTH is negative, removes the elements from OFFSET onward except for -LENGTH elements at the end of the array. If both OFFSET and LENGTH are omitted, removes everything. If OFFSET is past the end of the array, perl issues a warning, and splices at the end of the array.
This is handy if you remember the name of the builtin, but not its exact
syntax or semantics. When I can't remember what I want, I read a
couple of pages into
perldoc perlfunc, which categorizes builtins
by their uses.
Occasionally the difference between a Perl 5 operator and builtin is
significant, so you have to trawl through
perldoc perlop for more
details. That's rarely an issue for me, but that may be how I program. Be
aware of the distinction and be willing to check the other document, if
Perl 5 also includes a copious FAQ which contains a wealth of information
perldoc perlfaq is a great place to start, but when
I need to look something up in the FAQ, I use the
-q option to
$ perldoc -q number Found in /usr/share/perl/5.10/pod/perlfaq4.pod Why am I getting long decimals (eg, 19.9499999999999) instead of the numbers I should be getting (eg, 19.95)? Internally, your computer represents floating-point numbers in binary. Digital (as in powers of two) computers cannot store all numbers exactly. Some real numbers lose precision in the process. This is a problem with how computers store numbers and affects all computer languages, not just Perl. perlnumber shows the gory details of number representations and conversions. To limit the number of decimal places in your numbers, you can use the printf or sprintf function. See the "Floating Point Arithmetic" for more details. printf "%.2f", 10/3; my $number = sprintf "%.2f", 10/3;
This relies on a keyword search, so you have to get a keyword in the title of a question right, but if you browse the titles of the FAQ, you'll get some idea of the questions in the FAQ and the answers you can expect.
I tend to use the
-q switches when I
know I need something in the Perl 5 documentation but I can't remember