PERLMOD(1)       Perl Programmers Reference Guide      PERLMOD(1)


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.




29/Apr/1999            perl 5.005, patch 03                     1





PERLMOD(1)       Perl Programmers Reference Guide      PERLMOD(1)


       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:





29/Apr/1999            perl 5.005, patch 03                     2





PERLMOD(1)       Perl Programmers Reference Guide      PERLMOD(1)


           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



29/Apr/1999            perl 5.005, patch 03                     3





PERLMOD(1)       Perl Programmers Reference Guide      PERLMOD(1)


       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



29/Apr/1999            perl 5.005, patch 03                     4





PERLMOD(1)       Perl Programmers Reference Guide      PERLMOD(1)


       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: 1.3 $ =~ /\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! ],




29/Apr/1999            perl 5.005, patch 03                     5





PERLMOD(1)       Perl Programmers Reference Guide      PERLMOD(1)


               # 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;




29/Apr/1999            perl 5.005, patch 03                     6





PERLMOD(1)       Perl Programmers Reference Guide      PERLMOD(1)


       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();




29/Apr/1999            perl 5.005, patch 03                     7





PERLMOD(1)       Perl Programmers Reference Guide      PERLMOD(1)


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














29/Apr/1999            perl 5.005, patch 03                     8