This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Update to perl.pod suggested
[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
21 perl Perl overview (this section)
774d564b 22 perldelta Perl changes since previous version
760ac839 23
a0d0e21e
LW
24 perldata Perl data structures
25 perlsyn Perl syntax
26 perlop Perl operators and precedence
27 perlre Perl regular expressions
28 perlrun Perl execution and options
29 perlfunc Perl builtin functions
30 perlvar Perl predefined variables
31 perlsub Perl subroutines
32 perlmod Perl modules
760ac839 33 perlform Perl formats
5f05dabc 34 perllocale Perl locale support
760ac839 35
4633a7c4
LW
36 perlref Perl references
37 perldsc Perl data structures intro
38 perllol Perl data structures: lists of lists
5f05dabc 39 perltoot Perl OO tutorial
a0d0e21e 40 perlobj Perl objects
cb1a09d0 41 perltie Perl objects hidden behind simple variables
a0d0e21e 42 perlbot Perl OO tricks and examples
760ac839
LW
43 perlipc Perl interprocess communication
44
a0d0e21e
LW
45 perldebug Perl debugging
46 perldiag Perl diagnostic messages
a0d0e21e
LW
47 perlsec Perl security
48 perltrap Perl traps for the unwary
49 perlstyle Perl style guide
760ac839
LW
50
51 perlpod Perl plain old documentation
52 perlbook Perl book information
53
54 perlembed Perl how to embed perl in your C or C++ app
55 perlapio Perl internal IO abstraction interface
8e07c86e 56 perlxs Perl XS application programming interface
4633a7c4 57 perlxstut Perl XS tutorial
a0d0e21e
LW
58 perlguts Perl internal functions for those doing extensions
59 perlcall Perl calling conventions from C
a0d0e21e
LW
60
61(If you're intending to read these straight through for the first time,
62the suggested order will tend to reduce the number of forward references.)
63
4633a7c4
LW
64Additional documentation for Perl modules is available in the
65F</usr/local/man/> directory. Some of this is distributed standard with
66Perl, but you'll also find third-party modules there. You should be able
67to view this with your man(1) program by including the proper directories
68in the appropriate start-up files. To find out where these are, type:
16d20bd9 69
760ac839 70 perl -V:man.dir
16d20bd9 71
4633a7c4 72If the directories were F</usr/local/man/man1> and F</usr/local/man/man3>,
5f05dabc 73you would need to add only F</usr/local/man> to your MANPATH. If
4633a7c4 74they are different, you'll have to add both stems.
16d20bd9
AD
75
76If that doesn't work for some reason, you can still use the
4633a7c4
LW
77supplied F<perldoc> script to view module information. You might
78also look into getting a replacement man program.
16d20bd9 79
a0d0e21e
LW
80If something strange has gone wrong with your program and you're not
81sure where you should look for help, try the B<-w> switch first. It
82will often point out exactly where the trouble is.
83
84=head1 DESCRIPTION
85
5f05dabc 86Perl is a language optimized for scanning arbitrary
a0d0e21e
LW
87text files, extracting information from those text files, and printing
88reports based on that information. It's also a good language for many
89system management tasks. The language is intended to be practical
90(easy to use, efficient, complete) rather than beautiful (tiny,
94d58c47
PP
91elegant, minimal).
92
93Perl combines (in the author's opinion, anyway) some
a0d0e21e
LW
94of the best features of C, B<sed>, B<awk>, and B<sh>, so people
95familiar with those languages should have little difficulty with it.
96(Language historians will also note some vestiges of B<csh>, Pascal,
97and even BASIC-PLUS.) Expression syntax corresponds quite closely to C
98expression syntax. Unlike most Unix utilities, Perl does not
99arbitrarily limit the size of your data--if you've got the memory,
100Perl can slurp in your whole file as a single string. Recursion is
101of unlimited depth. And the hash tables used by associative arrays
102grow as necessary to prevent degraded performance. Perl uses
103sophisticated pattern matching techniques to scan large amounts of data
104very quickly. Although optimized for scanning text, Perl can also
105deal with binary data, and can make dbm files look like associative
c07a80fd 106arrays. Setuid Perl scripts are safer than
a0d0e21e
LW
107C programs through a dataflow tracing mechanism which prevents many
108stupid security holes. If you have a problem that would ordinarily use
109B<sed> or B<awk> or B<sh>, but it exceeds their capabilities or must
110run a little faster, and you don't want to write the silly thing in C,
111then Perl may be for you. There are also translators to turn your
112B<sed> and B<awk> scripts into Perl scripts.
113
114But wait, there's more...
115
116Perl version 5 is nearly a complete rewrite, and provides
117the following additional benefits:
118
119=over 5
120
121=item * Many usability enhancements
122
123It is now possible to write much more readable Perl code (even within
124regular expressions). Formerly cryptic variable names can be replaced
125by mnemonic identifiers. Error messages are more informative, and the
126optional warnings will catch many of the mistakes a novice might make.
127This cannot be stressed enough. Whenever you get mysterious behavior,
128try the B<-w> switch!!! Whenever you don't get mysterious behavior,
129try using B<-w> anyway.
130
131=item * Simplified grammar
132
133The new yacc grammar is one half the size of the old one. Many of the
134arbitrary grammar rules have been regularized. The number of reserved
135words has been cut by 2/3. Despite this, nearly all old Perl scripts
136will continue to work unchanged.
137
138=item * Lexical scoping
139
140Perl variables may now be declared within a lexical scope, like "auto"
141variables in C. Not only is this more efficient, but it contributes
5f05dabc
PP
142to better privacy for "programming in the large". Anonymous
143subroutines exhibit deep binding of lexical variables (closures).
a0d0e21e
LW
144
145=item * Arbitrarily nested data structures
146
147Any scalar value, including any array element, may now contain a
148reference to any other variable or subroutine. You can easily create
149anonymous variables and subroutines. Perl manages your reference
150counts for you.
151
152=item * Modularity and reusability
153
154The Perl library is now defined in terms of modules which can be easily
155shared among various packages. A package may choose to import all or a
156portion of a module's published interface. Pragmas (that is, compiler
157directives) are defined and used by the same mechanism.
158
159=item * Object-oriented programming
160
161A package can function as a class. Dynamic multiple inheritance and
162virtual methods are supported in a straightforward manner and with very
163little new syntax. Filehandles may now be treated as objects.
164
c07a80fd 165=item * Embeddable and Extensible
a0d0e21e
LW
166
167Perl may now be embedded easily in your C or C++ application, and can
168either call or be called by your routines through a documented
169interface. The XS preprocessor is provided to make it easy to glue
170your C or C++ routines into Perl. Dynamic loading of modules is
5f05dabc 171supported, and Perl itself can be made into a dynamic library.
a0d0e21e
LW
172
173=item * POSIX compliant
174
175A major new module is the POSIX module, which provides access to all
176available POSIX routines and definitions, via object classes where
177appropriate.
178
179=item * Package constructors and destructors
180
181The new BEGIN and END blocks provide means to capture control as
182a package is being compiled, and after the program exits. As a
183degenerate case they work just like awk's BEGIN and END when you
184use the B<-p> or B<-n> switches.
185
186=item * Multiple simultaneous DBM implementations
187
188A Perl program may now access DBM, NDBM, SDBM, GDBM, and Berkeley DB
189files from the same script simultaneously. In fact, the old dbmopen
190interface has been generalized to allow any variable to be tied
191to an object class which defines its access methods.
192
193=item * Subroutine definitions may now be autoloaded
194
195In fact, the AUTOLOAD mechanism also allows you to define any arbitrary
5f05dabc 196semantics for undefined subroutine calls. It's not for just autoloading.
a0d0e21e
LW
197
198=item * Regular expression enhancements
199
200You can now specify non-greedy quantifiers. You can now do grouping
201without creating a backreference. You can now write regular expressions
202with embedded whitespace and comments for readability. A consistent
203extensibility mechanism has been added that is upwardly compatible with
204all old regular expressions.
205
5f05dabc
PP
206=item * Innumerable Unbundled Modules
207
208The Comprehensive Perl Archive Network described in L<perlmod>
209contains hundreds of plug-and-play modules full of reusable
210code. See F<http://www.perl.com/CPAN> for a site near you.
211
212=item * Compilability
213
214While not yet in full production mode, a working perl-to-C compiler
215does exist. It can generate portable bytecode, simple C, or
216optimized C code.
217
a0d0e21e
LW
218=back
219
220Ok, that's I<definitely> enough hype.
221
222=head1 ENVIRONMENT
223
224=over 12
225
226=item HOME
227
228Used if chdir has no argument.
229
230=item LOGDIR
231
232Used if chdir has no argument and HOME is not set.
233
234=item PATH
235
236Used in executing subprocesses, and in finding the script if B<-S> is
237used.
238
239=item PERL5LIB
240
241A colon-separated list of directories in which to look for Perl library
242files before looking in the standard library and the current
4633a7c4
LW
243directory. If PERL5LIB is not defined, PERLLIB is used. When running
244taint checks (because the script was running setuid or setgid, or the
245B<-T> switch was used), neither variable is used. The script should
246instead say
247
248 use lib "/my/directory";
a0d0e21e
LW
249
250=item PERL5DB
251
252The command used to get the debugger code. If unset, uses
253
254 BEGIN { require 'perl5db.pl' }
255
5f05dabc
PP
256=item PERL_DESTRUCT_LEVEL
257
258Relevant only if your perl executable was built with B<-DDEBUGGING>,
259this controls the behavior of global destruction of objects and other
260references.
261
a0d0e21e
LW
262=item PERLLIB
263
264A colon-separated list of directories in which to look for Perl library
265files before looking in the standard library and the current
266directory. If PERL5LIB is defined, PERLLIB is not used.
267
a0d0e21e
LW
268=back
269
a034a98d
DD
270Perl also has environment variables that control how Perl handles data
271specific to particular natural languages. See L<perllocale>.
fb252e81 272
a0d0e21e
LW
273Apart from these, Perl uses no other environment variables, except
274to make them available to the script being executed, and to child
275processes. However, scripts running setuid would do well to execute
276the following lines before doing anything else, just to keep people
277honest:
278
279 $ENV{'PATH'} = '/bin:/usr/bin'; # or whatever you need
280 $ENV{'SHELL'} = '/bin/sh' if defined $ENV{'SHELL'};
281 $ENV{'IFS'} = '' if defined $ENV{'IFS'};
282
283=head1 AUTHOR
284
fb252e81 285Larry Wall E<lt>F<larry@wall.org>E<gt>, with the help of oodles of other folks.
a0d0e21e
LW
286
287=head1 FILES
288
289 "/tmp/perl-e$$" temporary file for -e commands
5f05dabc 290 "@INC" locations of perl libraries
a0d0e21e
LW
291
292=head1 SEE ALSO
293
294 a2p awk to perl translator
4633a7c4 295
a0d0e21e
LW
296 s2p sed to perl translator
297
298=head1 DIAGNOSTICS
299
300The B<-w> switch produces some lovely diagnostics.
301
302See L<perldiag> for explanations of all Perl's diagnostics.
303
304Compilation errors will tell you the line number of the error, with an
305indication of the next token or token type that was to be examined.
306(In the case of a script passed to Perl via B<-e> switches, each
307B<-e> is counted as one line.)
308
309Setuid scripts have additional constraints that can produce error
310messages such as "Insecure dependency". See L<perlsec>.
311
312Did we mention that you should definitely consider using the B<-w>
313switch?
314
315=head1 BUGS
316
317The B<-w> switch is not mandatory.
318
319Perl is at the mercy of your machine's definitions of various
5f05dabc
PP
320operations such as type casting, atof(), and sprintf(). The latter
321can even trigger a core dump when passed ludicrous input values.
a0d0e21e 322
748a9306 323If your stdio requires a seek or eof between reads and writes on a
a0d0e21e
LW
324particular stream, so does Perl. (This doesn't apply to sysread()
325and syswrite().)
326
327While none of the built-in data types have any arbitrary size limits
328(apart from memory size), there are still a few arbitrary limits: a
d357d931 329given variable name may not be longer than 255 characters, and no
a0d0e21e
LW
330component of your PATH may be longer than 255 if you use B<-S>. A regular
331expression may not compile to more than 32767 bytes internally.
332
b0607b7a
LV
333You may mail your bug reports (be sure to include full configuration
334information as output by the myconfig program in the perl source tree,
335or by C<perl -V>) to F<perlbug@perl.com>.
c07a80fd
PP
336If you've succeeded in compiling perl, the perlbug script in the utils/
337subdirectory can be used to help mail in a bug report.
4633a7c4 338
a0d0e21e
LW
339Perl actually stands for Pathologically Eclectic Rubbish Lister, but
340don't tell anyone I said that.
341
342=head1 NOTES
343
344The Perl motto is "There's more than one way to do it." Divining
345how many more is left as an exercise to the reader.
346
4633a7c4 347The three principal virtues of a programmer are Laziness,
a0d0e21e 348Impatience, and Hubris. See the Camel Book for why.
16d20bd9 349