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