This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perldebtut 1.10 from Richard Foley, plus Celsius and Fahrenheit.
[perl5.git] / pod / perl.pod
CommitLineData
a0d0e21e
LW
1=head1 NAME
2
3perl - Practical Extraction and Report Language
4
5=head1 SYNOPSIS
6
19799a22
GS
7B<perl> S<[ B<-sTuU> ]> S<[ B<-hv> ] [ B<-V>[:I<configvar>] ]>
8 S<[ B<-cw> ] [ B<-d>[:I<debugger>] ] [ B<-D>[I<number/list>] ]>
9 S<[ B<-pna> ] [ B<-F>I<pattern> ] [ B<-l>[I<octal>] ] [ B<-0>[I<octal>] ]>
10 S<[ B<-I>I<dir> ] [ B<-m>[B<->]I<module> ] [ B<-M>[B<->]I<'module...'> ]>
11 S<[ B<-P> ]> S<[ B<-S> ]> S<[ B<-x>[I<dir>] ]>
12 S<[ B<-i>[I<extension>] ]> S<[ B<-e> I<'command'> ]
13 [ B<--> ] [ I<programfile> ] [ I<argument> ]...>
c07a80fd 14
4755096e 15For ease of access, the Perl manual has been split up into several sections:
a0d0e21e 16
fb9cefb4 17 perl Perl overview (this section)
fb9cefb4
GS
18 perlfaq Perl frequently asked questions
19 perltoc Perl documentation table of contents
4755096e 20 perlbook Perl book information
760ac839 21
fb9cefb4 22 perlsyn Perl syntax
4755096e 23 perldata Perl data structures
fb9cefb4 24 perlop Perl operators and precedence
c2e66d9e
GS
25 perlsub Perl subroutines
26 perlfunc Perl builtin functions
4755096e
GS
27 perlreftut Perl references short introduction
28 perldsc Perl data structures intro
4755096e 29 perlrequick Perl regular expressions quick start
c2e66d9e
GS
30 perlpod Perl plain old documentation
31 perlstyle Perl style guide
32 perltrap Perl traps for the unwary
4755096e 33
c2e66d9e
GS
34 perlrun Perl execution and options
35 perldiag Perl diagnostic messages
4755096e 36 perllexwarn Perl warnings and their control
10862624 37 perldebtut Perl debugging tutorial
4755096e
GS
38 perldebug Perl debugging
39
fb9cefb4 40 perlvar Perl predefined variables
c2e66d9e
GS
41 perllol Perl data structures: arrays of arrays
42 perlopentut Perl open() tutorial
43 perlretut Perl regular expressions tutorial
2e1d04bc 44
4755096e
GS
45 perlref Perl references, the rest of the story
46 perlre Perl regular expressions, the rest of the story
fb9cefb4
GS
47 perlform Perl formats
48 perllocale Perl locale support
4755096e 49 perlunicode Perl unicode support
760ac839 50
c2e66d9e
GS
51 perlipc Perl interprocess communication
52 perlfork Perl fork() information
53 perlnumber Perl number semantics
54 perlthrtut Perl threads tutorial
55
56 perlport Perl portability guide
57 perlsec Perl security
58
694468e3 59 perlboot Perl OO tutorial for beginners
19799a22
GS
60 perltoot Perl OO tutorial, part 1
61 perltootc Perl OO tutorial, part 2
fb9cefb4 62 perlobj Perl objects
fb9cefb4 63 perlbot Perl OO tricks and examples
4755096e
GS
64 perltie Perl objects hidden behind simple variables
65
c2e66d9e
GS
66 perlmod Perl modules: how they work
67 perlmodlib Perl modules: how to write and use
68 perlmodinstall Perl modules: how to install from CPAN
69 perlnewmod Perl modules: preparing a new module for distribution
760ac839 70
4755096e
GS
71 perlfaq1 General Questions About Perl
72 perlfaq2 Obtaining and Learning about Perl
73 perlfaq3 Programming Tools
74 perlfaq4 Data Manipulation
75 perlfaq5 Files and Formats
76 perlfaq6 Regexes
77 perlfaq7 Perl Language Issues
78 perlfaq8 System Interaction
79 perlfaq9 Networking
760ac839 80
4755096e 81 perlcompile Perl compiler suite intro
760ac839 82
fb9cefb4 83 perlembed Perl ways to embed perl in your C or C++ application
055fd3a9 84 perldebguts Perl debugging guts and tips
fb9cefb4 85 perlxstut Perl XS tutorial
4755096e 86 perlxs Perl XS application programming interface
fb9cefb4
GS
87 perlguts Perl internal functions for those doing extensions
88 perlcall Perl calling conventions from C
4755096e
GS
89 perlutil utilities packaged with the Perl distribution
90 perlfilter Perl source filters
91 perldbmfilter Perl DBM filters
954c1994
GS
92 perlapi Perl API listing (autogenerated)
93 perlintern Perl internal functions (autogenerated)
4755096e 94 perlapio Perl internal IO abstraction interface
e50bb9a1 95 perltodo Perl things to do
e8cd7eae 96 perlhack Perl hackers guide
4755096e 97
fb9cefb4 98 perlhist Perl history records
4755096e
GS
99 perldelta Perl changes since previous version
100 perl56delta Perl changes in version 5.6
101 perl5005delta Perl changes in version 5.005
102 perl5004delta Perl changes in version 5.004
d516a115 103
49877630
GS
104 perlamiga Perl notes for Amiga
105 perlcygwin Perl notes for Cygwin
106 perldos Perl notes for DOS
107 perlhpux Perl notes for HP-UX
da369004 108 perlmachten Perl notes for Power MachTen
49877630
GS
109 perlos2 Perl notes for OS/2
110 perlos390 Perl notes for OS/390
c2e66d9e 111 perlposix-bc Perl notes for POSIX-BC
49877630
GS
112 perlvms Perl notes for VMS
113 perlwin32 Perl notes for Windows
114
a0d0e21e
LW
115(If you're intending to read these straight through for the first time,
116the suggested order will tend to reduce the number of forward references.)
117
19799a22 118By default, the manpages listed above are installed in the
fc952dec
CS
119F</usr/local/man/> directory.
120
121Extensive additional documentation for Perl modules is available. The
122default configuration for perl will place this additional documentation
123in the F</usr/local/lib/perl5/man> directory (or else in the F<man>
124subdirectory of the Perl library directory). Some of this additional
125documentation is distributed standard with Perl, but you'll also find
126documentation for third-party modules there.
127
128You should be able to view Perl's documentation with your man(1)
129program by including the proper directories in the appropriate start-up
130files, or in the MANPATH environment variable. To find out where the
131configuration has installed the manpages, type:
16d20bd9 132
760ac839 133 perl -V:man.dir
16d20bd9 134
fc952dec
CS
135If the directories have a common stem, such as F</usr/local/man/man1>
136and F</usr/local/man/man3>, you need only to add that stem
137(F</usr/local/man>) to your man(1) configuration files or your MANPATH
138environment variable. If they do not share a stem, you'll have to add
139both stems.
16d20bd9
AD
140
141If that doesn't work for some reason, you can still use the
4633a7c4
LW
142supplied F<perldoc> script to view module information. You might
143also look into getting a replacement man program.
16d20bd9 144
a0d0e21e
LW
145If something strange has gone wrong with your program and you're not
146sure where you should look for help, try the B<-w> switch first. It
147will often point out exactly where the trouble is.
148
149=head1 DESCRIPTION
150
5f05dabc 151Perl is a language optimized for scanning arbitrary
a0d0e21e
LW
152text files, extracting information from those text files, and printing
153reports based on that information. It's also a good language for many
154system management tasks. The language is intended to be practical
155(easy to use, efficient, complete) rather than beautiful (tiny,
94d58c47
PP
156elegant, minimal).
157
aa689395
PP
158Perl combines (in the author's opinion, anyway) some of the best
159features of C, B<sed>, B<awk>, and B<sh>, so people familiar with
160those languages should have little difficulty with it. (Language
161historians will also note some vestiges of B<csh>, Pascal, and even
14218588 162BASIC-PLUS.) Expression syntax corresponds closely to C
a0d0e21e
LW
163expression syntax. Unlike most Unix utilities, Perl does not
164arbitrarily limit the size of your data--if you've got the memory,
aa689395 165Perl can slurp in your whole file as a single string. Recursion is of
0f31cffe 166unlimited depth. And the tables used by hashes (sometimes called
aa689395 167"associative arrays") grow as necessary to prevent degraded
0f31cffe 168performance. Perl can use sophisticated pattern matching techniques to
14218588 169scan large amounts of data quickly. Although optimized for
aa689395
PP
170scanning text, Perl can also deal with binary data, and can make dbm
171files look like hashes. Setuid Perl scripts are safer than C programs
14218588 172through a dataflow tracing mechanism that prevents many stupid
aa689395
PP
173security holes.
174
175If you have a problem that would ordinarily use B<sed> or B<awk> or
176B<sh>, but it exceeds their capabilities or must run a little faster,
177and you don't want to write the silly thing in C, then Perl may be for
178you. There are also translators to turn your B<sed> and B<awk>
179scripts into Perl scripts.
a0d0e21e
LW
180
181But wait, there's more...
182
19799a22
GS
183Begun in 1993 (see L<perlhist>), Perl version 5 is nearly a complete
184rewrite that provides the following additional benefits:
a0d0e21e 185
19799a22 186=over
a0d0e21e 187
19799a22 188=item * modularity and reusability using innumerable modules
a0d0e21e 189
19799a22 190Described in L<perlmod>, L<perlmodlib>, and L<perlmodinstall>.
a0d0e21e 191
19799a22 192=item * embeddable and extensible
a0d0e21e 193
19799a22
GS
194Described in L<perlembed>, L<perlxstut>, L<perlxs>, L<perlcall>,
195L<perlguts>, and L<xsubpp>.
a0d0e21e 196
19799a22 197=item * roll-your-own magic variables (including multiple simultaneous DBM implementations)
a0d0e21e 198
19799a22 199Described in L<perltie> and L<AnyDBM_File>.
a0d0e21e 200
19799a22 201=item * subroutines can now be overridden, autoloaded, and prototyped
a0d0e21e 202
19799a22 203Described in L<perlsub>.
a0d0e21e 204
19799a22 205=item * arbitrarily nested data structures and anonymous functions
a0d0e21e 206
19799a22 207Described in L<perlreftut>, L<perlref>, L<perldsc>, and L<perllol>.
a0d0e21e 208
19799a22 209=item * object-oriented programming
a0d0e21e 210
19799a22 211Described in L<perlobj>, L<perltoot>, and L<perlbot>.
a0d0e21e 212
19799a22 213=item * compilability into C code or Perl bytecode
a0d0e21e 214
19799a22 215Described in L<B> and L<B::Bytecode>.
a0d0e21e 216
19799a22 217=item * support for light-weight processes (threads)
a0d0e21e 218
19799a22 219Described in L<perlthrtut> and L<Thread>.
a0d0e21e 220
19799a22 221=item * support for internationalization, localization, and Unicode
a0d0e21e 222
19799a22 223Described in L<perllocale> and L<utf8>.
a0d0e21e 224
19799a22 225=item * lexical scoping
a0d0e21e 226
19799a22 227Described in L<perlsub>.
a0d0e21e 228
19799a22 229=item * regular expression enhancements
a0d0e21e 230
19799a22 231Described in L<perlre>, with additional examples in L<perlop>.
a0d0e21e 232
14218588 233=item * enhanced debugger and interactive Perl environment, with integrated editor support
a0d0e21e 234
19799a22 235Described in L<perldebug>.
a0d0e21e 236
19799a22 237=item * POSIX 1003.1 compliant library
5f05dabc 238
19799a22 239Described in L<POSIX>.
5f05dabc 240
a0d0e21e
LW
241=back
242
68dc0745 243Okay, that's I<definitely> enough hype.
a0d0e21e 244
8e465e4e
JH
245=head1 AVAILABILITY
246
14218588 247Perl is available for most operating systems, including virtually
055fd3a9
GS
248all Unix-like platforms. See L<perlport/"Supported Platforms">
249for a listing.
8bc4a6bb 250
a0d0e21e
LW
251=head1 ENVIRONMENT
252
1e422769 253See L<perlrun>.
a0d0e21e
LW
254
255=head1 AUTHOR
256
19799a22 257Larry Wall <larry@wall.org>, with the help of oodles of other folks.
a0d0e21e 258
a99b1639
TP
259If your Perl success stories and testimonials may be of help to others
260who wish to advocate the use of Perl in their applications,
261or if you wish to simply express your gratitude to Larry and the
19799a22 262Perl developers, please write to perl-thanks@perl.org .
a99b1639 263
a0d0e21e
LW
264=head1 FILES
265
5f05dabc 266 "@INC" locations of perl libraries
a0d0e21e
LW
267
268=head1 SEE ALSO
269
270 a2p awk to perl translator
271 s2p sed to perl translator
272
19799a22 273 http://www.perl.com/ the Perl Home Page
5a3e7812 274 http://www.perl.com/CPAN the Comprehensive Perl Archive
19799a22 275
a0d0e21e
LW
276=head1 DIAGNOSTICS
277
9f1b1f2d
GS
278The C<use warnings> pragma (and the B<-w> switch) produces some
279lovely diagnostics.
a0d0e21e 280
5a964f20
TC
281See L<perldiag> for explanations of all Perl's diagnostics. The C<use
282diagnostics> pragma automatically turns Perl's normally terse warnings
283and errors into these longer forms.
a0d0e21e
LW
284
285Compilation errors will tell you the line number of the error, with an
286indication of the next token or token type that was to be examined.
14218588 287(In a script passed to Perl via B<-e> switches, each
a0d0e21e
LW
288B<-e> is counted as one line.)
289
290Setuid scripts have additional constraints that can produce error
291messages such as "Insecure dependency". See L<perlsec>.
292
293Did we mention that you should definitely consider using the B<-w>
294switch?
295
296=head1 BUGS
297
298The B<-w> switch is not mandatory.
299
300Perl is at the mercy of your machine's definitions of various
1b3f7d21
CS
301operations such as type casting, atof(), and floating-point
302output with sprintf().
a0d0e21e 303
748a9306 304If your stdio requires a seek or eof between reads and writes on a
a0d0e21e
LW
305particular stream, so does Perl. (This doesn't apply to sysread()
306and syswrite().)
307
308While none of the built-in data types have any arbitrary size limits
309(apart from memory size), there are still a few arbitrary limits: a
a30ac152
GS
310given variable name may not be longer than 251 characters. Line numbers
311displayed by diagnostics are internally stored as short integers,
312so they are limited to a maximum of 65535 (higher numbers usually being
313affected by wraparound).
a0d0e21e 314
b0607b7a 315You may mail your bug reports (be sure to include full configuration
19799a22
GS
316information as output by the myconfig program in the perl source
317tree, or by C<perl -V>) to perlbug@perl.com . If you've succeeded
055fd3a9 318in compiling perl, the B<perlbug> script in the F<utils/> subdirectory
19799a22 319can be used to help mail in a bug report.
4633a7c4 320
a0d0e21e
LW
321Perl actually stands for Pathologically Eclectic Rubbish Lister, but
322don't tell anyone I said that.
323
324=head1 NOTES
325
326The Perl motto is "There's more than one way to do it." Divining
327how many more is left as an exercise to the reader.
328
4633a7c4 329The three principal virtues of a programmer are Laziness,
a0d0e21e 330Impatience, and Hubris. See the Camel Book for why.
16d20bd9 331