PERLMOD(1)
NNAAMMEE
perlmod - Perl modules (packages and symbol tables)
DDEESSCCRRIIPPTTIIOONN
PPaacckkaaggeess
Perl provides a mechanism for alternative namespaces to
protect packages from stomping on each other's variables.
In fact, apart from certain magical variables, 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, eval, sub, or end of file,
whichever comes first (the same scope as the my() and
local() operators). All further unqualified dynamic
identifiers will be in this namespace. A package
statement affects only dynamic variables--including those
you've used local() on--but not lexical variables created
with my(). Typically it would be the first declaration in
a file to be included by the require or use operator. You
can switch into a package in more than one place; it
influences merely 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:
$Package::Variable. If the package name is null, the main
package is assumed. That is, $::sail is equivalent to
$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 eemmaaccss macros. It also makes C++ programmers
feel like they know what's going on.)
Packages may be nested inside other packages:
$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 OUTER that $INNER::var refers to
$OUTER::INNER::var. It would treat package 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 main, including all of the punctuation
variables like $_. In addition, the identifiers STDIN,
STDOUT, STDERR, ARGV, ARGVOUT, ENV, INC, and SIG are
forced to be in package main, even when used for other
purposes than their builtin one. Note also that, if you
have a package called m, s, or 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. $_ is still
global though.)
Eval()ed strings are compiled in the package in which the
eval() was compiled. (Assignments to $SIG{}, however,
assume the signal handler specified is in the main
package. Qualify the signal handler name if you wish to
have a signal handler in a package.) For an example,
examine perldb.pl in the Perl library. It initially
switches to the 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 main package to evaluate various
expressions in the context of the main package (or
wherever you came from). See the perldebug manpage.
The special symbol __PACKAGE__ contains the current
package, but cannot (easily) be used to construct
variables.
See the perlsub manpage for other scoping issues related
to my() and local(), and the perlref manpage regarding
closures.
SSyymmbbooll TTaabblleess
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 %main::, or %:: for short.
Likewise symbol table for the nested package mentioned
earlier is named %OUTER::INNER::.
The value in each entry of the hash is what you are
referring to when you use the *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 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 dumpvar, the name of the subroutine is qualified
so that its name is inserted into package main. While
popular many years ago, this is now considered very poor
style; in general, you should be writing modules and using
the normal export mechanism instead of hammering someone
else's namespace, even main's.
Assignment to a typeglob performs an aliasing operation,
i.e.,
*dick = *richard;
causes variables, subroutines, and file handles accessible
via the identifier richard to also be accessible via the
identifier dick. If you want to alias only 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?
This mechanism may be used to pass and return cheap
references into or from subroutines if you won't want to
copy the whole thing.
%some_hash = ();
*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;
}
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 won't want to have to remember to
dereference variables explicitly.
Another use of symbol tables is for making "constant"
scalars.
*PI = \3.14159265358979;
Now you cannot alter $PI, which is probably a good thing
all in all. This isn't the same as a constant subroutine
(one prototyped to take no arguments and to return a
constant expression), which is subject to optimization at
compile-time. This isn't. See the perlsub manpage for
details on these.
You can say *foo{PACKAGE} and *foo{NAME} to find out what
name and package the *foo symbol table entry comes from.
This may be useful in a subroutine which is passed
typeglobs as arguments
sub identify_typeglob {
my $glob = shift;
print 'You gave me ', *{$glob}{PACKAGE}, '::', *{$glob}{NAME}, "\n";
}
identify_typeglob *foo;
identify_typeglob *bar::baz;
This prints
You gave me main::foo
You gave me bar::baz
The *foo{THING} notation can also be used to obtain
references to the individual elements of *foo, see the
perlref manpage.
PPaacckkaaggee CCoonnssttrruuccttoorrss aanndd DDeessttrruuccttoorrss
There are two special subroutine definitions that function
as package constructors and destructors. These are the
BEGIN and END routines. The sub is optional for these
routines.
A 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 BEGIN blocks within a file--they will execute in
order of definition. Because a 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 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
BEGIN.
An 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
END blocks within a file--they will execute in reverse
order of definition; that is: last in, first out (LIFO).
Inside an END subroutine $? contains the value that the
script is going to pass to exit(). You can modify $? to
change the exit value of the script. Beware of changing
$? by accident (e.g. by running something via system).
Note that when you use the --nn and --pp switches to Perl,
BEGIN and END work just as they do in aawwkk, as a degenerate
case.
PPeerrll CCllaasssseess
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 the perltoot manpage and the perlobj
manpage.
PPeerrll MMoodduulleess
A module is just 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.
For example, to start a normal module called Some::Module,
create a file called Some/Module.pm and start with this
template:
package Some::Module; # assumes Some/Module.pm
use strict;
BEGIN {
use Exporter ();
use vars qw($VERSION @ISA @EXPORT @EXPORT_OK %EXPORT_TAGS);
# 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
@ISA = qw(Exporter);
@EXPORT = qw(&func1 &func2 &func4);
%EXPORT_TAGS = ( ); # eg: TAG => [ qw!name1 name2! ],
# your exported package globals go here,
# as well as any optionally exported functions
@EXPORT_OK = qw($Var1 %Hashit &func3);
}
use vars @EXPORT_OK;
# non-exported package globals go here
use vars qw(@more $stuff);
# initalize package globals, first exported ones
$Var1 = '';
%Hashit = ();
# then the others (which are still accessible as $Some::Module::stuff)
$stuff = '';
@more = ();
# all file-scoped lexicals must be created before
# the functions below that use them.
# file-private lexicals go here
my $priv_var = '';
my %secret_hash = ();
# here's a file-private function as a closure,
# callable as &$priv_func; it cannot be prototyped.
my $priv_func = sub {
# stuff goes here.
};
# 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
# this one isn't exported, but could be called!
sub func4(\%) {} # proto'd to 1 hash ref
END { } # module clean-up code here (global destructor)
Then go on to declare and use your variables in functions
without any qualifications. See the Exporter manpage and
the the perlmodlib manpage 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; }
As a special case
use Module ();
is exactly equivalent to
BEGIN { require "Module.pm"; }
All Perl module files have the extension .pm. use assumes
this so that you don't have to spell out "Module.pm" in
quotes. This also helps to differentiate new modules from
old .pl and .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 use statement implies a BEGIN block, the
importation of semantics happens at the moment the 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 require instead of use. With require 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()
In general use Module (); is recommended over require
Module;.
Perl packages may be nested inside other package names, so
we can have package names containing ::. 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, Text::Soundex, then
its definition is actually found in the library file
Text/Soundex.pm.
Perl modules always have a .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 .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 say just use POSIX to get it all.
For more information on writing extension modules, see the
perlxstut manpage and the perlguts manpage.
SSEEEE AALLSSOO
See the perlmodlib manpage for general style issues
related to building Perl modules and classes as well as
descriptions of the standard library and CPAN, the
Exporter manpage for how Perl's standard import/export
mechanism works, the perltoot manpage for an in-depth
tutorial on creating classes, the perlobj manpage for a
hard-core reference document on objects, and the perlsub
manpage for an explanation of functions and scoping.