This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
updates from PodParser v1.12 on CPAN (from Brad Appleton)
[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
37 perlform Perl formats
49877630 38 perlunicode Perl unicode support
fb9cefb4 39 perllocale Perl locale support
760ac839 40
a1e2a320 41 perlreftut Perl references short introduction
19799a22 42 perlref Perl references, the rest of the story
fb9cefb4 43 perldsc Perl data structures intro
19799a22 44 perllol Perl data structures: arrays of arrays
694468e3 45 perlboot Perl OO tutorial for beginners
19799a22
GS
46 perltoot Perl OO tutorial, part 1
47 perltootc Perl OO tutorial, part 2
fb9cefb4
GS
48 perlobj Perl objects
49 perltie Perl objects hidden behind simple variables
50 perlbot Perl OO tricks and examples
51 perlipc Perl interprocess communication
7766f137 52 perlfork Perl fork() information
2605996a 53 perlthrtut Perl threads tutorial
49877630 54 perllexwarn Perl warnings and their control
c93fa817 55 perlfilter Perl source filters
49877630 56 perldbmfilter Perl DBM filters
760ac839 57
54a137f5 58 perlcompile Perl compiler suite intro
fb9cefb4
GS
59 perldebug Perl debugging
60 perldiag Perl diagnostic messages
ac65edd0 61 perlnumber Perl number semantics
fb9cefb4
GS
62 perlsec Perl security
63 perltrap Perl traps for the unwary
64 perlport Perl portability guide
65 perlstyle Perl style guide
760ac839 66
fb9cefb4
GS
67 perlpod Perl plain old documentation
68 perlbook Perl book information
760ac839 69
fb9cefb4
GS
70 perlembed Perl ways to embed perl in your C or C++ application
71 perlapio Perl internal IO abstraction interface
72 perlxs Perl XS application programming interface
73 perlxstut Perl XS tutorial
74 perlguts Perl internal functions for those doing extensions
75 perlcall Perl calling conventions from C
954c1994
GS
76 perlapi Perl API listing (autogenerated)
77 perlintern Perl internal functions (autogenerated)
a0d0e21e 78
e50bb9a1 79 perltodo Perl things to do
e8cd7eae 80 perlhack Perl hackers guide
fb9cefb4 81 perlhist Perl history records
d516a115 82
49877630
GS
83 perlamiga Perl notes for Amiga
84 perlcygwin Perl notes for Cygwin
85 perldos Perl notes for DOS
86 perlhpux Perl notes for HP-UX
87 perlos2 Perl notes for OS/2
88 perlos390 Perl notes for OS/390
89 perlvms Perl notes for VMS
90 perlwin32 Perl notes for Windows
91
a0d0e21e
LW
92(If you're intending to read these straight through for the first time,
93the suggested order will tend to reduce the number of forward references.)
94
19799a22 95By default, the manpages listed above are installed in the
fc952dec
CS
96F</usr/local/man/> directory.
97
98Extensive additional documentation for Perl modules is available. The
99default configuration for perl will place this additional documentation
100in the F</usr/local/lib/perl5/man> directory (or else in the F<man>
101subdirectory of the Perl library directory). Some of this additional
102documentation is distributed standard with Perl, but you'll also find
103documentation for third-party modules there.
104
105You should be able to view Perl's documentation with your man(1)
106program by including the proper directories in the appropriate start-up
107files, or in the MANPATH environment variable. To find out where the
108configuration has installed the manpages, type:
16d20bd9 109
760ac839 110 perl -V:man.dir
16d20bd9 111
fc952dec
CS
112If the directories have a common stem, such as F</usr/local/man/man1>
113and F</usr/local/man/man3>, you need only to add that stem
114(F</usr/local/man>) to your man(1) configuration files or your MANPATH
115environment variable. If they do not share a stem, you'll have to add
116both stems.
16d20bd9
AD
117
118If that doesn't work for some reason, you can still use the
4633a7c4
LW
119supplied F<perldoc> script to view module information. You might
120also look into getting a replacement man program.
16d20bd9 121
a0d0e21e
LW
122If something strange has gone wrong with your program and you're not
123sure where you should look for help, try the B<-w> switch first. It
124will often point out exactly where the trouble is.
125
126=head1 DESCRIPTION
127
5f05dabc 128Perl is a language optimized for scanning arbitrary
a0d0e21e
LW
129text files, extracting information from those text files, and printing
130reports based on that information. It's also a good language for many
131system management tasks. The language is intended to be practical
132(easy to use, efficient, complete) rather than beautiful (tiny,
94d58c47
PP
133elegant, minimal).
134
aa689395
PP
135Perl combines (in the author's opinion, anyway) some of the best
136features of C, B<sed>, B<awk>, and B<sh>, so people familiar with
137those languages should have little difficulty with it. (Language
138historians will also note some vestiges of B<csh>, Pascal, and even
14218588 139BASIC-PLUS.) Expression syntax corresponds closely to C
a0d0e21e
LW
140expression syntax. Unlike most Unix utilities, Perl does not
141arbitrarily limit the size of your data--if you've got the memory,
aa689395 142Perl can slurp in your whole file as a single string. Recursion is of
0f31cffe 143unlimited depth. And the tables used by hashes (sometimes called
aa689395 144"associative arrays") grow as necessary to prevent degraded
0f31cffe 145performance. Perl can use sophisticated pattern matching techniques to
14218588 146scan large amounts of data quickly. Although optimized for
aa689395
PP
147scanning text, Perl can also deal with binary data, and can make dbm
148files look like hashes. Setuid Perl scripts are safer than C programs
14218588 149through a dataflow tracing mechanism that prevents many stupid
aa689395
PP
150security holes.
151
152If you have a problem that would ordinarily use B<sed> or B<awk> or
153B<sh>, but it exceeds their capabilities or must run a little faster,
154and you don't want to write the silly thing in C, then Perl may be for
155you. There are also translators to turn your B<sed> and B<awk>
156scripts into Perl scripts.
a0d0e21e
LW
157
158But wait, there's more...
159
19799a22
GS
160Begun in 1993 (see L<perlhist>), Perl version 5 is nearly a complete
161rewrite that provides the following additional benefits:
a0d0e21e 162
19799a22 163=over
a0d0e21e 164
19799a22 165=item * modularity and reusability using innumerable modules
a0d0e21e 166
19799a22 167Described in L<perlmod>, L<perlmodlib>, and L<perlmodinstall>.
a0d0e21e 168
19799a22 169=item * embeddable and extensible
a0d0e21e 170
19799a22
GS
171Described in L<perlembed>, L<perlxstut>, L<perlxs>, L<perlcall>,
172L<perlguts>, and L<xsubpp>.
a0d0e21e 173
19799a22 174=item * roll-your-own magic variables (including multiple simultaneous DBM implementations)
a0d0e21e 175
19799a22 176Described in L<perltie> and L<AnyDBM_File>.
a0d0e21e 177
19799a22 178=item * subroutines can now be overridden, autoloaded, and prototyped
a0d0e21e 179
19799a22 180Described in L<perlsub>.
a0d0e21e 181
19799a22 182=item * arbitrarily nested data structures and anonymous functions
a0d0e21e 183
19799a22 184Described in L<perlreftut>, L<perlref>, L<perldsc>, and L<perllol>.
a0d0e21e 185
19799a22 186=item * object-oriented programming
a0d0e21e 187
19799a22 188Described in L<perlobj>, L<perltoot>, and L<perlbot>.
a0d0e21e 189
19799a22 190=item * compilability into C code or Perl bytecode
a0d0e21e 191
19799a22 192Described in L<B> and L<B::Bytecode>.
a0d0e21e 193
19799a22 194=item * support for light-weight processes (threads)
a0d0e21e 195
19799a22 196Described in L<perlthrtut> and L<Thread>.
a0d0e21e 197
19799a22 198=item * support for internationalization, localization, and Unicode
a0d0e21e 199
19799a22 200Described in L<perllocale> and L<utf8>.
a0d0e21e 201
19799a22 202=item * lexical scoping
a0d0e21e 203
19799a22 204Described in L<perlsub>.
a0d0e21e 205
19799a22 206=item * regular expression enhancements
a0d0e21e 207
19799a22 208Described in L<perlre>, with additional examples in L<perlop>.
a0d0e21e 209
14218588 210=item * enhanced debugger and interactive Perl environment, with integrated editor support
a0d0e21e 211
19799a22 212Described in L<perldebug>.
a0d0e21e 213
19799a22 214=item * POSIX 1003.1 compliant library
5f05dabc 215
19799a22 216Described in L<POSIX>.
5f05dabc 217
a0d0e21e
LW
218=back
219
68dc0745 220Okay, that's I<definitely> enough hype.
a0d0e21e 221
8e465e4e
JH
222=head1 AVAILABILITY
223
14218588
GS
224Perl is available for most operating systems, including virtually
225all Unix-like platforms.
8e465e4e 226
fb533e5b
JH
227As of early March 2000 (the Perl release 5.6.0), the following
228platforms are able to build Perl from the standard source code
229distribution available at http://www.perl.com/CPAN/src/index.html
230
231 AIX
8bc4a6bb 232 DOS DJGPP 1)
fb533e5b
JH
233 FreeBSD
234 HP-UX
235 IRIX
236 Linux
c22a0cd5 237 LynxOS
fb533e5b
JH
238 MachTen
239 MPE/iX
240 NetBSD
241 OpenBSD
242 OS/2
243 Rhapsody/Darwin 2)
244 Solaris
245 Tru64 UNIX 3)
246 UNICOS
247 UNICOS/mk
248 VMS
249 VOS
250 Windows 3.1 1)
251 Windows 95 1) 4)
252 Windows 98 1) 4)
253 Windows NT 1) 4)
8e465e4e
JH
254
255 1) in DOS mode either the DOS or OS/2 ports can be used
c6018dae 256 2) new in 5.6.0: the BSD/NeXT-based UNIX of Mac OS X
fb533e5b 257 3) formerly known as Digital UNIX and before that DEC OSF/1
873b149f 258 4) compilers: Borland, Cygwin, Mingw32 EGCS/GCC, VC++
c47ff5f1 259
8bc4a6bb 260The following platforms worked for the previous major release
90ea4f4d 261(5.005_03 being the latest maintenance release of that, as of early
8bc4a6bb
JH
262March 2000), but be did not manage to test these in time for the 5.6.0
263release of Perl. There is a very good chance that these will work
264just fine with 5.6.0.
fb533e5b
JH
265
266 A/UX
267 BeOS
268 BSD/OS
269 DG/UX
270 DYNIX/ptx
271 DomainOS
272 Hurd
273 NextSTEP
274 OpenSTEP
275 PowerMAX
276 QNX
277 SCO ODT/OSR
278 SunOS
279 SVR4
280 Ultrix
281
90ea4f4d 282The following platform worked for the previous major release (5.005_03
8bc4a6bb 283being the latest maintenance release of that, as of early March 2000).
c6018dae 284However, standardization on UTF-8 as the internal string representation
8bc4a6bb 285in 5.6.0 has introduced incompatibilities in this EBCDIC platform.
c6018dae 286Support for this platform may be enabled in a future release:
fb533e5b
JH
287
288 OS390 1)
289
290 1) Previously known as MVS, or OpenEdition MVS.
291
292Strongly related to the OS390 platform by also being EBCDIC-based
c6018dae 293mainframe platforms are the following platforms:
fb533e5b
JH
294
295 BS2000
296 VM/ESA
297
c6018dae
GS
298These are also not expected to work under 5.6.0 for the same reasons
299as OS390. Contact the mailing list perl-mvs@perl.org for more details.
fb533e5b 300
c6018dae
GS
301MacOS (Classic, pre-X) is almost 5.6.0-ready; building from the source
302does work with 5.6.0, but additional MacOS specific source code is needed
303for a complete port. Contact the mailing list macperl-porters@macperl.org
fb533e5b
JH
304for more more information.
305
306The following platforms have been known to build Perl from source in
307the past, but we haven't been able to verify their status for the
308current release, either because the hardware/software platforms are
309rare or because we don't have an active champion on these
c6018dae 310platforms--or both:
fb533e5b
JH
311
312 3b1
313 AmigaOS
314 ConvexOS
315 CX/UX
316 DC/OSx
317 DDE SMES
318 DOS EMX
319 Dynix
320 EP/IX
321 ESIX
322 FPS
323 GENIX
324 Greenhills
325 ISC
326 MachTen 68k
327 MiNT
328 MPC
329 NEWS-OS
330 Opus
331 Plan 9
332 PowerUX
333 RISC/os
334 Stellar
335 SVR2
336 TI1500
337 TitanOS
338 Unisys Dynix
339 Unixware
340
c6018dae 341Support for the following platform is planned for a future Perl release:
fb533e5b 342
00ad96e1 343 Netware
8e465e4e
JH
344
345The following platforms have their own source code distributions and
8bc4a6bb 346binaries available via http://www.perl.com/CPAN/ports/index.html:
8e465e4e
JH
347
348 Perl release
349
350 AS/400 5.003
04251ce8 351 Netware 5.003_07
8e465e4e
JH
352 Tandem Guardian 5.004
353
354The following platforms have only binaries available via
8bc4a6bb 355http://www.perl.com/CPAN/ports/index.html:
8e465e4e
JH
356
357 Perl release
358
d845c4a6 359 Acorn RISCOS 5.005_02
8e465e4e
JH
360 AOS 5.002
361 LynxOS 5.004_02
8e465e4e 362
5de137a0
JH
363Although we do suggest that you always build your own Perl from
364the source code, both for maximal configurability and for security,
365in case you are in a hurry you can check
366http://www.perl.com/CPAN/ports/index.html for binary distributions.
8bc4a6bb 367
a0d0e21e
LW
368=head1 ENVIRONMENT
369
1e422769 370See L<perlrun>.
a0d0e21e
LW
371
372=head1 AUTHOR
373
19799a22 374Larry Wall <larry@wall.org>, with the help of oodles of other folks.
a0d0e21e 375
a99b1639
TP
376If your Perl success stories and testimonials may be of help to others
377who wish to advocate the use of Perl in their applications,
378or if you wish to simply express your gratitude to Larry and the
19799a22 379Perl developers, please write to perl-thanks@perl.org .
a99b1639 380
a0d0e21e
LW
381=head1 FILES
382
5f05dabc 383 "@INC" locations of perl libraries
a0d0e21e
LW
384
385=head1 SEE ALSO
386
387 a2p awk to perl translator
388 s2p sed to perl translator
389
19799a22 390 http://www.perl.com/ the Perl Home Page
5a3e7812 391 http://www.perl.com/CPAN the Comprehensive Perl Archive
19799a22 392
a0d0e21e
LW
393=head1 DIAGNOSTICS
394
395The B<-w> switch produces some lovely diagnostics.
396
5a964f20
TC
397See L<perldiag> for explanations of all Perl's diagnostics. The C<use
398diagnostics> pragma automatically turns Perl's normally terse warnings
399and errors into these longer forms.
a0d0e21e
LW
400
401Compilation errors will tell you the line number of the error, with an
402indication of the next token or token type that was to be examined.
14218588 403(In a script passed to Perl via B<-e> switches, each
a0d0e21e
LW
404B<-e> is counted as one line.)
405
406Setuid scripts have additional constraints that can produce error
407messages such as "Insecure dependency". See L<perlsec>.
408
409Did we mention that you should definitely consider using the B<-w>
410switch?
411
412=head1 BUGS
413
414The B<-w> switch is not mandatory.
415
416Perl is at the mercy of your machine's definitions of various
1b3f7d21
CS
417operations such as type casting, atof(), and floating-point
418output with sprintf().
a0d0e21e 419
748a9306 420If your stdio requires a seek or eof between reads and writes on a
a0d0e21e
LW
421particular stream, so does Perl. (This doesn't apply to sysread()
422and syswrite().)
423
424While none of the built-in data types have any arbitrary size limits
425(apart from memory size), there are still a few arbitrary limits: a
a30ac152
GS
426given variable name may not be longer than 251 characters. Line numbers
427displayed by diagnostics are internally stored as short integers,
428so they are limited to a maximum of 65535 (higher numbers usually being
429affected by wraparound).
a0d0e21e 430
b0607b7a 431You may mail your bug reports (be sure to include full configuration
19799a22
GS
432information as output by the myconfig program in the perl source
433tree, or by C<perl -V>) to perlbug@perl.com . If you've succeeded
434in compiling perl, the perlbug script in the utils/ subdirectory
435can be used to help mail in a bug report.
4633a7c4 436
a0d0e21e
LW
437Perl actually stands for Pathologically Eclectic Rubbish Lister, but
438don't tell anyone I said that.
439
440=head1 NOTES
441
442The Perl motto is "There's more than one way to do it." Divining
443how many more is left as an exercise to the reader.
444
4633a7c4 445The three principal virtues of a programmer are Laziness,
a0d0e21e 446Impatience, and Hubris. See the Camel Book for why.
16d20bd9 447