home *** CD-ROM | disk | FTP | other *** search
- NAME
- perlmod - Perl modules (packages and symbol tables)
-
- DESCRIPTION
- Packages
-
- 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
- (although some identifiers default to the main package instead
- of the current one). 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 only affects 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 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: `$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
- 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 `"This is $owner's house"', you'll be accessing
- `$owner::s'; that is, the $s variable in package `owner', which
- is probably not what you meant. Use braces to disambiguate, as
- in `"This is ${owner}'s house"'.
-
- 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, when unqualified, 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 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. $_ 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.
-
- Symbol Tables
-
- 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. The standard 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, formats, and file and directory
- handles accessible via the identifier `richard' also to 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;
-
-
- Which 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. It only works when assigning to dynamic variables, not
- lexicals.
-
- %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;
- }
-
-
- 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, which is
- subject to optimization at compile-time. This isn't. A constant
- subroutine is one prototyped to take no arguments and to return
- a constant expression. See the perlsub manpage for details on
- these. The `use constant' pragma is a convenient shorthand for
- 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 that gets 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.
-
- Package Constructors and Destructors
-
- 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 polymorphing into
- another program via `exec', or 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 -n and -p switches to Perl, `BEGIN'
- and `END' work just as they do in awk, as a degenerate case. As
- currently implemented (and subject to change, since its
- inconvenient at best), both `BEGIN' *and* `END' blocks are run
- when you use the -c switch for a compile-only syntax check,
- although your main code is not.
-
- Perl Classes
-
- There is no special class syntax in Perl, but a package may
- function 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 in its
- global @ISA array (which must be a package global, not a
- lexical).
-
- For more on this, see the perltoot manpage and the perlobj
- manpage.
-
- Perl Modules
-
- 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);
-
- # initialize 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; import Module; }
-
-
- or
-
- BEGIN { require Module; import Module LIST; }
-
-
- As a special case
-
- use Module ();
-
-
- is exactly equivalent to
-
- BEGIN { require Module; }
-
-
- 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).
-
- The two statements:
-
- require SomeModule;
- require "SomeModule.pm";
-
-
- differ from each other in two ways. In the first case, any
- double colons in the module name, such as `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
- `require' clues in the compiler that uses of indirect object
- notation involving "SomeModule", as in `$ob = purge SomeModule',
- are method calls, not function calls. (Yes, this really can make
- a difference.)
-
- 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', 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 `use' each
- other, and each also called a function from that other module.
- In that case, it's easy to use `require's instead.
-
- 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.
-
- SEE ALSO
- 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.
-
-