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