This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
This is my patch patch.1n for perl5.001.
[perl5.git] / pod / perl.pod
CommitLineData
a0d0e21e
LW
1=head1 NAME
2
3perl - Practical Extraction and Report Language
4
5=head1 SYNOPSIS
6
7For ease of access, the Perl manual has been split up into a number
8of sections:
9
10 perl Perl overview (this section)
11 perldata Perl data structures
12 perlsyn Perl syntax
13 perlop Perl operators and precedence
14 perlre Perl regular expressions
15 perlrun Perl execution and options
16 perlfunc Perl builtin functions
17 perlvar Perl predefined variables
18 perlsub Perl subroutines
19 perlmod Perl modules
20 perlref Perl references and nested data structures
21 perlobj Perl objects
22 perlbot Perl OO tricks and examples
23 perldebug Perl debugging
24 perldiag Perl diagnostic messages
25 perlform Perl formats
26 perlipc Perl interprocess communication
27 perlsec Perl security
28 perltrap Perl traps for the unwary
29 perlstyle Perl style guide
8e07c86e 30 perlxs Perl XS application programming interface
a0d0e21e
LW
31 perlguts Perl internal functions for those doing extensions
32 perlcall Perl calling conventions from C
33 perlovl Perl overloading semantics
e50aee73
AD
34 perlembed Perl how to embed perl in your C or C++ app
35 perlpod Perl plain old documentation
a0d0e21e
LW
36 perlbook Perl book information
37
38(If you're intending to read these straight through for the first time,
39the suggested order will tend to reduce the number of forward references.)
40
16d20bd9
AD
41Additional documentation for perl modules is available in
42the F</usr/local/lib/perl5/man/man3> directory. You can view this
43with a man(1) program by including the following in the
44appropriate start-up files. (You may have to adjust the path to
45match $Config{'man3dir'}.)
46
47 .profile (for sh, bash or ksh users):
48 MANPATH=$MANPATH:/usr/local/lib/perl5/man
49 export MANPATH
50
51 .login (for csh or tcsh users):
52 setenv MANPATH $MANPATH:/usr/local/lib/perl5/man
53
54If that doesn't work for some reason, you can still use the
55supplied perldoc script to view module information.
56
a0d0e21e
LW
57If something strange has gone wrong with your program and you're not
58sure where you should look for help, try the B<-w> switch first. It
59will often point out exactly where the trouble is.
60
61=head1 DESCRIPTION
62
63Perl is an interpreted language optimized for scanning arbitrary
64text files, extracting information from those text files, and printing
65reports based on that information. It's also a good language for many
66system management tasks. The language is intended to be practical
67(easy to use, efficient, complete) rather than beautiful (tiny,
68elegant, minimal). It combines (in the author's opinion, anyway) some
69of the best features of C, B<sed>, B<awk>, and B<sh>, so people
70familiar with those languages should have little difficulty with it.
71(Language historians will also note some vestiges of B<csh>, Pascal,
72and even BASIC-PLUS.) Expression syntax corresponds quite closely to C
73expression syntax. Unlike most Unix utilities, Perl does not
74arbitrarily limit the size of your data--if you've got the memory,
75Perl can slurp in your whole file as a single string. Recursion is
76of unlimited depth. And the hash tables used by associative arrays
77grow as necessary to prevent degraded performance. Perl uses
78sophisticated pattern matching techniques to scan large amounts of data
79very quickly. Although optimized for scanning text, Perl can also
80deal with binary data, and can make dbm files look like associative
81arrays (where dbm is available). Setuid Perl scripts are safer than
82C programs through a dataflow tracing mechanism which prevents many
83stupid security holes. If you have a problem that would ordinarily use
84B<sed> or B<awk> or B<sh>, but it exceeds their capabilities or must
85run a little faster, and you don't want to write the silly thing in C,
86then Perl may be for you. There are also translators to turn your
87B<sed> and B<awk> scripts into Perl scripts.
88
89But wait, there's more...
90
91Perl version 5 is nearly a complete rewrite, and provides
92the following additional benefits:
93
94=over 5
95
96=item * Many usability enhancements
97
98It is now possible to write much more readable Perl code (even within
99regular expressions). Formerly cryptic variable names can be replaced
100by mnemonic identifiers. Error messages are more informative, and the
101optional warnings will catch many of the mistakes a novice might make.
102This cannot be stressed enough. Whenever you get mysterious behavior,
103try the B<-w> switch!!! Whenever you don't get mysterious behavior,
104try using B<-w> anyway.
105
106=item * Simplified grammar
107
108The new yacc grammar is one half the size of the old one. Many of the
109arbitrary grammar rules have been regularized. The number of reserved
110words has been cut by 2/3. Despite this, nearly all old Perl scripts
111will continue to work unchanged.
112
113=item * Lexical scoping
114
115Perl variables may now be declared within a lexical scope, like "auto"
116variables in C. Not only is this more efficient, but it contributes
117to better privacy for "programming in the large".
118
119=item * Arbitrarily nested data structures
120
121Any scalar value, including any array element, may now contain a
122reference to any other variable or subroutine. You can easily create
123anonymous variables and subroutines. Perl manages your reference
124counts for you.
125
126=item * Modularity and reusability
127
128The Perl library is now defined in terms of modules which can be easily
129shared among various packages. A package may choose to import all or a
130portion of a module's published interface. Pragmas (that is, compiler
131directives) are defined and used by the same mechanism.
132
133=item * Object-oriented programming
134
135A package can function as a class. Dynamic multiple inheritance and
136virtual methods are supported in a straightforward manner and with very
137little new syntax. Filehandles may now be treated as objects.
138
139=item * Embeddible and Extensible
140
141Perl may now be embedded easily in your C or C++ application, and can
142either call or be called by your routines through a documented
143interface. The XS preprocessor is provided to make it easy to glue
144your C or C++ routines into Perl. Dynamic loading of modules is
145supported.
146
147=item * POSIX compliant
148
149A major new module is the POSIX module, which provides access to all
150available POSIX routines and definitions, via object classes where
151appropriate.
152
153=item * Package constructors and destructors
154
155The new BEGIN and END blocks provide means to capture control as
156a package is being compiled, and after the program exits. As a
157degenerate case they work just like awk's BEGIN and END when you
158use the B<-p> or B<-n> switches.
159
160=item * Multiple simultaneous DBM implementations
161
162A Perl program may now access DBM, NDBM, SDBM, GDBM, and Berkeley DB
163files from the same script simultaneously. In fact, the old dbmopen
164interface has been generalized to allow any variable to be tied
165to an object class which defines its access methods.
166
167=item * Subroutine definitions may now be autoloaded
168
169In fact, the AUTOLOAD mechanism also allows you to define any arbitrary
170semantics for undefined subroutine calls. It's not just for autoloading.
171
172=item * Regular expression enhancements
173
174You can now specify non-greedy quantifiers. You can now do grouping
175without creating a backreference. You can now write regular expressions
176with embedded whitespace and comments for readability. A consistent
177extensibility mechanism has been added that is upwardly compatible with
178all old regular expressions.
179
180=back
181
182Ok, that's I<definitely> enough hype.
183
184=head1 ENVIRONMENT
185
186=over 12
187
188=item HOME
189
190Used if chdir has no argument.
191
192=item LOGDIR
193
194Used if chdir has no argument and HOME is not set.
195
196=item PATH
197
198Used in executing subprocesses, and in finding the script if B<-S> is
199used.
200
201=item PERL5LIB
202
203A colon-separated list of directories in which to look for Perl library
204files before looking in the standard library and the current
205directory. If PERL5LIB is not defined, PERLLIB is used.
206
207=item PERL5DB
208
209The command used to get the debugger code. If unset, uses
210
211 BEGIN { require 'perl5db.pl' }
212
213=item PERLLIB
214
215A colon-separated list of directories in which to look for Perl library
216files before looking in the standard library and the current
217directory. If PERL5LIB is defined, PERLLIB is not used.
218
219
220=back
221
222Apart from these, Perl uses no other environment variables, except
223to make them available to the script being executed, and to child
224processes. However, scripts running setuid would do well to execute
225the following lines before doing anything else, just to keep people
226honest:
227
228 $ENV{'PATH'} = '/bin:/usr/bin'; # or whatever you need
229 $ENV{'SHELL'} = '/bin/sh' if defined $ENV{'SHELL'};
230 $ENV{'IFS'} = '' if defined $ENV{'IFS'};
231
232=head1 AUTHOR
233
234Larry Wall <F<lwall@netlabs.com.>, with the help of oodles of other folks.
235
236=head1 FILES
237
238 "/tmp/perl-e$$" temporary file for -e commands
239 "@INC" locations of perl 5 libraries
240
241=head1 SEE ALSO
242
243 a2p awk to perl translator
244 s2p sed to perl translator
245
246=head1 DIAGNOSTICS
247
248The B<-w> switch produces some lovely diagnostics.
249
250See L<perldiag> for explanations of all Perl's diagnostics.
251
252Compilation errors will tell you the line number of the error, with an
253indication of the next token or token type that was to be examined.
254(In the case of a script passed to Perl via B<-e> switches, each
255B<-e> is counted as one line.)
256
257Setuid scripts have additional constraints that can produce error
258messages such as "Insecure dependency". See L<perlsec>.
259
260Did we mention that you should definitely consider using the B<-w>
261switch?
262
263=head1 BUGS
264
265The B<-w> switch is not mandatory.
266
267Perl is at the mercy of your machine's definitions of various
268operations such as type casting, atof() and sprintf().
269
748a9306 270If your stdio requires a seek or eof between reads and writes on a
a0d0e21e
LW
271particular stream, so does Perl. (This doesn't apply to sysread()
272and syswrite().)
273
274While none of the built-in data types have any arbitrary size limits
275(apart from memory size), there are still a few arbitrary limits: a
276given identifier may not be longer than 255 characters, and no
277component of your PATH may be longer than 255 if you use B<-S>. A regular
278expression may not compile to more than 32767 bytes internally.
279
280Perl actually stands for Pathologically Eclectic Rubbish Lister, but
281don't tell anyone I said that.
282
283=head1 NOTES
284
285The Perl motto is "There's more than one way to do it." Divining
286how many more is left as an exercise to the reader.
287
288The three principle virtues of a programmer are Laziness,
289Impatience, and Hubris. See the Camel Book for why.
16d20bd9 290