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