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