This is patch.2b1f to perl5.002beta1.

[perl5.git] / pod / perlmod.pod

=head1 NAME

perlmod - Perl modules (packages)

=head1 DESCRIPTION

=head2 Packages

Perl provides a mechanism for alternative namespaces to protect packages
from stomping on each others variables.  In fact, apart from certain magical
variables, there's really no such thing as a global variable in Perl.
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, 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 because 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> typeglob 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 typeglob performs an aliasing operation,
i.e.,

    *dick = *richard;

causes variables, subroutines and file handles 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 will 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, 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

A module is a just 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.

For example, to start a normal module called Fred, create
a file called Fred.pm and put this at the start of it:

    package 	 Fred;
    require 	 Exporter;
    @ISA       = qw(Exporter);
    @EXPORT    = qw(func1 func2);
    @EXPORT_OK = qw($sally @listabob %harry func3);

Then go on to declare and use your variables in functions
without any qualifications.
See L<Exporter> and the I<Perl Modules File> for details on 
mechanics and style issues in module creation.

Perl modules are included into your program 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<perlxs>
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
libraries 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 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<diagnostics>

Pragma to produce enhanced diagnostics

=item C<integer>

Pragma to compute arithmetic in integer instead of double

=item C<less>

Pragma to request less of something from the compiler

=item C<sigtrap>

Pragma to enable stack backtrace on unexpected signals

=item C<strict>

Pragma to restrict unsafe constructs

=item C<subs>

Pragma to predeclare sub names

=back

=head2 Standard Modules

Standard, bundled modules are all expected to behave in a well-defined
manner with respect to namespace pollution because they use the
Exporter module.  See their own documentation for details.

To find out all the modules installed on your system, do this:

    find `perl -e 'print "@INC"'` -name '*.pm' -print

They should all have their own documentation installed and accessible via
your system man(1) command.  If that fails, try the I<perldoc> program.

=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.

Many popular C extension modules
do not come 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 with their authors before randomly
posting asking for their present condition and disposition.  

=head2 CPAN

CPAN stands for the Comprehensive Perl Archive Network.  This is a globally
replicated collection of all known Perl materials, including hundreds 
of unbunded modules.  Here are the major categories of modules:

=over

=item *
Language Extensions and Documentation Tools 

=item *
Development Support

=item *
Operating System Interfaces

=item *
Networking, Device Control (modems) and InterProcess Communication

=item *
Data Types and Data Type Utilities

=item *
Database Interfaces

=item *
User Interfaces

=item *
Interfaces to / Emulations of Other Programming Languages

=item *
File Names, File Systems and File Locking (see also File Handles)

=item *
String Processing, Language Text Processing, Parsing and Searching

=item *
Option, Argument, Parameter and Configuration File Processing

=item *
Internationalization and Locale

=item *
Authentication, Security and Encryption

=item *
World Wide Web, HTML, HTTP, CGI, MIME

=item *
Server and Daemon Utilities

=item *
Archiving and Compression

=item *
Images, Pixmap and Bitmap Manipulation, Drawing and Graphing

=item *
Mail and Usenet News

=item *
Control Flow Utilities (callbacks and exceptions etc)

=item *
File Handle and Input/Output Stream Utilities

=item *
Miscellaneous Modules

=back

Some of the reguster CPAN sites as of this writing include the following.
You should try to choose one close to you:

=over

=item *
ftp://ftp.sterling.com/programming/languages/perl/

=item *
ftp://ftp.sedl.org/pub/mirrors/CPAN/

=item *
ftp://ftp.uoknor.edu/mirrors/CPAN/

=item *
ftp://ftp.delphi.com/pub/mirrors/packages/perl/CPAN/

=item *
ftp://uiarchive.cso.uiuc.edu/pub/lang/perl/CPAN/

=item *
ftp://ftp.cis.ufl.edu/pub/perl/CPAN/

=item *
ftp://ftp.switch.ch/mirror/CPAN/

=item *
ftp://ftp.sunet.se/pub/lang/perl/CPAN/

=item *
ftp://ftp.ci.uminho.pt/pub/lang/perl/

=item *
ftp://ftp.cs.ruu.nl/pub/PERL/CPAN/

=item *
ftp://ftp.demon.co.uk/pub/mirrors/perl/CPAN/

=item *
ftp://ftp.rz.ruhr-uni-bochum.de/pub/programming/languages/perl/CPAN/

=item *
ftp://ftp.leo.org/pub/comp/programming/languages/perl/CPAN/

=item *
ftp://ftp.pasteur.fr/pub/computing/unix/perl/CPAN/

=item *
ftp://ftp.ibp.fr/pub/perl/CPAN/

=item *
ftp://ftp.funet.fi/pub/languages/perl/CPAN/

=item *
ftp://ftp.tekotago.ac.nz/pub/perl/CPAN/

=item *
ftp://ftp.mame.mu.oz.au/pub/perl/CPAN/

=item *
ftp://coombs.anu.edu.au/pub/perl/

=item *
ftp://dongpo.math.ncu.edu.tw/perl/CPAN/

=item *
ftp://ftp.lab.kdd.co.jp/lang/perl/CPAN/

=item *
ftp://ftp.is.co.za/programming/perl/CPAN/

=back

For an up-to-date listing of CPAN sites, 
see http://www.perl.com/perl/ or ftp://ftp.perl.com/perl/.