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