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