perl 5.000perl-5.000

[editor's note: this commit combines approximate 4 months of furious
releases of Andy Dougherty and Larry Wall - see pod/perlhist.pod for
details.  Andy notes that;
 
Alas neither my "Irwin AccuTrack" nor my DC 600A quarter-inch cartridge 
backup tapes from that era seem to be readable anymore.  I guess 13 years 
exceeds the shelf life for that backup technology :-(.
]

1 files changed, 472 insertions, 0 deletions

diff --git a/pod/perlmod.pod b/pod/perlmod.pod
new file mode 100644
index 0000000000..d804b1e4ed
--- /dev/null
+++ b/pod/perlmod.pod
@@ -0,0 +1,472 @@
+=head1 NAME
+
+perlmod - Perl modules (packages)
+
+=head1 DESCRIPTION
+
+=head2 Packages
+
+Perl provides a mechanism for alternate namespaces to protect packages
+from stomping on each others variables.  By default, a Perl script starts
+compiling into the package known as C<main>.  You can switch namespaces
+using the C<package> declaration.  The scope of the package declaration is
+from the declaration itself to the end of the enclosing block (the same
+scope as the local() operator).  Typically it would be the first
+declaration in a file to be included by the C<require> operator.  You can
+switch into a package in more than one place; it merely influences which
+symbol table is used by the compiler for the rest of that block.  You can
+refer to variables and filehandles in other packages by prefixing the
+identifier with the package name and a double colon:
+C<$Package::Variable>.  If the package name is null, the C<main> package
+as assumed.  That is, C<$::sail> is equivalent to C<$main::sail>.
+
+(The old package delimiter was a single quote, but double colon
+is now the preferred delimiter, in part because it's more readable
+to humans, and in part because it's more readable to B<emacs> macros.
+It also makes C++ programmers feel like they know what's going on.)
+
+Packages may be nested inside other packages: C<$OUTER::INNER::var>.  This
+implies nothing about the order of name lookups, however.  All symbols
+are either local to the current package, or must be fully qualified
+from the outer package name down.  For instance, there is nowhere
+within package C<OUTER> that C<$INNER::var> refers to C<$OUTER::INNER::var>.
+It would treat package C<INNER> as a totally separate global package.
+
+Only identifiers starting with letters (or underscore) are stored in a
+package's symbol table.  All other symbols are kept in package C<main>.
+In addition, the identifiers STDIN, STDOUT, STDERR, C<ARGV>,
+ARGVOUT, ENV, INC and SIG are forced to be in package C<main>,
+even when used for other purposes than their built-in one.  Note also
+that, if you have a package called C<m>, C<s> or C<y>, then you can't use
+the qualified form of an identifier since it will be interpreted instead
+as a pattern match, a substitution, or a translation.
+
+(Variables beginning with underscore used to be forced into package
+main, but we decided it was more useful for package writers to be able
+to use leading underscore to indicate private variables and method names.)
+
+Eval()ed strings are compiled in the package in which the eval() was
+compiled.  (Assignments to C<$SIG{}>, however, assume the signal
+handler specified is in the C<main. package.  Qualify the signal handler
+name if you wish to have a signal handler in a package.)  For an
+example, examine F<perldb.pl> in the Perl library.  It initially switches
+to the C<DB> package so that the debugger doesn't interfere with variables
+in the script you are trying to debug.  At various points, however, it
+temporarily switches back to the C<main> package to evaluate various
+expressions in the context of the C<main> package (or wherever you came
+from).  See L<perldebug>.
+
+=head2 Symbol Tables
+
+The symbol table for a package happens to be stored in the associative
+array of that name appended with two colons.  The main symbol table's
+name is thus C<%main::>, or C<%::> for short.  Likewise the nested package
+mentioned earlier is named C<%OUTER::INNER::>.
+
+The value in each entry of the associative array is what you are
+referring to when you use the C<*name> notation.  In fact, the following
+have the same effect, though the first is more efficient because it
+does the symbol table lookups at compile time:
+
+    local(*main::foo) = *main::bar; local($main::{'foo'}) =
+    $main::{'bar'};
+
+You can use this to print out all the variables in a package, for
+instance.  Here is F<dumpvar.pl> from the Perl library:
+
+   package dumpvar;
+   sub main::dumpvar {
+       ($package) = @_;
+       local(*stab) = eval("*${package}::");
+       while (($key,$val) = each(%stab)) {
+	   local(*entry) = $val;
+	   if (defined $entry) {
+	       print "\$$key = '$entry'\n";
+	   }
+
+	   if (defined @entry) {
+	       print "\@$key = (\n";
+	       foreach $num ($[ .. $#entry) {
+		   print "  $num\t'",$entry[$num],"'\n";
+	       }
+	       print ")\n";
+	   }
+
+	   if ($key ne "${package}::" && defined %entry) {
+	       print "\%$key = (\n";
+	       foreach $key (sort keys(%entry)) {
+		   print "  $key\t'",$entry{$key},"'\n";
+	       }
+	       print ")\n";
+	   }
+       }
+   }
+
+Note that even though the subroutine is compiled in package C<dumpvar>,
+the name of the subroutine is qualified so that its name is inserted
+into package C<main>.
+
+Assignment to a symbol table entry performs an aliasing operation,
+i.e.,
+
+    *dick = *richard;
+
+causes variables, subroutines and filehandles accessible via the
+identifier C<richard> to also be accessible via the symbol C<dick>.  If
+you only want to alias a particular variable or subroutine, you can
+assign a reference instead:
+
+    *dick = \$richard;
+
+makes $richard and $dick the same variable, but leaves
+@richard and @dick as separate arrays.  Tricky, eh?
+
+=head2 Package Constructors and Destructors
+
+There are two special subroutine definitions that function as package
+constructors and destructors.  These are the C<BEGIN> and C<END>
+routines.  The C<sub> is optional for these routines.
+
+A C<BEGIN> subroutine is executed as soon as possible, that is, the
+moment it is completely defined, even before the rest of the containing
+file is parsed.  You may have multiple C<BEGIN> blocks within a
+file--they will execute in order of definition.  Because a C<BEGIN>
+block executes immediately, it can pull in definitions of subroutines
+and such from other files in time to be visible to the rest of the
+file.
+
+An C<END> subroutine is executed as late as possible, that is, when the
+interpreter is being exited, even if it is exiting as a result of a
+die() function.  (But not if it's is being blown out of the water by a
+signal--you have to trap that yourself (if you can).)  You may have
+multiple C<END> blocks within a file--they wil execute in reverse
+order of definition; that is: last in, first out (LIFO).
+
+Note that when you use the B<-n> and B<-p> switches to Perl, C<BEGIN>
+and C<END> work just as they do in B<awk>, as a degenerate case.
+
+=head2 Perl Classes
+
+There is no special class syntax in Perl 5, but a package may function
+as a class if it provides subroutines that function as methods.  Such a
+package may also derive some of its methods from another class package
+by listing the other package name in its @ISA array.  For more on
+this, see L<perlobj>.
+
+=head2 Perl Modules
+
+In Perl 5, the notion of packages has been extended into the notion of
+modules.  A module is a package that is defined in a library file of
+the same name, and is designed to be reusable.  It may do this by
+providing a mechanism for exporting some of its symbols into the symbol
+table of any package using it.  Or it may function as a class
+definition and make its semantics available implicitly through method
+calls on the class and its objects, without explicit exportation of any
+symbols.  Or it can do a little of both.
+
+Perl modules are included by saying
+
+    use Module;
+
+or
+
+    use Module LIST;
+
+This is exactly equivalent to
+
+    BEGIN { require "Module.pm"; import Module; }
+
+or
+
+    BEGIN { require "Module.pm"; import Module LIST; }
+
+All Perl module files have the extension F<.pm>.  C<use> assumes this so
+that you don't have to spell out "F<Module.pm>" in quotes.  This also
+helps to differentiate new modules from old F<.pl> and F<.ph> files.
+Module names are also capitalized unless they're functioning as pragmas,
+"Pragmas" are in effect compiler directives, and are sometimes called
+"pragmatic modules" (or even "pragmata" if you're a classicist).
+
+Because the C<use> statement implies a C<BEGIN> block, the importation
+of semantics happens at the moment the C<use> statement is compiled,
+before the rest of the file is compiled.  This is how it is able
+to function as a pragma mechanism, and also how modules are able to
+declare subroutines that are then visible as list operators for
+the rest of the current file.  This will not work if you use C<require>
+instead of C<use>.  Therefore, if you're planning on the module altering
+your namespace, use C<use>; otherwise, use C<require>.  Otherwise you 
+can get into this problem:
+
+    require Cwd;		# make Cwd:: accessible
+    $here = Cwd::getcwd();	
+
+    use Cwd;			# import names from Cwd:: 
+    $here = getcwd();
+
+    require Cwd;	    	# make Cwd:: accessible
+    $here = getcwd(); 		# oops! no main::getcwd()
+
+Perl packages may be nested inside other package names, so we can have
+package names containing C<::>.  But if we used that package name
+directly as a filename it would makes for unwieldy or impossible
+filenames on some systems.  Therefore, if a module's name is, say,
+C<Text::Soundex>, then its definition is actually found in the library
+file F<Text/Soundex.pm>.
+
+Perl modules always have a F<.pm> file, but there may also be dynamically
+linked executables or autoloaded subroutine definitions associated with
+the module.  If so, these will be entirely transparent to the user of
+the module.  It is the responsibility of the F<.pm> file to load (or
+arrange to autoload) any additional functionality.  The POSIX module
+happens to do both dynamic loading and autoloading, but the user can
+just say C<use POSIX> to get it all.
+
+For more information on writing extension modules, see L<perlapi>
+and L<perlguts>.
+
+=head1 NOTE
+
+Perl does not enforce private and public parts of its modules as you may
+have been used to in other languages like C++, Ada, or Modula-17.  Perl
+doesn't have an infatuation with enforced privacy.  It would prefer
+that you stayed out of its living room because you weren't invited, not
+because it has a shotgun.
+
+The module and its user have a contract, part of which is common law,
+and part of which is "written".  Part of the common law contract is
+that a module doesn't pollute any namespace it wasn't asked to.  The
+written contract for the module (AKA documentation) may make other
+provisions.  But then you know when you C<use RedefineTheWorld> that
+you're redefining the world and willing to take the consequences.
+
+=head1 THE PERL MODULE LIBRARY
+
+A number of modules are included the the Perl distribution.  These are
+described below, and all end in F<.pm>.  You may also discover files in 
+the library directory that end in either F<.pl> or F<.ph>.  These are old
+libaries supplied so that old programs that use them still run.  The
+F<.pl> files will all eventually be converted into standard modules, and
+the F<.ph> files made by B<h2ph> will probably end up as extension modules
+made by B<h2xs>.  (Some F<.ph> values may already be available through the
+POSIX module.)  The B<pl2pm> file in the distribution may help in your
+conversion, but it's just a mechanical process, so is far from bullet proof.
+
+=head2 Pragmatic Modules
+
+They work somewhat like pragmas in that they tend to affect the compilation of
+your program, and thus will usually only work well when used within a
+C<use>, or C<no>.  These are locally scoped, so if an inner BLOCK
+may countermand any of these by saying
+
+    no integer;
+    no strict 'refs';
+
+which lasts until the end of that BLOCK.
+
+The following programs are defined (and have their own documentation).
+
+=over 12
+
+=item C<integer>
+
+Perl pragma to compute arithmetic in integer instead of double
+
+=item C<less>
+
+Perl pragma to request less of something from the compiler
+
+=item C<sigtrap>
+
+Perl pragma to enable stack backtrace on unexpected signals
+
+=item C<strict>
+
+Perl pragma to restrict unsafe constructs
+
+=item C<subs>
+
+Perl pragma to predeclare sub names
+
+=back
+
+=head2 Standard Modules
+
+The following modules are all expacted to behave in a well-defined
+manner with respect to namespace pollution because they use the
+Exporter module.
+See their own documentation for details.
+
+=over 12
+
+=item C<Abbrev>
+
+create an abbreviation table from a list
+
+=item C<AnyDBM_File>
+
+provide framework for multiple DBMs 
+
+=item C<AutoLoader>
+
+load functions only on demand
+
+=item C<AutoSplit>
+
+split a package for autoloading
+
+=item C<Basename>
+
+parse file anme and path from a specification
+
+=item C<Benchmark>
+
+benchmark running times of code 
+
+=item C<Carp>
+
+warn or die of errors (from perspective of caller)
+
+=item C<CheckTree>
+
+run many filetest checks on a tree
+
+=item C<Collate>
+
+compare 8-bit scalar data according to the current locale
+
+=item C<Config>
+
+access Perl configuration option
+
+=item C<Cwd>
+
+get pathname of current working directory
+
+=item C<DynaLoader>
+
+Dynamically load C libraries into Perl code 
+
+=item C<English>
+
+use nice English (or B<awk>) names for ugly punctuation variables
+
+=item C<Env>
+
+Perl module that imports environment variables
+
+=item C<Exporter>
+
+module to control namespace manipulations 
+
+=item C<Fcntl>
+
+load the C Fcntl.h defines
+
+=item C<FileHandle>
+
+supply object methods for filehandles 
+
+=item C<Find>
+
+traverse a file tree
+
+=item C<Finddepth>
+
+traverse a directory structure depth-first
+
+=item C<Getopt>
+
+basic and extended getopt(3) processing
+
+=item C<MakeMaker>
+
+generate a Makefile for Perl extension
+
+=item C<Open2>
+
+open a process for both reading and writing
+
+=item C<Open3>
+
+open a process for reading, writing, and error handling
+
+=item C<POSIX>
+
+Perl interface to IEEE 1003.1 namespace
+
+=item C<Ping>
+
+check a host for upness
+
+=item C<Socket>
+
+load the C socket.h defines
+
+=back
+
+=head2 Extension Modules
+
+Extension modules are written in C (or a mix of Perl and C) and get
+dynamically loaded into Perl if and when you need them.  Supported
+extension modules include the Socket, Fcntl, and POSIX modules.
+
+The following are popular C extension modules, which while available at
+Perl 5.0 release time, do not come not bundled (at least, not completely)
+due to their size, volatility, or simply lack of time for adequate testing
+and configuration across the multitude of platforms on which Perl was
+beta-tested.  You are encouraged to look for them in archie(1L), the Perl
+FAQ or Meta-FAQ, the WWW page, and even their authors before randomly
+posting asking for their present condition and disposition.  There's no
+guarantee that the names or addresses below have not changed since printing,
+and in fact, they probably have!
+
+=over 12
+
+=item C<Curses>
+
+Written by William Setzer <F<William_Setzer@ncsu.edu>>, while not
+included with the standard distribution, this extension module ports to
+most systems.  FTP from your nearest Perl archive site, or try
+
+        ftp://ftp.ncsu.edu/pub/math/wsetzer/cursperl5??.tar.gz
+
+It is currently in alpha test, so the name and ftp location may
+change.
+
+
+=item C<DBI>
+
+This is the portable database interface written by
+<F<Tim.Bunce@ig.co.uk>>.  This supersedes the many perl4 ports for
+database extensions.  The official archive for DBperl extensions is
+F<ftp.demon.co.uk:/pub/perl/db>.  This archive contains copies of perl4
+ports for Ingres, Oracle, Sybase, Informix, Unify, Postgres, and
+Interbase, as well as rdb and shql and other non-SQL systems.
+
+=item C<DB_File>
+
+Fastest and most restriction-free of the DBM bindings, this extension module 
+uses the popular Berkeley DB to tie() into your hashes.  This has a
+standardly-distributed man page and dynamic loading extension module, but
+you'll have to fetch the Berkeley code yourself.  See L<DB_File> for
+where.
+
+=item C<Sx>
+
+This extension module is a front to the Athena and Xlib libraries for Perl
+GUI progamming, originally written by by Dominic Giampaolo
+<F<dbg@sgi.com>>, then and rewritten for Sx by FrE<eacute>dE<eacute>ric
+Chauveau <F<fmc@pasteur.fr>>.  It's available for FTP from
+
+    ftp.pasteur.fr:/pub/Perl/Sx.tar.gz
+
+=item C<Tk>
+
+This extension module is an object-oriented Perl5 binding to the popular
+tcl/tk X11 package.  However, you need know no TCL to use it!
+It was written by Malcolm Beattie <F<mbeattie@sable.ox.ac.uk>>.
+If you are unable to locate it using archie(1L) or a similar
+tool, you may try retrieving it from F</private/Tk-october.tar.gz>
+from Malcolm's machine listed above.
+
+=back