About Us Documentation

Contact Site Map



Man Page for PERLMOD

     perlmod - Perl modules (packages)


     Perl provides a mechanism for alternate namespaces to
     protect packages from stomping on each others variables.  By
     default, a Perl script starts compiling into the package
     known as main.  You can switch namespaces using the 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 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: $Package::Variable.  If the package name is null, the
     main package as assumed.  That is, $::sail is equivalent to

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

     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

     Only identifiers starting with letters (or underscore) are
     stored in a package's symbol table.  All other symbols are
     kept in package main.  In addition, the identifiers STDIN,
     to be in package main, even when used for other purposes
     than their built-in 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 since 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 $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 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.

     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 %main::, or %:: for
     short.  Likewise the nested package mentioned earlier is
     named %OUTER::INNER::.

     The value in each entry of the associative array is what you
     are referring to when you use the *name 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'}) =

     You can use this to print out all the variables in a
     package, for instance.  Here is dumpvar.pl from the Perl

        package dumpvar;
        sub main::dumpvar {
            ($package) = @_;
            local(*stab) = eval("*${package}::");
            while (($key,$val) = each(%stab)) {
                local(*entry) = $val;
                if (defined $entry) {
                    print "key = '$entry'0;

                if (defined @entry) {
                    print "@$key = (0;
                    foreach $num ($[ .. $#entry) {
                        print "  $num'",$entry[$num],"'0;
                    print ")0;

                if ($key ne "${package}::" && defined %entry) {
                    print "$key = (0;
                    foreach $key (sort keys(%entry)) {
                        print "  $key'",$entry{$key},"'0;
                    print ")0;

     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.

     Assignment to a symbol table entry performs an aliasing
     operation, i.e.,

         *dick = *richard;

     causes variables, subroutines and filehandles accessible via
     the identifier richard to also be accessible via the symbol
     dick.  If you only want to alias a particular variable or
     subroutine, you can assign a reference instead:

         *dick = ichard;

     makes $richard and $dick the same variable, but leaves
     @richard and @dick as separate arrays.  Tricky, eh?

     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

     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.

     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 wil execute in reverse order of
     definition; that is: last in, first out (LIFO).

     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.

     Perl Classes

     There is no special class syntax in Perl 5, 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
     perlobj manpage.

     Perl Modules

     In Perl 5, the notion of packages has been extended into the
     notion of modules.  A module is 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.

     Perl modules are included by saying

         use Module;


         use Module LIST;

     This is exactly equivalent to

         BEGIN { require "Module.pm"; import Module; }


         BEGIN { require "Module.pm"; import Module LIST; }

     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

     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.  Therefore, if you're planning on
     the module altering your namespace, use use; otherwise, use
     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 ::.  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

     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 just say use POSIX to get it all.

     For more information on writing extension modules, see the
     perlapi manpage and the perlguts manpage.

     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 use RedefineTheWorld that you're
     redefining the world and willing to take the consequences.

     A number of modules are included the the Perl  distribution.
     These are described below, and all end in .pm.  You may also
     discover files in the library directory that end in either
     .pl or .ph.  These are old libaries supplied so that old
     programs that use them still run.  The the .ph files made by
     h2ph will probably end up as extension modules made by h2xs.
     (Some .ph values may already be available through the POSIX
     module.)  The pl2pm file in the distribution may help in
     your conversion, but it's just a mechanical process, so is
     far from bullet proof.

     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 use, or no.  These are locally
     scoped, so if an inner BLOCK may countermand any of these by

         no integer;
         no strict 'refs';

     which lasts until the end of that BLOCK.

     The following programs are defined (and have their own

     integer     Perl pragma to compute arithmetic in integer
                 instead of double

     less        Perl pragma to request less of something from
                 the compiler

     sigtrap     Perl pragma to enable stack backtrace on
                 unexpected signals

     strict      Perl pragma to restrict unsafe constructs

     subs        Perl pragma to predeclare sub names

     Standard Modules

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

     Abbrev      create an abbreviation table from a list

     AnyDBM_File provide framework for multiple DBMs

     AutoLoader  load functions only on demand

     AutoSplit   split a package for autoloading

     Basename    parse file anme and path from a specification

     Benchmark   benchmark running times of code

     Carp        warn or die of errors (from perspective of

     CheckTree   run many filetest checks on a tree

     Collate     compare 8-bit scalar data according to the
                 current locale

     Config      access Perl configuration option

     Cwd         get pathname of current working directory

     DynaLoader  Dynamically load C libraries into Perl code

     English     use nice English (or awk) names for ugly
                 punctuation variables

     Env         Perl module that imports environment variables

     Exporter    module to control namespace manipulations

     Fcntl       load the C Fcntl.h defines

     FileHandle  supply object methods for filehandles

     Find        traverse a file tree

     Finddepth   traverse a directory structure depth-first

     Getopt      basic and extended getopt(3) processing

     MakeMaker   generate a Makefile for Perl extension

     Open2       open a process for both reading and writing

     Open3       open a process for reading, writing, and error

     POSIX       Perl interface to IEEE 1003.1 namespace

     Ping        check a host for upness

     Socket      load the C socket.h defines

     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.

     The following are popular C extension modules, which while
     available at Perl 5.0 release time, do not come not 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 their
     authors before randomly posting asking for their present
     condition and disposition.  There's no guarantee that the
     names or addresses below have not changed since printing,
     and in fact, they probably have!

     Curses      Written by William Setzer
                 <William_Setzer@ncsu.edu>, while not included
                 with the standard distribution, this extension
                 module ports to most systems.  FTP from your
                 nearest Perl archive site, or try


                 It is currently in alpha test, so the name and
                 ftp location may change.

     DBI         This is the portable database interface written
                 by <Tim.Bunce@ig.co.uk>.  This supersedes the
                 many perl4 ports for database extensions.  The
                 official archive for DBperl extensions is
                 ftp.demon.co.uk:/pub/perl/db.  This archive
                 contains copies of perl4 ports for Ingres,
                 Oracle, Sybase, Informix, Unify, Postgres, and
                 Interbase, as well as rdb and shql and other
                 non-SQL systems.

     DB_File     Fastest and most restriction-free of the DBM
                 bindings, this extension module uses the popular
                 Berkeley DB to tie() into your hashes.  This has
                 a standardly-distributed man page and dynamic
                 loading extension module, but you'll have to
                 fetch the Berkeley code yourself.  See the
                 DB_File manpage for where.

     Sx          This extension module is a front to the Athena
                 and Xlib libraries for Perl GUI progamming,
                 originally written by by Dominic Giampaolo
                 <dbg@sgi.com>, then and rewritten for Sx by

                 Frederic Chauveau <fmc@pasteur.fr>.  It's
                 available for FTP from


     Tk          This extension module is an object-oriented
                 Perl5 binding to the popular tcl/tk X11 package.
                 However, you need know no TCL to use it!  It was
                 written by Malcolm Beattie
                 <mbeattie@sable.ox.ac.uk>.  If you are unable to
                 locate it using archie(1L) or a similar tool,
                 you may try retrieving it from /private/Tk-
                 october.tar.gz from Malcolm's machine listed


Email addresses listed on this site may  NOT be used for unsolicited commercial email.

Ready-to-Run Software, Inc Privacy Statement

Portions (c)Copyright, 1996-2005 by Ready-to-Run Software, Inc
(All rights reserved.)
212 Cedar Cove
Lansing, NY 14882
Phone: 607 533 UNIX (8649)
Fax: 607 533 4002