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