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