[win32] merge changes#872,873 from maintbranch
[p5sagit/p5-mst-13.2.git] / pod / perl.pod
index eb6ff63..a7e02f6 100644 (file)
@@ -4,22 +4,25 @@ perl - Practical Extraction and Report Language
 
 =head1 SYNOPSIS
 
-B<perl>        [ B<-acdhnpPsSTuUvw> ] 
-[ S<B<-0>[I<octal>]> ] 
-[ S<B<-D>I<number/list>]> ]
-[ S<B<-F>I<string>> ] 
-[ S<B<-i>[I<extension>]> ] 
-[ S<B<-I>I<dir>> ]
-[ S<B<-l>I<octal>> ] 
-[ S<B<-x>I<dir>> ]
-[ I<programfile> | S<B<-e> I<command>> ] 
-[ I<argument> ... ]
+B<perl>        S<[ B<-sTuU> ]>
+       S<[ B<-hv> ] [ B<-V>[:I<configvar>] ]>
+       S<[ B<-cw> ] [ B<-d>[:I<debugger>] ] [ B<-D>[I<number/list>] ]>
+       S<[ B<-pna> ] [ B<-F>I<pattern> ] [ B<-l>[I<octal>] ] [ B<-0>[I<octal>] ]>
+       S<[ B<-I>I<dir> ] [ B<-m>[B<->]I<module> ] [ B<-M>[B<->]I<'module...'> ]>
+       S<[ B<-P> ]>
+       S<[ B<-S> ]>
+       S<[ B<-x>[I<dir>] ]>
+       S<[ B<-i>[I<extension>] ]>
+       S<[ B<-e> I<'command'> ] [ B<--> ] [ I<programfile> ] [ I<argument> ]...>
 
 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
     perltoc    Perl documentation table of contents
+
     perldata   Perl data structures
     perlsyn    Perl syntax
     perlop     Perl operators and precedence
@@ -28,42 +31,63 @@ of sections:
     perlfunc   Perl builtin functions
     perlvar    Perl predefined variables
     perlsub    Perl subroutines
-    perlmod    Perl modules
-    perlref    Perl references 
+    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
+
+    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 
+    perlguts   Perl internal functions for those doing extensions
     perlcall   Perl calling conventions from C
-    perlembed  Perl how to embed perl in your C or C++ app
-    perlpod    Perl plain old documentation
-    perlbook   Perl book information
+
+    perlhist   Perl history records
 
 (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</usr/local/man/> directory.  Some of this is distributed standard with
-Perl, but you'll also find third-party modules there.  You should be able
-to view this with your man(1) program by including the proper directories
-in the appropriate start-up files.  To find out where these are, type:
+By default, all of the above manpages are installed in the 
+F</usr/local/man/> directory.  
 
-    perl -le 'use Config; print "@Config{man1dir,man3dir}"'
+Extensive additional documentation for Perl modules is available.  The
+default configuration for perl will place this additional documentation
+in the F</usr/local/lib/perl5/man> directory (or else in the F<man>
+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.
 
-If the directories were F</usr/local/man/man1> and F</usr/local/man/man3>,
-you would only need to add F</usr/local/man> to your MANPATH.  If 
-they are different, you'll have to add both stems.
+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:
+
+    perl -V:man.dir
+
+If the directories have a common stem, such as F</usr/local/man/man1>
+and F</usr/local/man/man3>, you need only to add that stem
+(F</usr/local/man>) 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 F<perldoc> script to view module information.  You might
@@ -75,31 +99,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<sed>, B<awk>, and B<sh>, so people
-familiar with those languages should have little difficulty with it.
-(Language historians will also note some vestiges of B<csh>, 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<sed>, B<awk>, and B<sh>, so people familiar with
+those languages should have little difficulty with it.  (Language
+historians will also note some vestiges of B<csh>, 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.  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<sed> or B<awk> or B<sh>, 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<sed> and B<awk> 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<sed> or B<awk> or
+B<sh>, 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<sed> and B<awk>
+scripts into Perl scripts.
 
 But wait, there's more...
 
@@ -129,7 +157,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
 
@@ -157,7 +186,7 @@ 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
 
@@ -182,80 +211,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
-
-Ok, that's I<definitely> enough hype.
-
-=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
+=item * Innumerable Unbundled Modules
 
-Used in executing subprocesses, and in finding the script if B<-S> is
-used.
+The Comprehensive Perl Archive Network described in L<perlmodlib>
+contains hundreds of plug-and-play modules full of reusable code.
+See F<http://www.perl.com/CPAN> for a site near you.
 
-=item PERL5LIB
+=item * Compilability
 
-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.  When running
-taint checks (because the script was running setuid or setgid, or the
-B<-T> switch was used), neither variable is used.  The script should
-instead say
-
-    use lib "/my/directory";
-
-=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.
+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<definitely> enough hype.
+
+=head1 ENVIRONMENT
 
-    $ENV{'PATH'} = '/bin:/usr/bin';    # or whatever you need
-    $ENV{'SHELL'} = '/bin/sh' if defined $ENV{'SHELL'};
-    $ENV{'IFS'} = ''          if defined $ENV{'IFS'};
+See L<perlrun>.
 
 =head1 AUTHOR
 
-Larry Wall E<lt><F<lwall@sems.com>E<gt>, with the help of oodles of other folks.
+Larry Wall <F<larry@wall.org>>, with the help of oodles of other folks.
+
+If your Perl success stories and testimonials may be of help to others 
+who wish to advocate the use of Perl in their applications, 
+or if you wish to simply express your gratitude to Larry and the 
+Perl developers, please write to <F<perl-thanks@perl.org>>.
 
 =head1 FILES
 
  "/tmp/perl-e$$"       temporary file for -e commands
- "@INC"                        locations of perl 5 libraries
+ "@INC"                        locations of perl libraries
 
 =head1 SEE ALSO
 
@@ -285,8 +283,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().  The latter
-can even trigger a coredump when passed ludicrous input values.
+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()
@@ -294,14 +292,13 @@ 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.
 
-See the perl bugs database at F<http://perl.com/perl/bugs/>.  You may
-mail your bug reports (be sure to include full configuration information
-as output by the myconfig program in the perl source tree) to
-F<perlbug@perl.com>.
+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<perl -V>) to <F<perlbug@perl.com>>.
 If you've succeeded in compiling perl, the perlbug script in the utils/
 subdirectory can be used to help mail in a bug report.