extra code in pp_concat, Take 2
[p5sagit/p5-mst-13.2.git] / pod / perl.pod
CommitLineData
a0d0e21e 1=head1 NAME
2
3perl - Practical Extraction and Report Language
4
5=head1 SYNOPSIS
6
19799a22 7B<perl> S<[ B<-sTuU> ]> S<[ B<-hv> ] [ B<-V>[:I<configvar>] ]>
8 S<[ B<-cw> ] [ B<-d>[:I<debugger>] ] [ B<-D>[I<number/list>] ]>
9 S<[ B<-pna> ] [ B<-F>I<pattern> ] [ B<-l>[I<octal>] ] [ B<-0>[I<octal>] ]>
10 S<[ B<-I>I<dir> ] [ B<-m>[B<->]I<module> ] [ B<-M>[B<->]I<'module...'> ]>
11 S<[ B<-P> ]> S<[ B<-S> ]> S<[ B<-x>[I<dir>] ]>
12 S<[ B<-i>[I<extension>] ]> S<[ B<-e> I<'command'> ]
13 [ B<--> ] [ I<programfile> ] [ I<argument> ]...>
c07a80fd 14
10151d09 15If you're new to Perl, you should start with L<perlintro>, which is a
16general intro for beginners and provides some background to help you
17navigate the rest of Perl's extensive documentation.
18
19For ease of access, the Perl manual has been split up into several sections.
a0d0e21e 20
fd7b6849 21=head2 Overview
22
fb9cefb4 23 perl Perl overview (this section)
10151d09 24 perlintro Perl introduction for beginners
fb9cefb4 25 perltoc Perl documentation table of contents
760ac839 26
fd7b6849 27=head2 Tutorials
28
7a2320f0 29 perlreftut Perl references short introduction
30 perldsc Perl data structures intro
31 perllol Perl data structures: arrays of arrays
7a2320f0 32
41630250 33 perlrequick Perl regular expressions quick start
7a2320f0 34 perlretut Perl regular expressions tutorial
35
36 perlboot Perl OO tutorial for beginners
37 perltoot Perl OO tutorial, part 1
38 perltooc Perl OO tutorial, part 2
39 perlbot Perl OO tricks and examples
40
41 perlstyle Perl style guide
42
41630250 43 perlcheat Perl cheat sheet
7a2320f0 44 perltrap Perl traps for the unwary
45 perldebtut Perl debugging tutorial
46
fd7b6849 47 perlfaq Perl frequently asked questions
48 perlfaq1 General Questions About Perl
49 perlfaq2 Obtaining and Learning about Perl
50 perlfaq3 Programming Tools
51 perlfaq4 Data Manipulation
52 perlfaq5 Files and Formats
53 perlfaq6 Regexes
54 perlfaq7 Perl Language Issues
55 perlfaq8 System Interaction
56 perlfaq9 Networking
0f542199 57
fd7b6849 58=head2 Reference Manual
413510b3 59
fb9cefb4 60 perlsyn Perl syntax
4755096e 61 perldata Perl data structures
fb9cefb4 62 perlop Perl operators and precedence
c2e66d9e 63 perlsub Perl subroutines
fd7b6849 64 perlfunc Perl built-in functions
413510b3 65 perlopentut Perl open() tutorial
41630250 66 perlpacktut Perl pack() and unpack() tutorial
c2e66d9e 67 perlpod Perl plain old documentation
41630250 68 perlpodspec Perl plain old documentation format specification
c2e66d9e 69 perlrun Perl execution and options
70 perldiag Perl diagnostic messages
41630250 71 perllexwarn Perl warnings and their control
4755096e 72 perldebug Perl debugging
fb9cefb4 73 perlvar Perl predefined variables
4755096e 74 perlre Perl regular expressions, the rest of the story
30487ceb 75 perlreref Perl regular expressions quick reference
d396a558 76 perlref Perl references, the rest of the story
fb9cefb4 77 perlform Perl formats
d396a558 78 perlobj Perl objects
d396a558 79 perltie Perl objects hidden behind simple variables
fd7b6849 80 perldbmfilter Perl DBM filters
760ac839 81
c2e66d9e 82 perlipc Perl interprocess communication
83 perlfork Perl fork() information
84 perlnumber Perl number semantics
53d7eaa8 85
c2e66d9e 86 perlthrtut Perl threads tutorial
41630250 87 perlothrtut Old Perl threads tutorial
c2e66d9e 88
89 perlport Perl portability guide
d396a558 90 perllocale Perl locale support
07fcf8ff 91 perluniintro Perl Unicode introduction
41630250 92 perlunicode Perl Unicode support
d396a558 93 perlebcdic Considerations for running Perl on EBCDIC platforms
c2e66d9e 94
d396a558 95 perlsec Perl security
4755096e 96
c2e66d9e 97 perlmod Perl modules: how they work
35bf961c 98 perlmodlib Perl modules: how to write and use
99 perlmodstyle Perl modules: how to write modules with style
fd7b6849 100 perlmodinstall Perl modules: how to install from CPAN
c2e66d9e 101 perlnewmod Perl modules: preparing a new module for distribution
760ac839 102
fd7b6849 103 perlutil utilities packaged with the Perl distribution
760ac839 104
41630250 105 perlcompile Perl compiler suite intro
760ac839 106
fd7b6849 107 perlfilter Perl source filters
108
109=head2 Internals and C Language Interface
110
fb9cefb4 111 perlembed Perl ways to embed perl in your C or C++ application
41630250 112 perldebguts Perl debugging guts and tips
fb9cefb4 113 perlxstut Perl XS tutorial
4755096e 114 perlxs Perl XS application programming interface
f40a6c71 115 perlclib Internal replacements for standard C library functions
fb9cefb4 116 perlguts Perl internal functions for those doing extensions
117 perlcall Perl calling conventions from C
fd7b6849 118
954c1994 119 perlapi Perl API listing (autogenerated)
120 perlintern Perl internal functions (autogenerated)
dc5c060f 121 perliol C API for Perl's implementation of IO in Layers
4755096e 122 perlapio Perl internal IO abstraction interface
fd7b6849 123
e8cd7eae 124 perlhack Perl hackers guide
4755096e 125
fd7b6849 126=head2 Miscellaneous
127
128 perlbook Perl book information
fd7b6849 129 perltodo Perl things to do
130
2a551100 131 perldoc Look up Perl documentation in Pod format
132
fb9cefb4 133 perlhist Perl history records
4755096e 134 perldelta Perl changes since previous version
496c75d0 135 perl592delta Perl changes in version 5.9.2
e0eb806d 136 perl591delta Perl changes in version 5.9.1
1400179b 137 perl590delta Perl changes in version 5.9.0
e4bb216d 138 perl586delta Perl changes in version 5.8.6
07e9b5fe 139 perl585delta Perl changes in version 5.8.5
5f15c94e 140 perl584delta Perl changes in version 5.8.4
2e038148 141 perl583delta Perl changes in version 5.8.3
142 perl582delta Perl changes in version 5.8.2
b6235c4f 143 perl581delta Perl changes in version 5.8.1
2e038148 144 perl58delta Perl changes in version 5.8.0
77b096b5 145 perl573delta Perl changes in version 5.7.3
245d750e 146 perl572delta Perl changes in version 5.7.2
1db9e106 147 perl571delta Perl changes in version 5.7.1
148 perl570delta Perl changes in version 5.7.0
493a87da 149 perl561delta Perl changes in version 5.6.1
41630250 150 perl56delta Perl changes in version 5.6
4755096e 151 perl5005delta Perl changes in version 5.005
152 perl5004delta Perl changes in version 5.004
d516a115 153
2a551100 154 perlartistic Perl Artistic License
155 perlgpl GNU General Public License
156
d8416318 157=head2 Language-Specific
158
159 perlcn Perl for Simplified Chinese (in EUC-CN)
160 perljp Perl for Japanese (in EUC-JP)
161 perlko Perl for Korean (in EUC-KR)
162 perltw Perl for Traditional Chinese (in Big5)
163
fd7b6849 164=head2 Platform-Specific
165
37d4d706 166 perlaix Perl notes for AIX
a83b6f46 167 perlamiga Perl notes for AmigaOS
168 perlapollo Perl notes for Apollo DomainOS
169 perlbeos Perl notes for BeOS
dc5c060f 170 perlbs2000 Perl notes for POSIX-BC BS2000
a1f19229 171 perlce Perl notes for WinCE
49877630 172 perlcygwin Perl notes for Cygwin
245d750e 173 perldgux Perl notes for DG/UX
49877630 174 perldos Perl notes for DOS
9a997319 175 perlepoc Perl notes for EPOC
41630250 176 perlfreebsd Perl notes for FreeBSD
49877630 177 perlhpux Perl notes for HP-UX
a83b6f46 178 perlhurd Perl notes for Hurd
469e7be4 179 perlirix Perl notes for Irix
41630250 180 perlmachten Perl notes for Power MachTen
26d9b02f 181 perlmacos Perl notes for Mac OS (Classic)
0d53b15f 182 perlmacosx Perl notes for Mac OS X
a83b6f46 183 perlmint Perl notes for MiNT
ab648d5e 184 perlmpeix Perl notes for MPE/iX
41630250 185 perlnetware Perl notes for NetWare
49877630 186 perlos2 Perl notes for OS/2
187 perlos390 Perl notes for OS/390
522b859a 188 perlos400 Perl notes for OS/400
a83b6f46 189 perlplan9 Perl notes for Plan 9
190 perlqnx Perl notes for QNX
d420ca49 191 perlsolaris Perl notes for Solaris
772ff3b9 192 perltru64 Perl notes for Tru64
41630250 193 perluts Perl notes for UTS
cbe1151c 194 perlvmesa Perl notes for VM/ESA
49877630 195 perlvms Perl notes for VMS
9a997319 196 perlvos Perl notes for Stratus VOS
49877630 197 perlwin32 Perl notes for Windows
198
a0d0e21e 199
19799a22 200By default, the manpages listed above are installed in the
fc952dec 201F</usr/local/man/> directory.
202
203Extensive additional documentation for Perl modules is available. The
204default configuration for perl will place this additional documentation
205in the F</usr/local/lib/perl5/man> directory (or else in the F<man>
206subdirectory of the Perl library directory). Some of this additional
207documentation is distributed standard with Perl, but you'll also find
208documentation for third-party modules there.
209
210You should be able to view Perl's documentation with your man(1)
211program by including the proper directories in the appropriate start-up
212files, or in the MANPATH environment variable. To find out where the
213configuration has installed the manpages, type:
16d20bd9 214
760ac839 215 perl -V:man.dir
16d20bd9 216
fc952dec 217If the directories have a common stem, such as F</usr/local/man/man1>
218and F</usr/local/man/man3>, you need only to add that stem
219(F</usr/local/man>) to your man(1) configuration files or your MANPATH
220environment variable. If they do not share a stem, you'll have to add
221both stems.
16d20bd9 222
223If that doesn't work for some reason, you can still use the
4633a7c4 224supplied F<perldoc> script to view module information. You might
225also look into getting a replacement man program.
16d20bd9 226
a0d0e21e 227If something strange has gone wrong with your program and you're not
228sure where you should look for help, try the B<-w> switch first. It
229will often point out exactly where the trouble is.
230
231=head1 DESCRIPTION
232
5f05dabc 233Perl is a language optimized for scanning arbitrary
a0d0e21e 234text files, extracting information from those text files, and printing
235reports based on that information. It's also a good language for many
236system management tasks. The language is intended to be practical
237(easy to use, efficient, complete) rather than beautiful (tiny,
94d58c47 238elegant, minimal).
239
aa689395 240Perl combines (in the author's opinion, anyway) some of the best
241features of C, B<sed>, B<awk>, and B<sh>, so people familiar with
242those languages should have little difficulty with it. (Language
243historians will also note some vestiges of B<csh>, Pascal, and even
14218588 244BASIC-PLUS.) Expression syntax corresponds closely to C
a0d0e21e 245expression syntax. Unlike most Unix utilities, Perl does not
246arbitrarily limit the size of your data--if you've got the memory,
aa689395 247Perl can slurp in your whole file as a single string. Recursion is of
0f31cffe 248unlimited depth. And the tables used by hashes (sometimes called
aa689395 249"associative arrays") grow as necessary to prevent degraded
0f31cffe 250performance. Perl can use sophisticated pattern matching techniques to
14218588 251scan large amounts of data quickly. Although optimized for
aa689395 252scanning text, Perl can also deal with binary data, and can make dbm
253files look like hashes. Setuid Perl scripts are safer than C programs
14218588 254through a dataflow tracing mechanism that prevents many stupid
aa689395 255security holes.
256
257If you have a problem that would ordinarily use B<sed> or B<awk> or
258B<sh>, but it exceeds their capabilities or must run a little faster,
259and you don't want to write the silly thing in C, then Perl may be for
260you. There are also translators to turn your B<sed> and B<awk>
261scripts into Perl scripts.
a0d0e21e 262
263But wait, there's more...
264
19799a22 265Begun in 1993 (see L<perlhist>), Perl version 5 is nearly a complete
266rewrite that provides the following additional benefits:
a0d0e21e 267
13a2d996 268=over 4
a0d0e21e 269
551e1d92 270=item *
271
272modularity and reusability using innumerable modules
a0d0e21e 273
19799a22 274Described in L<perlmod>, L<perlmodlib>, and L<perlmodinstall>.
a0d0e21e 275
551e1d92 276=item *
277
278embeddable and extensible
a0d0e21e 279
19799a22 280Described in L<perlembed>, L<perlxstut>, L<perlxs>, L<perlcall>,
281L<perlguts>, and L<xsubpp>.
a0d0e21e 282
551e1d92 283=item *
284
63de3cb2 285roll-your-own magic variables (including multiple simultaneous DBM
286implementations)
a0d0e21e 287
19799a22 288Described in L<perltie> and L<AnyDBM_File>.
a0d0e21e 289
551e1d92 290=item *
291
292subroutines can now be overridden, autoloaded, and prototyped
a0d0e21e 293
19799a22 294Described in L<perlsub>.
a0d0e21e 295
551e1d92 296=item *
297
298arbitrarily nested data structures and anonymous functions
a0d0e21e 299
19799a22 300Described in L<perlreftut>, L<perlref>, L<perldsc>, and L<perllol>.
a0d0e21e 301
551e1d92 302=item *
303
304object-oriented programming
a0d0e21e 305
f6b3c421 306Described in L<perlobj>, L<perlboot>, L<perltoot>, L<perltooc>,
307and L<perlbot>.
a0d0e21e 308
551e1d92 309=item *
310
551e1d92 311support for light-weight processes (threads)
a0d0e21e 312
63de3cb2 313Described in L<perlthrtut> and L<threads>.
a0d0e21e 314
551e1d92 315=item *
316
63de3cb2 317support for Unicode, internationalization, and localization
a0d0e21e 318
63de3cb2 319Described in L<perluniintro>, L<perllocale> and L<Locale::Maketext>.
a0d0e21e 320
551e1d92 321=item *
322
323lexical scoping
a0d0e21e 324
19799a22 325Described in L<perlsub>.
a0d0e21e 326
551e1d92 327=item *
328
329regular expression enhancements
a0d0e21e 330
19799a22 331Described in L<perlre>, with additional examples in L<perlop>.
a0d0e21e 332
551e1d92 333=item *
334
335enhanced debugger and interactive Perl environment,
336with integrated editor support
a0d0e21e 337
f6b3c421 338Described in L<perldebtut>, L<perldebug> and L<perldebguts>.
a0d0e21e 339
551e1d92 340=item *
341
342POSIX 1003.1 compliant library
5f05dabc 343
19799a22 344Described in L<POSIX>.
5f05dabc 345
a0d0e21e 346=back
347
68dc0745 348Okay, that's I<definitely> enough hype.
a0d0e21e 349
8e465e4e 350=head1 AVAILABILITY
351
14218588 352Perl is available for most operating systems, including virtually
055fd3a9 353all Unix-like platforms. See L<perlport/"Supported Platforms">
354for a listing.
8bc4a6bb 355
a0d0e21e 356=head1 ENVIRONMENT
357
1e422769 358See L<perlrun>.
a0d0e21e 359
360=head1 AUTHOR
361
19799a22 362Larry Wall <larry@wall.org>, with the help of oodles of other folks.
a0d0e21e 363
a99b1639 364If your Perl success stories and testimonials may be of help to others
365who wish to advocate the use of Perl in their applications,
366or if you wish to simply express your gratitude to Larry and the
19799a22 367Perl developers, please write to perl-thanks@perl.org .
a99b1639 368
a0d0e21e 369=head1 FILES
370
5f05dabc 371 "@INC" locations of perl libraries
a0d0e21e 372
373=head1 SEE ALSO
374
375 a2p awk to perl translator
376 s2p sed to perl translator
377
c5f69108 378 http://www.perl.org/ the Perl homepage
c9e30dd8 379 http://www.perl.com/ Perl articles (O'Reilly Media)
f6b3c421 380 http://www.cpan.org/ the Comprehensive Perl Archive
c5f69108 381 http://www.pm.org/ the Perl Mongers
19799a22 382
a0d0e21e 383=head1 DIAGNOSTICS
384
9f1b1f2d 385The C<use warnings> pragma (and the B<-w> switch) produces some
386lovely diagnostics.
a0d0e21e 387
5a964f20 388See L<perldiag> for explanations of all Perl's diagnostics. The C<use
389diagnostics> pragma automatically turns Perl's normally terse warnings
390and errors into these longer forms.
a0d0e21e 391
392Compilation errors will tell you the line number of the error, with an
393indication of the next token or token type that was to be examined.
14218588 394(In a script passed to Perl via B<-e> switches, each
a0d0e21e 395B<-e> is counted as one line.)
396
397Setuid scripts have additional constraints that can produce error
398messages such as "Insecure dependency". See L<perlsec>.
399
400Did we mention that you should definitely consider using the B<-w>
401switch?
402
403=head1 BUGS
404
405The B<-w> switch is not mandatory.
406
407Perl is at the mercy of your machine's definitions of various
1b3f7d21 408operations such as type casting, atof(), and floating-point
409output with sprintf().
a0d0e21e 410
748a9306 411If your stdio requires a seek or eof between reads and writes on a
a0d0e21e 412particular stream, so does Perl. (This doesn't apply to sysread()
413and syswrite().)
414
415While none of the built-in data types have any arbitrary size limits
416(apart from memory size), there are still a few arbitrary limits: a
a30ac152 417given variable name may not be longer than 251 characters. Line numbers
418displayed by diagnostics are internally stored as short integers,
419so they are limited to a maximum of 65535 (higher numbers usually being
420affected by wraparound).
a0d0e21e 421
b0607b7a 422You may mail your bug reports (be sure to include full configuration
19799a22 423information as output by the myconfig program in the perl source
7f2de2d2 424tree, or by C<perl -V>) to perlbug@perl.org . If you've succeeded
055fd3a9 425in compiling perl, the B<perlbug> script in the F<utils/> subdirectory
19799a22 426can be used to help mail in a bug report.
4633a7c4 427
a0d0e21e 428Perl actually stands for Pathologically Eclectic Rubbish Lister, but
429don't tell anyone I said that.
430
431=head1 NOTES
432
433The Perl motto is "There's more than one way to do it." Divining
434how many more is left as an exercise to the reader.
435
4633a7c4 436The three principal virtues of a programmer are Laziness,
a0d0e21e 437Impatience, and Hubris. See the Camel Book for why.
16d20bd9 438