X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperl.pod;h=3036f35b2197e7dd352c8d59dca229bfbfb5d1ed;hb=84850974f570c6c594cc0df54611ffc5f0b26130;hp=3664ab64020de270def8761ef3a07bbaf3a5b8f3;hpb=8e07c86ebc651fe92eb7e3b25f801f57cfb8dd6f;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perl.pod b/pod/perl.pod index 3664ab6..3036f35 100644 --- a/pod/perl.pod +++ b/pod/perl.pod @@ -4,10 +4,24 @@ perl - Practical Extraction and Report Language =head1 SYNOPSIS +B S<[ B<-sTuU> ]> + S<[ B<-hv> ] [ B<-V>[:I] ]> + S<[ B<-cw> ] [ B<-d>[:I] ] [ B<-D>[I] ]> + S<[ B<-pna> ] [ B<-F>I ] [ B<-l>[I] ] [ B<-0>[I] ]> + S<[ B<-I>I ] [ B<-m>[B<->]I ] [ B<-M>[B<->]I<'module...'> ]> + S<[ B<-P> ]> + S<[ B<-S> ]> + S<[ B<-x>[I] ]> + S<[ B<-i>[I] ]> + S<[ B<-e> I<'command'> ] [ B<--> ] [ I ] [ I ]...> + For ease of access, the Perl manual has been split up into a number of sections: perl Perl overview (this section) + perldelta Perl changes since previous version + perlfaq Perl frequently asked questions + perldata Perl data structures perlsyn Perl syntax perlop Perl operators and precedence @@ -16,43 +30,65 @@ of sections: perlfunc Perl builtin functions perlvar Perl predefined variables perlsub Perl subroutines - perlmod Perl modules - perlref Perl references and nested data structures + perlmod Perl modules: how they work + perlmodlib Perl modules: how to write and use + perlform Perl formats + perllocale Perl locale support + + perlref Perl references + perldsc Perl data structures intro + perllol Perl data structures: lists of lists + perltoot Perl OO tutorial perlobj Perl objects + perltie Perl objects hidden behind simple variables perlbot Perl OO tricks and examples + perlipc Perl interprocess communication + perldebug Perl debugging perldiag Perl diagnostic messages - perlform Perl formats - perlipc Perl interprocess communication perlsec Perl security perltrap Perl traps for the unwary perlstyle Perl style guide - perlxs Perl XS application programming interface - perlguts Perl internal functions for those doing extensions - perlcall Perl calling conventions from C - perlovl Perl overloading semantics - perlembed Perl how to embed perl in your C or C++ app + perlpod Perl plain old documentation perlbook Perl book information + perlembed Perl ways to embed perl in your C or C++ application + perlapio Perl internal IO abstraction interface + perlxs Perl XS application programming interface + perlxstut Perl XS tutorial + perlguts Perl internal functions for those doing extensions + perlcall Perl calling conventions from C + (If you're intending to read these straight through for the first time, the suggested order will tend to reduce the number of forward references.) -Additional documentation for perl modules is available in -the F directory. You can view this -with a man(1) program by including the following in the -appropriate start-up files. (You may have to adjust the path to -match $Config{'man3dir'}.) +By default, all of the above manpages are installed in the +F directory. + +Extensive additional documentation for Perl modules is available. The +default configuration for perl will place this additional documentation +in the F directory (or else in the F +subdirectory of the Perl library directory). Some of this additional +documentation is distributed standard with Perl, but you'll also find +documentation for third-party modules there. - .profile (for sh, bash or ksh users): - MANPATH=$MANPATH:/usr/local/lib/perl5/man - export MANPATH +You should be able to view Perl's documentation with your man(1) +program by including the proper directories in the appropriate start-up +files, or in the MANPATH environment variable. To find out where the +configuration has installed the manpages, type: - .login (for csh or tcsh users): - setenv MANPATH $MANPATH:/usr/local/lib/perl5/man + perl -V:man.dir + +If the directories have a common stem, such as F +and F, you need only to add that stem +(F) to your man(1) configuration files or your MANPATH +environment variable. If they do not share a stem, you'll have to add +both stems. If that doesn't work for some reason, you can still use the -supplied perldoc script to view module information. +supplied F script to view module information. You might +also look into getting a replacement man program. If something strange has gone wrong with your program and you're not sure where you should look for help, try the B<-w> switch first. It @@ -60,31 +96,35 @@ will often point out exactly where the trouble is. =head1 DESCRIPTION -Perl is an interpreted language optimized for scanning arbitrary +Perl is a language optimized for scanning arbitrary text files, extracting information from those text files, and printing reports based on that information. It's also a good language for many system management tasks. The language is intended to be practical (easy to use, efficient, complete) rather than beautiful (tiny, -elegant, minimal). It combines (in the author's opinion, anyway) some -of the best features of C, B, B, and B, so people -familiar with those languages should have little difficulty with it. -(Language historians will also note some vestiges of B, Pascal, -and even BASIC-PLUS.) Expression syntax corresponds quite closely to C +elegant, minimal). + +Perl combines (in the author's opinion, anyway) some of the best +features of C, B, B, and B, so people familiar with +those languages should have little difficulty with it. (Language +historians will also note some vestiges of B, Pascal, and even +BASIC-PLUS.) Expression syntax corresponds quite closely to C expression syntax. Unlike most Unix utilities, Perl does not arbitrarily limit the size of your data--if you've got the memory, -Perl can slurp in your whole file as a single string. Recursion is -of unlimited depth. And the hash tables used by associative arrays -grow as necessary to prevent degraded performance. Perl uses -sophisticated pattern matching techniques to scan large amounts of data -very quickly. Although optimized for scanning text, Perl can also -deal with binary data, and can make dbm files look like associative -arrays (where dbm is available). Setuid Perl scripts are safer than -C programs through a dataflow tracing mechanism which prevents many -stupid security holes. If you have a problem that would ordinarily use -B or B or B, but it exceeds their capabilities or must -run a little faster, and you don't want to write the silly thing in C, -then Perl may be for you. There are also translators to turn your -B and B scripts into Perl scripts. +Perl can slurp in your whole file as a single string. Recursion is of +unlimited depth. And the tables used by hashes (previously called +"associative arrays") grow as necessary to prevent degraded +performance. Perl uses sophisticated pattern matching techniques to +scan large amounts of data very quickly. Although optimized for +scanning text, Perl can also deal with binary data, and can make dbm +files look like hashes. Setuid Perl scripts are safer than C programs +through a dataflow tracing mechanism which prevents many stupid +security holes. + +If you have a problem that would ordinarily use B or B or +B, but it exceeds their capabilities or must run a little faster, +and you don't want to write the silly thing in C, then Perl may be for +you. There are also translators to turn your B and B +scripts into Perl scripts. But wait, there's more... @@ -114,7 +154,8 @@ will continue to work unchanged. Perl variables may now be declared within a lexical scope, like "auto" variables in C. Not only is this more efficient, but it contributes -to better privacy for "programming in the large". +to better privacy for "programming in the large". Anonymous +subroutines exhibit deep binding of lexical variables (closures). =item * Arbitrarily nested data structures @@ -136,13 +177,13 @@ A package can function as a class. Dynamic multiple inheritance and virtual methods are supported in a straightforward manner and with very little new syntax. Filehandles may now be treated as objects. -=item * Embeddible and Extensible +=item * Embeddable and Extensible Perl may now be embedded easily in your C or C++ application, and can either call or be called by your routines through a documented interface. The XS preprocessor is provided to make it easy to glue your C or C++ routines into Perl. Dynamic loading of modules is -supported. +supported, and Perl itself can be made into a dynamic library. =item * POSIX compliant @@ -167,80 +208,49 @@ to an object class which defines its access methods. =item * Subroutine definitions may now be autoloaded In fact, the AUTOLOAD mechanism also allows you to define any arbitrary -semantics for undefined subroutine calls. It's not just for autoloading. +semantics for undefined subroutine calls. It's not for just autoloading. =item * Regular expression enhancements -You can now specify non-greedy quantifiers. You can now do grouping +You can now specify nongreedy quantifiers. You can now do grouping without creating a backreference. You can now write regular expressions with embedded whitespace and comments for readability. A consistent extensibility mechanism has been added that is upwardly compatible with all old regular expressions. -=back +=item * Innumerable Unbundled Modules -Ok, that's I enough hype. +The Comprehensive Perl Archive Network described in L +contains hundreds of plug-and-play modules full of reusable code. +See F for a site near you. -=head1 ENVIRONMENT - -=over 12 - -=item HOME - -Used if chdir has no argument. - -=item LOGDIR - -Used if chdir has no argument and HOME is not set. - -=item PATH - -Used in executing subprocesses, and in finding the script if B<-S> is -used. - -=item PERL5LIB - -A colon-separated list of directories in which to look for Perl library -files before looking in the standard library and the current -directory. If PERL5LIB is not defined, PERLLIB is used. - -=item PERL5DB - -The command used to get the debugger code. If unset, uses - - BEGIN { require 'perl5db.pl' } - -=item PERLLIB - -A colon-separated list of directories in which to look for Perl library -files before looking in the standard library and the current -directory. If PERL5LIB is defined, PERLLIB is not used. +=item * Compilability +While not yet in full production mode, a working perl-to-C compiler +does exist. It can generate portable byte code, simple C, or +optimized C code. =back -Apart from these, Perl uses no other environment variables, except -to make them available to the script being executed, and to child -processes. However, scripts running setuid would do well to execute -the following lines before doing anything else, just to keep people -honest: +Okay, that's I enough hype. - $ENV{'PATH'} = '/bin:/usr/bin'; # or whatever you need - $ENV{'SHELL'} = '/bin/sh' if defined $ENV{'SHELL'}; - $ENV{'IFS'} = '' if defined $ENV{'IFS'}; +=head1 ENVIRONMENT + +See L. =head1 AUTHOR -Larry Wall , with the help of oodles of other folks. +Larry Wall >, with the help of oodles of other folks. =head1 FILES "/tmp/perl-e$$" temporary file for -e commands - "@INC" locations of perl 5 libraries + "@INC" locations of perl libraries =head1 SEE ALSO a2p awk to perl translator + s2p sed to perl translator =head1 DIAGNOSTICS @@ -265,7 +275,8 @@ switch? The B<-w> switch is not mandatory. Perl is at the mercy of your machine's definitions of various -operations such as type casting, atof() and sprintf(). +operations such as type casting, atof(), and floating-point +output with sprintf(). If your stdio requires a seek or eof between reads and writes on a particular stream, so does Perl. (This doesn't apply to sysread() @@ -273,10 +284,16 @@ and syswrite().) While none of the built-in data types have any arbitrary size limits (apart from memory size), there are still a few arbitrary limits: a -given identifier may not be longer than 255 characters, and no +given variable name may not be longer than 255 characters, and no component of your PATH may be longer than 255 if you use B<-S>. A regular expression may not compile to more than 32767 bytes internally. +You may mail your bug reports (be sure to include full configuration +information as output by the myconfig program in the perl source tree, +or by C) to >. +If you've succeeded in compiling perl, the perlbug script in the utils/ +subdirectory can be used to help mail in a bug report. + Perl actually stands for Pathologically Eclectic Rubbish Lister, but don't tell anyone I said that. @@ -285,6 +302,6 @@ don't tell anyone I said that. The Perl motto is "There's more than one way to do it." Divining how many more is left as an exercise to the reader. -The three principle virtues of a programmer are Laziness, +The three principal virtues of a programmer are Laziness, Impatience, and Hubris. See the Camel Book for why.