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