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