=head1 NAME
-perlmod - Perl modules (packages)
+perlmod - Perl modules (packages and symbol tables)
=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
+Perl provides a mechanism for alternative namespaces to protect
+packages from stomping on each other's variables. In fact, there's
+really no such thing as a global variable in Perl. The package
+statement declares the compilation unit as being in the given
+namespace. The scope of the package declaration is from the
+declaration itself through the end of the enclosing block, C<eval>,
+or file, whichever comes first (the same scope as the my() and
+local() operators). Unqualified dynamic identifiers will be in
+this namespace, except for those few identifiers that if unqualified,
+default to the main package instead of the current one as described
+below. A package statement affects only dynamic variables--including
+those you've used local() on--but I<not> lexical variables created
+with my(). Typically it would be the first declaration in a file
+included by the C<do>, C<require>, or C<use> operators. 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 is 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--as opposed to using the
+single quote as separator, which was there to make Ada programmers feel
+like they knew what's going on. Because the old-fashioned syntax is still
+supported for backwards compatibility, if you try to use a string like
+C<"This is $owner's house">, you'll be accessing C<$owner::s>; that is,
+the $s variable in package C<owner>, which is probably not what you meant.
+Use braces to disambiguate, as in C<"This is ${owner}'s house">.
+
+Packages may themselves contain package separators, as in
+C<$OUTER::INNER::var>. This implies nothing about the order of
+name lookups, however. There are no relative packages: 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
+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>, including all punctuation variables, like $_. In addition,
+when unqualified, 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. 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 would be instead interpreted
+as a pattern match, a substitution, or a transliteration.
+
+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.)
+to use leading underscore to indicate private variables and method names.
+$_ is still global though. See also L<perlvar/"Technical Note on the
+Syntax of Variable Names">.
-Eval()ed strings are compiled in the package in which the eval() was
+C<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
+in the program 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>.
+The special symbol C<__PACKAGE__> contains the current package, but cannot
+(easily) be used to construct variables.
+
+See L<perlsub> for other scoping issues related to my() and local(),
+and L<perlref> regarding closures.
+
=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 symbol table for a package happens to be stored in the hash of that
+name with two colons appended. The main symbol table's name is thus
+C<%main::>, or C<%::> for short. Likewise the symbol table for the nested
+package mentioned earlier is named C<%OUTER::INNER::>.
+
+The value in each entry of the hash 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:
-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};
- local(*main::foo) = *main::bar; local($main::{'foo'}) =
- $main::{'bar'};
+(Be sure to note the B<vast> difference between the second line above
+and C<local $main::foo = $main::bar>. The former is accessing the hash
+C<%main::>, which is the symbol table of package C<main>. The latter is
+simply assigning scalar C<$bar> in package C<main> to scalar C<$foo> of
+the same package.)
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.,
+instance. The standard but antiquated F<dumpvar.pl> library and
+the CPAN module Devel::Symdump make use of this.
+
+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:
+causes variables, subroutines, formats, and file and directory handles
+accessible via the identifier C<richard> also to be accessible via the
+identifier C<dick>. If you want to alias only a particular variable or
+subroutine, assign a reference instead:
*dick = \$richard;
-makes $richard and $dick the same variable, but leaves
+Which 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.
+This mechanism may be used to pass and return cheap references
+into or from subroutines if you don't want to copy the whole
+thing. It only works when assigning to dynamic variables, not
+lexicals.
-For more information on writing extension modules, see L<perlxs>
-and L<perlguts>.
+ %some_hash = (); # can't be my()
+ *some_hash = fn( \%another_hash );
+ sub fn {
+ local *hashsym = shift;
+ # now use %hashsym normally, and you
+ # will affect the caller's %another_hash
+ my %nhash = (); # do what you want
+ return \%nhash;
+ }
-=head1 NOTE
+On return, the reference will overwrite the hash slot in the
+symbol table specified by the *some_hash typeglob. This
+is a somewhat tricky way of passing around references cheaply
+when you don't want to have to remember to dereference variables
+explicitly.
-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.
+Another use of symbol tables is for making "constant" scalars.
-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.
+ *PI = \3.14159265358979;
-=head1 THE PERL MODULE LIBRARY
+Now you cannot alter C<$PI>, which is probably a good thing all in all.
+This isn't the same as a constant subroutine, which is subject to
+optimization at compile-time. A constant subroutine is one prototyped
+to take no arguments and to return a constant expression. See
+L<perlsub> for details on these. The C<use constant> pragma is a
+convenient shorthand for these.
-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.
+You can say C<*foo{PACKAGE}> and C<*foo{NAME}> to find out what name and
+package the *foo symbol table entry comes from. This may be useful
+in a subroutine that gets passed typeglobs as arguments:
-=head2 Pragmatic Modules
+ sub identify_typeglob {
+ my $glob = shift;
+ print 'You gave me ', *{$glob}{PACKAGE}, '::', *{$glob}{NAME}, "\n";
+ }
+ identify_typeglob *foo;
+ identify_typeglob *bar::baz;
-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
+This prints
- no integer;
- no strict 'refs';
+ You gave me main::foo
+ You gave me bar::baz
-which lasts until the end of that BLOCK.
+The C<*foo{THING}> notation can also be used to obtain references to the
+individual elements of *foo. See L<perlref>.
-The following programs are defined (and have their own documentation).
+Subroutine definitions (and declarations, for that matter) need
+not necessarily be situated in the package whose symbol table they
+occupy. You can define a subroutine outside its package by
+explicitly qualifying the name of the subroutine:
-=over 12
+ package main;
+ sub Some_package::foo { ... } # &foo defined in Some_package
-=item C<diagnostics>
+This is just a shorthand for a typeglob assignment at compile time:
-Pragma to produce enhanced diagnostics
+ BEGIN { *Some_package::foo = sub { ... } }
-=item C<integer>
+and is I<not> the same as writing:
-Pragma to compute arithmetic in integer instead of double
+ {
+ package Some_package;
+ sub foo { ... }
+ }
-=item C<less>
+In the first two versions, the body of the subroutine is
+lexically in the main package, I<not> in Some_package. So
+something like this:
-Pragma to request less of something from the compiler
+ package main;
-=item C<sigtrap>
+ $Some_package::name = "fred";
+ $main::name = "barney";
-Pragma to enable stack backtrace on unexpected signals
+ sub Some_package::foo {
+ print "in ", __PACKAGE__, ": \$name is '$name'\n";
+ }
-=item C<strict>
+ Some_package::foo();
-Pragma to restrict unsafe constructs
+prints:
-=item C<subs>
+ in main: $name is 'barney'
-Pragma to predeclare sub names
+rather than:
-=back
+ in Some_package: $name is 'fred'
-=head2 Standard Modules
+This also has implications for the use of the SUPER:: qualifier
+(see L<perlobj>).
-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
+=head2 Package Constructors and Destructors
-=item *
-Language Extensions and Documentation Tools
+Four special subroutines act as package constructors and destructors.
+These are the C<BEGIN>, C<CHECK>, C<INIT>, 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. Once a C<BEGIN>
+has run, it is immediately undefined and any code it used is returned to
+Perl's memory pool. This means you can't ever explicitly call a C<BEGIN>.
+
+An C<END> subroutine is executed as late as possible, that is, after
+perl has finished running the program and just before the interpreter
+is being exited, even if it is exiting as a result of a die() function.
+(But not if it's polymorphing into another program via C<exec>, or
+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). C<END> blocks are not executed when you run perl with the
+C<-c> switch, or if compilation fails.
+
+Inside an C<END> subroutine, C<$?> contains the value that the program is
+going to pass to C<exit()>. You can modify C<$?> to change the exit
+value of the program. Beware of changing C<$?> by accident (e.g. by
+running something via C<system>).
+
+Similar to C<BEGIN> blocks, C<INIT> blocks are run just before the
+Perl runtime begins execution, in "first in, first out" (FIFO) order.
+For example, the code generators documented in L<perlcc> make use of
+C<INIT> blocks to initialize and resolve pointers to XSUBs.
+
+Similar to C<END> blocks, C<CHECK> blocks are run just after the
+Perl compile phase ends and before the run time begins, in
+LIFO order. C<CHECK> blocks are again useful in the Perl compiler
+suite to save the compiled state of the program.
+
+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.
+Both C<BEGIN> and C<CHECK> blocks are run when you use the B<-c>
+switch for a compile-only syntax check, although your main code
+is not.
-=item *
-Development Support
+=head2 Perl Classes
-=item *
-Operating System Interfaces
+There is no special class syntax in Perl, but a package may act
+as a class if it provides subroutines to act as methods. Such a
+package may also derive some of its methods from another class (package)
+by listing the other package name(s) in its global @ISA array (which
+must be a package global, not a lexical).
-=item *
-Networking, Device Control (modems) and InterProcess Communication
+For more on this, see L<perltoot> and L<perlobj>.
-=item *
-Data Types and Data Type Utilities
+=head2 Perl Modules
-=item *
-Database Interfaces
+A module is just a set of related functions in a library file, i.e.,
+a Perl package with the same name as the file. It is specifically
+designed to be reusable by other modules or programs. 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 explicitly
+exporting anything. Or it can do a little of both.
-=item *
-User Interfaces
+For example, to start a traditional, non-OO module called Some::Module,
+create a file called F<Some/Module.pm> and start with this template:
-=item *
-Interfaces to / Emulations of Other Programming Languages
+ package Some::Module; # assumes Some/Module.pm
-=item *
-File Names, File Systems and File Locking (see also File Handles)
+ use strict;
+ use warnings;
-=item *
-String Processing, Language Text Processing, Parsing and Searching
+ BEGIN {
+ use Exporter ();
+ our ($VERSION, @ISA, @EXPORT, @EXPORT_OK, %EXPORT_TAGS);
-=item *
-Option, Argument, Parameter and Configuration File Processing
+ # set the version for version checking
+ $VERSION = 1.00;
+ # if using RCS/CVS, this may be preferred
+ $VERSION = do { my @r = (q$Revision: 2.21 $ =~ /\d+/g); sprintf "%d."."%02d" x $#r, @r }; # must be all one line, for MakeMaker
-=item *
-Internationalization and Locale
+ @ISA = qw(Exporter);
+ @EXPORT = qw(&func1 &func2 &func4);
+ %EXPORT_TAGS = ( ); # eg: TAG => [ qw!name1 name2! ],
-=item *
-Authentication, Security and Encryption
+ # your exported package globals go here,
+ # as well as any optionally exported functions
+ @EXPORT_OK = qw($Var1 %Hashit &func3);
+ }
+ our @EXPORT_OK;
-=item *
-World Wide Web, HTML, HTTP, CGI, MIME
+ # non-exported package globals go here
+ our @more;
+ our $stuff;
-=item *
-Server and Daemon Utilities
+ # initialize package globals, first exported ones
+ $Var1 = '';
+ %Hashit = ();
-=item *
-Archiving and Compression
+ # then the others (which are still accessible as $Some::Module::stuff)
+ $stuff = '';
+ @more = ();
-=item *
-Images, Pixmap and Bitmap Manipulation, Drawing and Graphing
+ # all file-scoped lexicals must be created before
+ # the functions below that use them.
-=item *
-Mail and Usenet News
+ # file-private lexicals go here
+ my $priv_var = '';
+ my %secret_hash = ();
-=item *
-Control Flow Utilities (callbacks and exceptions etc)
+ # here's a file-private function as a closure,
+ # callable as &$priv_func; it cannot be prototyped.
+ my $priv_func = sub {
+ # stuff goes here.
+ };
-=item *
-File Handle and Input/Output Stream Utilities
+ # make all your functions, whether exported or not;
+ # remember to put something interesting in the {} stubs
+ sub func1 {} # no prototype
+ sub func2() {} # proto'd void
+ sub func3($$) {} # proto'd to 2 scalars
-=item *
-Miscellaneous Modules
+ # this one isn't exported, but could be called!
+ sub func4(\%) {} # proto'd to 1 hash ref
-=back
+ END { } # module clean-up code here (global destructor)
-Some of the reguster CPAN sites as of this writing include the following.
-You should try to choose one close to you:
+ ## YOUR CODE GOES HERE
-=over
+ 1; # don't forget to return a true value from the file
-=item *
-ftp://ftp.sterling.com/programming/languages/perl/
+Then go on to declare and use your variables in functions without
+any qualifications. See L<Exporter> and the L<perlmodlib> for
+details on mechanics and style issues in module creation.
-=item *
-ftp://ftp.sedl.org/pub/mirrors/CPAN/
+Perl modules are included into your program by saying
-=item *
-ftp://ftp.uoknor.edu/mirrors/CPAN/
+ use Module;
-=item *
-ftp://ftp.delphi.com/pub/mirrors/packages/perl/CPAN/
+or
-=item *
-ftp://uiarchive.cso.uiuc.edu/pub/lang/perl/CPAN/
+ use Module LIST;
-=item *
-ftp://ftp.cis.ufl.edu/pub/perl/CPAN/
+This is exactly equivalent to
-=item *
-ftp://ftp.switch.ch/mirror/CPAN/
+ BEGIN { require Module; import Module; }
-=item *
-ftp://ftp.sunet.se/pub/lang/perl/CPAN/
+or
-=item *
-ftp://ftp.ci.uminho.pt/pub/lang/perl/
+ BEGIN { require Module; import Module LIST; }
-=item *
-ftp://ftp.cs.ruu.nl/pub/PERL/CPAN/
+As a special case
-=item *
-ftp://ftp.demon.co.uk/pub/mirrors/perl/CPAN/
+ use Module ();
-=item *
-ftp://ftp.rz.ruhr-uni-bochum.de/pub/programming/languages/perl/CPAN/
+is exactly equivalent to
-=item *
-ftp://ftp.leo.org/pub/comp/programming/languages/perl/CPAN/
+ BEGIN { require Module; }
-=item *
-ftp://ftp.pasteur.fr/pub/computing/unix/perl/CPAN/
+All Perl module files have the extension F<.pm>. The C<use> operator
+assumes this so 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).
-=item *
-ftp://ftp.ibp.fr/pub/perl/CPAN/
+The two statements:
-=item *
-ftp://ftp.funet.fi/pub/languages/perl/CPAN/
+ require SomeModule;
+ require "SomeModule.pm";
-=item *
-ftp://ftp.tekotago.ac.nz/pub/perl/CPAN/
+differ from each other in two ways. In the first case, any double
+colons in the module name, such as C<Some::Module>, are translated
+into your system's directory separator, usually "/". The second
+case does not, and would have to be specified literally. The other
+difference is that seeing the first C<require> clues in the compiler
+that uses of indirect object notation involving "SomeModule", as
+in C<$ob = purge SomeModule>, are method calls, not function calls.
+(Yes, this really can make a difference.)
-=item *
-ftp://ftp.mame.mu.oz.au/pub/perl/CPAN/
+Because the C<use> statement implies a C<BEGIN> block, the importing
+of semantics happens as soon as 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 or unary operators for
+the rest of the current file. This will not work if you use C<require>
+instead of C<use>. With C<require> you can get into this problem:
-=item *
-ftp://coombs.anu.edu.au/pub/perl/
+ require Cwd; # make Cwd:: accessible
+ $here = Cwd::getcwd();
-=item *
-ftp://dongpo.math.ncu.edu.tw/perl/CPAN/
+ use Cwd; # import names from Cwd::
+ $here = getcwd();
-=item *
-ftp://ftp.lab.kdd.co.jp/lang/perl/CPAN/
+ require Cwd; # make Cwd:: accessible
+ $here = getcwd(); # oops! no main::getcwd()
-=item *
-ftp://ftp.is.co.za/programming/perl/CPAN/
+In general, C<use Module ()> is recommended over C<require Module>,
+because it determines module availability at compile time, not in the
+middle of your program's execution. An exception would be if two modules
+each tried to C<use> each other, and each also called a function from
+that other module. In that case, it's easy to use C<require>s instead.
-=back
+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 make 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>.
-For an up-to-date listing of CPAN sites,
-see http://www.perl.com/perl/ or ftp://ftp.perl.com/perl/.
+Perl modules always have a F<.pm> file, but there may also be
+dynamically linked executables (often ending in F<.so>) or autoloaded
+subroutine definitions (often ending in F<.al>) 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. For example,
+although the POSIX module happens to do both dynamic loading and
+autoloading, the user can say just C<use POSIX> to get it all.
+
+=head1 SEE ALSO
+
+See L<perlmodlib> for general style issues related to building Perl
+modules and classes, as well as descriptions of the standard library
+and CPAN, L<Exporter> for how Perl's standard import/export mechanism
+works, L<perltoot> and L<perltootc> for an in-depth tutorial on
+creating classes, L<perlobj> for a hard-core reference document on
+objects, L<perlsub> for an explanation of functions and scoping,
+and L<perlxstut> and L<perlguts> for more information on writing
+extension modules.