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