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