This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perlfaq update from Tom Christiansen
[perl5.git] / pod / perl.pod
CommitLineData
a0d0e21e
LW
1=head1 NAME
2
3perl - Practical Extraction and Report Language
4
5=head1 SYNOPSIS
6
94d58c47
PP
7B<perl> S<[ B<-sTuU> ]>
8 S<[ B<-hv> ] [ B<-V>[:I<configvar>] ]>
9 S<[ B<-cw> ] [ B<-d>[:I<debugger>] ] [ B<-D>[I<number/list>] ]>
10 S<[ B<-pna> ] [ B<-F>I<pattern> ] [ B<-l>[I<octal>] ] [ B<-0>[I<octal>] ]>
11 S<[ B<-I>I<dir> ] [ B<-m>[B<->]I<module> ] [ B<-M>[B<->]I<'module...'> ]>
12 S<[ B<-P> ]>
13 S<[ B<-S> ]>
14 S<[ B<-x>[I<dir>] ]>
15 S<[ B<-i>[I<extension>] ]>
16 S<[ B<-e> I<'command'> ] [ B<--> ] [ I<programfile> ] [ I<argument> ]...>
c07a80fd 17
a0d0e21e
LW
18For ease of access, the Perl manual has been split up into a number
19of sections:
20
fb9cefb4
GS
21 perl Perl overview (this section)
22 perldelta Perl changes since previous version
9bc80687
GS
23 perl5005delta Perl changes in version 5.005
24 perl5004delta Perl changes in version 5.004
fb9cefb4
GS
25 perlfaq Perl frequently asked questions
26 perltoc Perl documentation table of contents
760ac839 27
fb9cefb4
GS
28 perldata Perl data structures
29 perlsyn Perl syntax
30 perlop Perl operators and precedence
31 perlre Perl regular expressions
32 perlrun Perl execution and options
33 perlfunc Perl builtin functions
2605996a 34 perlopentut Perl open() tutorial
fb9cefb4
GS
35 perlvar Perl predefined variables
36 perlsub Perl subroutines
37 perlmod Perl modules: how they work
38 perlmodlib Perl modules: how to write and use
39 perlmodinstall Perl modules: how to install from CPAN
40 perlform Perl formats
41 perllocale Perl locale support
760ac839 42
fb9cefb4 43 perlref Perl references
a1e2a320 44 perlreftut Perl references short introduction
fb9cefb4
GS
45 perldsc Perl data structures intro
46 perllol Perl data structures: lists of lists
47 perltoot Perl OO tutorial
48 perlobj Perl objects
49 perltie Perl objects hidden behind simple variables
50 perlbot Perl OO tricks and examples
51 perlipc Perl interprocess communication
2605996a 52 perlthrtut Perl threads tutorial
9fe6733a 53 perldbmfilter Perl DBM Filters
760ac839 54
fb9cefb4
GS
55 perldebug Perl debugging
56 perldiag Perl diagnostic messages
57 perlsec Perl security
58 perltrap Perl traps for the unwary
59 perlport Perl portability guide
60 perlstyle Perl style guide
760ac839 61
fb9cefb4
GS
62 perlpod Perl plain old documentation
63 perlbook Perl book information
760ac839 64
fb9cefb4
GS
65 perlembed Perl ways to embed perl in your C or C++ application
66 perlapio Perl internal IO abstraction interface
67 perlxs Perl XS application programming interface
68 perlxstut Perl XS tutorial
69 perlguts Perl internal functions for those doing extensions
70 perlcall Perl calling conventions from C
a0d0e21e 71
e50bb9a1 72 perltodo Perl things to do
fb9cefb4 73 perlhist Perl history records
d516a115 74
a0d0e21e
LW
75(If you're intending to read these straight through for the first time,
76the suggested order will tend to reduce the number of forward references.)
77
fc952dec
CS
78By default, all of the above manpages are installed in the
79F</usr/local/man/> directory.
80
81Extensive additional documentation for Perl modules is available. The
82default configuration for perl will place this additional documentation
83in the F</usr/local/lib/perl5/man> directory (or else in the F<man>
84subdirectory of the Perl library directory). Some of this additional
85documentation is distributed standard with Perl, but you'll also find
86documentation for third-party modules there.
87
88You should be able to view Perl's documentation with your man(1)
89program by including the proper directories in the appropriate start-up
90files, or in the MANPATH environment variable. To find out where the
91configuration has installed the manpages, type:
16d20bd9 92
760ac839 93 perl -V:man.dir
16d20bd9 94
fc952dec
CS
95If the directories have a common stem, such as F</usr/local/man/man1>
96and F</usr/local/man/man3>, you need only to add that stem
97(F</usr/local/man>) to your man(1) configuration files or your MANPATH
98environment variable. If they do not share a stem, you'll have to add
99both stems.
16d20bd9
AD
100
101If that doesn't work for some reason, you can still use the
4633a7c4
LW
102supplied F<perldoc> script to view module information. You might
103also look into getting a replacement man program.
16d20bd9 104
a0d0e21e
LW
105If something strange has gone wrong with your program and you're not
106sure where you should look for help, try the B<-w> switch first. It
107will often point out exactly where the trouble is.
108
109=head1 DESCRIPTION
110
5f05dabc 111Perl is a language optimized for scanning arbitrary
a0d0e21e
LW
112text files, extracting information from those text files, and printing
113reports based on that information. It's also a good language for many
114system management tasks. The language is intended to be practical
115(easy to use, efficient, complete) rather than beautiful (tiny,
94d58c47
PP
116elegant, minimal).
117
aa689395
PP
118Perl combines (in the author's opinion, anyway) some of the best
119features of C, B<sed>, B<awk>, and B<sh>, so people familiar with
120those languages should have little difficulty with it. (Language
121historians will also note some vestiges of B<csh>, Pascal, and even
122BASIC-PLUS.) Expression syntax corresponds quite closely to C
a0d0e21e
LW
123expression syntax. Unlike most Unix utilities, Perl does not
124arbitrarily limit the size of your data--if you've got the memory,
aa689395 125Perl can slurp in your whole file as a single string. Recursion is of
0f31cffe 126unlimited depth. And the tables used by hashes (sometimes called
aa689395 127"associative arrays") grow as necessary to prevent degraded
0f31cffe 128performance. Perl can use sophisticated pattern matching techniques to
aa689395
PP
129scan large amounts of data very quickly. Although optimized for
130scanning text, Perl can also deal with binary data, and can make dbm
131files look like hashes. Setuid Perl scripts are safer than C programs
132through a dataflow tracing mechanism which prevents many stupid
133security holes.
134
135If you have a problem that would ordinarily use B<sed> or B<awk> or
136B<sh>, but it exceeds their capabilities or must run a little faster,
137and you don't want to write the silly thing in C, then Perl may be for
138you. There are also translators to turn your B<sed> and B<awk>
139scripts into Perl scripts.
a0d0e21e
LW
140
141But wait, there's more...
142
143Perl version 5 is nearly a complete rewrite, and provides
144the following additional benefits:
145
146=over 5
147
148=item * Many usability enhancements
149
150It is now possible to write much more readable Perl code (even within
151regular expressions). Formerly cryptic variable names can be replaced
152by mnemonic identifiers. Error messages are more informative, and the
153optional warnings will catch many of the mistakes a novice might make.
154This cannot be stressed enough. Whenever you get mysterious behavior,
155try the B<-w> switch!!! Whenever you don't get mysterious behavior,
156try using B<-w> anyway.
157
158=item * Simplified grammar
159
160The new yacc grammar is one half the size of the old one. Many of the
161arbitrary grammar rules have been regularized. The number of reserved
162words has been cut by 2/3. Despite this, nearly all old Perl scripts
163will continue to work unchanged.
164
165=item * Lexical scoping
166
167Perl variables may now be declared within a lexical scope, like "auto"
168variables in C. Not only is this more efficient, but it contributes
fc952dec 169to better privacy for "programming in the large". Anonymous
5f05dabc 170subroutines exhibit deep binding of lexical variables (closures).
a0d0e21e
LW
171
172=item * Arbitrarily nested data structures
173
174Any scalar value, including any array element, may now contain a
175reference to any other variable or subroutine. You can easily create
176anonymous variables and subroutines. Perl manages your reference
177counts for you.
178
179=item * Modularity and reusability
180
181The Perl library is now defined in terms of modules which can be easily
182shared among various packages. A package may choose to import all or a
183portion of a module's published interface. Pragmas (that is, compiler
184directives) are defined and used by the same mechanism.
185
186=item * Object-oriented programming
187
188A package can function as a class. Dynamic multiple inheritance and
189virtual methods are supported in a straightforward manner and with very
190little new syntax. Filehandles may now be treated as objects.
191
c07a80fd 192=item * Embeddable and Extensible
a0d0e21e
LW
193
194Perl may now be embedded easily in your C or C++ application, and can
195either call or be called by your routines through a documented
196interface. The XS preprocessor is provided to make it easy to glue
197your C or C++ routines into Perl. Dynamic loading of modules is
5f05dabc 198supported, and Perl itself can be made into a dynamic library.
a0d0e21e
LW
199
200=item * POSIX compliant
201
202A major new module is the POSIX module, which provides access to all
203available POSIX routines and definitions, via object classes where
204appropriate.
205
206=item * Package constructors and destructors
207
208The new BEGIN and END blocks provide means to capture control as
209a package is being compiled, and after the program exits. As a
210degenerate case they work just like awk's BEGIN and END when you
211use the B<-p> or B<-n> switches.
212
213=item * Multiple simultaneous DBM implementations
214
215A Perl program may now access DBM, NDBM, SDBM, GDBM, and Berkeley DB
216files from the same script simultaneously. In fact, the old dbmopen
217interface has been generalized to allow any variable to be tied
218to an object class which defines its access methods.
219
220=item * Subroutine definitions may now be autoloaded
221
222In fact, the AUTOLOAD mechanism also allows you to define any arbitrary
5f05dabc 223semantics for undefined subroutine calls. It's not for just autoloading.
a0d0e21e
LW
224
225=item * Regular expression enhancements
226
fc952dec 227You can now specify nongreedy quantifiers. You can now do grouping
a0d0e21e
LW
228without creating a backreference. You can now write regular expressions
229with embedded whitespace and comments for readability. A consistent
230extensibility mechanism has been added that is upwardly compatible with
231all old regular expressions.
232
5f05dabc
PP
233=item * Innumerable Unbundled Modules
234
f102b883
TC
235The Comprehensive Perl Archive Network described in L<perlmodlib>
236contains hundreds of plug-and-play modules full of reusable code.
237See F<http://www.perl.com/CPAN> for a site near you.
5f05dabc
PP
238
239=item * Compilability
240
241While not yet in full production mode, a working perl-to-C compiler
fc952dec 242does exist. It can generate portable byte code, simple C, or
5f05dabc
PP
243optimized C code.
244
a0d0e21e
LW
245=back
246
68dc0745 247Okay, that's I<definitely> enough hype.
a0d0e21e 248
8e465e4e
JH
249=head1 AVAILABILITY
250
251Perl is available for the vast majority of operating system platforms,
252including most Unix-like platforms. The following situation is as of
253February 1999 and Perl 5.005_03.
254
255The following platforms are able to build Perl from the standard
256source code distribution available at
257F<http://www.perl.com/CPAN/src/index.html>
258
58493fc4
JH
259 AIX Linux SCO ODT/OSR
260 A/UX MachTen Solaris
261 BeOS MPE/iX SunOS
262 BSD/OS NetBSD SVR4
263 DG/UX NextSTEP Tru64 UNIX 3)
264 DomainOS OpenBSD Ultrix
265 DOS DJGPP 1) OpenSTEP UNICOS
266 DYNIX/ptx OS/2 VMS
267 FreeBSD OS390 2) VOS
268 HP-UX PowerMAX Windows 3.1 1)
269 Hurd QNX Windows 95 1) 4)
270 IRIX Windows 98 1) 4)
271 Windows NT 1) 4)
8e465e4e
JH
272
273 1) in DOS mode either the DOS or OS/2 ports can be used
58493fc4
JH
274 2) formerly known as MVS
275 3) formerly known as Digital UNIX and before that DEC OSF/1
276 4) compilers: Borland, Cygwin32, Mingw32 EGCS/GCC, VC++
277
8e465e4e
JH
278The following platforms have been known to build Perl from the source
279but for the Perl release 5.005_03 we haven't been able to verify them,
280either because the hardware/software platforms are rather rare or
2e04d155 281because we don't have an active champion on these platforms, or both.
8e465e4e
JH
282
283 3b1 FPS Plan 9
04251ce8
JH
284 AmigaOS GENIX PowerUX
285 ConvexOS Greenhills RISC/os
286 CX/UX ISC Stellar
287 DC/OSx MachTen 68k SVR2
288 DDE SMES MiNT TI1500
82cda36e
JH
289 DOS EMX MPC TitanOS
290 Dynix NEWS-OS UNICOS/mk
291 EP/IX Opus Unisys Dynix
292 ESIX Unixware
8e465e4e
JH
293
294The following platforms are planned to be supported in the standard
2e04d155 295source code distribution of the Perl release 5.006 but are not
8e465e4e
JH
296supported in the Perl release 5.005_03:
297
298 BS2000
00ad96e1
JH
299 Netware
300 Rhapsody
8e465e4e
JH
301 VM/ESA
302
303The following platforms have their own source code distributions and
304binaries available via F<http://www.perl.com/CPAN/ports/index.html>.
305
306 Perl release
307
308 AS/400 5.003
2e04d155 309 MacOS 5.004
04251ce8 310 Netware 5.003_07
8e465e4e
JH
311 Tandem Guardian 5.004
312
313The following platforms have only binaries available via
314F<http://www.perl.com/CPAN/ports/index.html>.
315
316 Perl release
317
d845c4a6 318 Acorn RISCOS 5.005_02
8e465e4e
JH
319 AOS 5.002
320 LynxOS 5.004_02
8e465e4e 321
a0d0e21e
LW
322=head1 ENVIRONMENT
323
1e422769 324See L<perlrun>.
a0d0e21e
LW
325
326=head1 AUTHOR
327
9607fc9c 328Larry Wall <F<larry@wall.org>>, with the help of oodles of other folks.
a0d0e21e 329
a99b1639
TP
330If your Perl success stories and testimonials may be of help to others
331who wish to advocate the use of Perl in their applications,
332or if you wish to simply express your gratitude to Larry and the
333Perl developers, please write to <F<perl-thanks@perl.org>>.
334
a0d0e21e
LW
335=head1 FILES
336
5f05dabc 337 "@INC" locations of perl libraries
a0d0e21e
LW
338
339=head1 SEE ALSO
340
341 a2p awk to perl translator
4633a7c4 342
a0d0e21e
LW
343 s2p sed to perl translator
344
345=head1 DIAGNOSTICS
346
347The B<-w> switch produces some lovely diagnostics.
348
5a964f20
TC
349See L<perldiag> for explanations of all Perl's diagnostics. The C<use
350diagnostics> pragma automatically turns Perl's normally terse warnings
351and errors into these longer forms.
a0d0e21e
LW
352
353Compilation errors will tell you the line number of the error, with an
354indication of the next token or token type that was to be examined.
355(In the case of a script passed to Perl via B<-e> switches, each
356B<-e> is counted as one line.)
357
358Setuid scripts have additional constraints that can produce error
359messages such as "Insecure dependency". See L<perlsec>.
360
361Did we mention that you should definitely consider using the B<-w>
362switch?
363
364=head1 BUGS
365
366The B<-w> switch is not mandatory.
367
368Perl is at the mercy of your machine's definitions of various
1b3f7d21
CS
369operations such as type casting, atof(), and floating-point
370output with sprintf().
a0d0e21e 371
748a9306 372If your stdio requires a seek or eof between reads and writes on a
a0d0e21e
LW
373particular stream, so does Perl. (This doesn't apply to sysread()
374and syswrite().)
375
376While none of the built-in data types have any arbitrary size limits
377(apart from memory size), there are still a few arbitrary limits: a
a30ac152
GS
378given variable name may not be longer than 251 characters. Line numbers
379displayed by diagnostics are internally stored as short integers,
380so they are limited to a maximum of 65535 (higher numbers usually being
381affected by wraparound).
a0d0e21e 382
b0607b7a
LV
383You may mail your bug reports (be sure to include full configuration
384information as output by the myconfig program in the perl source tree,
9607fc9c 385or by C<perl -V>) to <F<perlbug@perl.com>>.
c07a80fd
PP
386If you've succeeded in compiling perl, the perlbug script in the utils/
387subdirectory can be used to help mail in a bug report.
4633a7c4 388
a0d0e21e
LW
389Perl actually stands for Pathologically Eclectic Rubbish Lister, but
390don't tell anyone I said that.
391
392=head1 NOTES
393
394The Perl motto is "There's more than one way to do it." Divining
395how many more is left as an exercise to the reader.
396
4633a7c4 397The three principal virtues of a programmer are Laziness,
a0d0e21e 398Impatience, and Hubris. See the Camel Book for why.
16d20bd9 399