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