Programming with Perl Modules: Chapter 1

Introduction to Perl Modules and CPAN

What Are Packages? So What's in a Name? Packages and Symbol Tables Package Constructors and Destructors Modules Use Versus Require Object-Oriented Programming Method Invocation The CPAN Architecture

Perl modules are best described as batches of reusable code. Want to send an email message from your Perl program? You could write the code from scratch, or you can just use Net::SMTP. Want to give your script an elegant graphical interface? Take a look at the pTk module, which does just that.

The virtues extolled for Perl programmers are laziness, impatience, and hubris. Together, these admirable characteristics have led to the creation and use of many publicly accessible Perl modules. Because of laziness, programmers would rather write modules than repeat a procedure over and over (and would rather use modules written by other people than write new code from scratch). Because of impatience, programmers write consolidated code that is flexible enough to anticipate their future needs. And because of hubris, programmers share their triumphs with the rest of the Perl community and continually tweak their modules until they're the best they can be.

Recent Perl distributions include a variety of modules that perform a number of tasks, from parsing command-line arguments using the Getopt modules, to timing programs using Benchmark.

This chapter offers a conceptual overview of packages and modules in Perl and an introduction to the structure of the Comprehensive Perl Archive Network (CPAN).

If you're interested in writing your own Perl modules, refer to Chapter 13, Contributing to CPAN, which details the process of writing Perl modules and how to register with and distribute your contributions through CPAN.

What Are Packages?

Perl provides a mechanism to separate residents and guests, known as packages. A package can act like the front door to your house; you only invite people you know to come inside; you decide who can enter. People who live in your house extend the same courtesy to your neighbors by knocking before entering those people's homes.

Your residence and property might be compared to a package's namespace: when you buy a property, the mortgage is in your name--"Nathan owns this house."

So, what if I live in a duplex or condominium? The same applies. Although there may be 20 units in your building, each unit has its own address and door.

A package, then, is a namespace implementation that protects packages from affecting variables in other packages.

The extent of the effects of the package statement includes everything from the package declaration through the end of the enclosing block, eval, end of file, or declaration of another package--whichever comes first. A package statement affects only dynamic variables (globals, even when local()ized), not lexical variables (declared with my()).

So What's in a Name?

package BushWhack;

sub lawn_kid {
    my $lk = shift;
    print("$lk is a lawn kid.\n");
}

lawn_kid('Joe'); # or
BushWhack::lawn_kid('Joe\'s sister Sue');

package LawnCare;

my$asleep = 151;
my $not_paying_attention = 20;
package DUH; print "$not_paying_attention, $asleep\n";
package WAKEUP; print "$not_paying_attention, $asleep\n";

The awful_chemical() subroutine is in package LawnCare:

sub awful_chemical {
        my $ac = shift;
        print("$ac is a(n) awful chemical.\n");
}

LawnCare::awful_chemical('Chlorine');

You are able to create a BushWhack::LawnCare package. Symbols are local to the current package or qualified from the outer package down. In other words, there is no place in BushWhack where $LawnCare::BushWhack::variable refers to $BushWhack::variable.

Packages and Symbol Tables

In other words, *BushWhack represents the value of %BushWhack::--see the following:

local *low_flyer = *BushWhack::variable; # compile time
local *low_flyer = *BushWhack::{"variable"}; # run time

foreach $symbol_name (sort keys %BushWhack::) {
        local *local_sym = $BushWhack::{$symbol_name};
        print "\$$symbol_name is defined\n"
                if($local_sym);
        print "\@$symbol_name is defined\n"
                if(@local_sym);
        print "\%$symbol_name is defined\n"
                if(%sym);
}

Package Constructors and Destructors

Even if you have a subroutine call that appears before BEGIN, BEGIN still executes first:

package MakeRoom;
call_me_now();
sub call_me_now { print "I'm gonna be first!\n"; } # umm, no
BEGIN { print "See, told you that I'd be first.\n"; }
END { print "th-th-th-that's all folks.\n"; }

See, told you that I'd be first.
I'm gonna be first!
th-th-th-that's all folks.

package Repetition;
call_me_now();
sub call_me_now { 
        # err, no
        print "Hey, I *said* that I was going to be first!\n";
}
BEGIN { print "Yeah, I'm first!\n"; }
BEGIN { print "And I'm next!\n"; }
END { print "Well, you've got nothing to complain about - I'm ",
                "last\n"; }

Yeah, I'm first!
And I'm next!
Hey, I *said* that I was going to be first!
Well, you've got nothing to complain about - I'm last

The END subroutine does what it says. Code contained in an END subroutine is executed when the interpreter is exiting; even if the interpreter is exiting because of a die().

A program can have multiple END statements, where the last END is executed until the first END is reached:[2]

END { print "Am I *really* first?\n"; }
$random_file = 'some_file.ext';
open(FOO, $random_file)
    or die("can't open $random_file: $!");
close(FOO);
END { print "Am I *really* second?\n"; }

can't open some_file.ext: No such file or directory at myscript line 4.
Am I *really* second?
Am I *really* first?

Modules

So, what's a module? A module is a package stored in a file with the same name; it is intended to be reused. Modules can export symbols into their caller's package. Symbols don't need to be explicitly exported. Class modules can also export their symbols but typically should not.

Regardless of the mechanism you use to write a module or any other goodies, such as exporting symbols or creating objects, Perl modules have a .pm extension.[3]

Since you probably won't be writing your modules to be pragmas (compiler directives), you should capitalize module names. Since we must use the package name as its filename, such as Nathan::LastName, we'll use a filename like Nathan/LastName.pm. In this example, we'll be discussing Some::Module, contributed by Tom Christiansen.

Create a file called Some/Module.pm, and insert the following into it:

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;
   @ISA         = qw(Exporter);
   @EXPORT      = qw(&func1 &func2 &func3);
   %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);
}
use vars      @EXPORT_OK;
# nonexported 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)

1. After the package declaration and enabling of the strict pragma, we use a BEGIN to initialize @EXPORT_OK; we'll need to use vars @EXPORT_OK later.

   BEGIN {
      use Exporter   ();
   

   We use the Exporter module as if we're going to import symbols, but we're not importing anything. When you use use(), you're telling the package not to import any symbols into your current package. In this case, we're not importing any symbols from Exporter, just loading it in at compile-time.

2. Next, we bring in some globals the Exporter needs.

      use vars       qw($VERSION @ISA @EXPORT @EXPORT_OK %EXPORT_TAGS);
      # set the version for version checking
      $VERSION     = 1.00;
   

   @ISA tells the interpreter where to look for a method that can't be found in the current package; this is how Perl handles inheritance. One class (package) recursively inherits methods from all classes (packages) listed in its @ISA array. @ISA contains names of other packages; the packages are searched (depth-first, recursively) for the methods the interpreter is seeking. For example, we'll be using Exporter to handle importing.

      @ISA         = qw(Exporter);
   

3. Now, let's tell what we'll be exporting. In this case, it's both functions (&func1, &func2, &func4) and exported package globals and/or functions ($Var1, %Hashit, &func3).

      @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);
   }
   

4. Finally, it's time to add the nonexported globals, lexicals, and function prototypes, and the global destructor.

   END { }
   

Use Versus Require

In other words, use and require (which is used for reading Perl libraries) are two different things.

You can use Perl modules in your program with:

use Module;
use Module LIST;

require "Module";
require "Module.pm";

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

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

require TestModule;
$value = TestModule::test_me_out();

require TestModule;
$value = test_me_out(); # wrong!

use TestModule;
$value = test_me_out();

Object-Oriented Programming

[Language name here] is a revolutionary object-oriented programming language...

It makes your life easier when you're trying to generate a canvas filled with bouncing heads.

You can use Perl modules for object-oriented programming (OOP), but this doesn't mean you'll need to write (or even rewrite) your modules with object-oriented methodology in mind. Let's put Perl modules and OOP into perspective:

• An object is simply a reference that happens to know which class it belongs to.

• A class is simply a package that happens to provide methods to deal with object references.

• A method is simply a subroutine that expects an object reference (or a package name, for class methods) as the first argument.

An Object Is Simply a Reference

Here's a minimal case:

package FrothyMug;
sub new { bless {} }

sub new {
   my $self = {};
   bless $self;
   return $self;
}

sub new {
   my $class = shift;
   my $self = {};
   bless $self, $class;
   $self->initialize();
   return $self;
}

The scenario is similar here. A package's methods treat the reference as any other reference. Outside the package, the reference should only be accessed through the package's methods

A Class Is Simply a Package

The interpreter uses @ISA (see previous section, "Modules") to search for missing methods. If you change @ISA or add new subroutines, Perl needs to look up the method again because the cache has been changed. If Perl still can't find a method in @ISA, it does the lookup in UNIVERSAL, but if you have defined an (object's package) AUTOLOAD routine, AUTOLOAD is called instead of the missing method. If Perl can't find an AUTOLOAD routine, it checks (object's @ISA) AUTOLOAD. Finally, it checks for the method in UNIVERSAL AUTOLOAD; if this fails, the program exits with an error that the method can't be found.

Perl only does method inheritance, that is, interface inheritance. Access to instance data is left to the class. This isn't a problem because most classes' objects use an anonymous hash, which is very much like the grassy areas in the heartland of the United States--the anonymous hash acts like a grassy field where herds of cattle (other classes) come to graze.

A Method Is Simply a Subroutine

Class->meth();
$obj->meth();
$obj_or_clasname->meth();
meth Class;
meth $obj;
meth $obj_or_clasname;

Class and object methods could be static and instance methods, except that static is a fighting word in the Perl community. Class methods expect the name of the class as the first argument passed to the method. The constructor is an example of a class method. Class methods may simply ignore the first argument because the package of their caller is irrelevant.

You can also use a class method to look up an object by name:

sub find_my_object_by_name {
   my ($class, $name) = @_;
   $objtable{$name};
}

sub display_widget {
   my $self = shift;
   my @keys = @_ ? @_ : sort keys %$self;
   foreach $key (@keys) {
      print "\t$key => $self->{$key}\n";
   }
}

Method Invocation

$object = method Class "Whatever";
method_2 $object 'Param 1', 'Param 2';

method_2 { method Class "Whatever" } 'Param 1', 'Param 2';

$object = Class->method("Whatever");
$fred->display('Param 1', 'Param 2');

$parrot = Bird->noisy("Shh"), 'be', 'quiet';
$parrot->shoot(times => 5), pain => 'likely';

m1 $ob->m2;

$ob->m1->m2;

$ob->m2->m1;

The CPAN Architecture

The Perl Resource Kit contains a complete CPAN distribution, so access to the Perl modules discussed in this book is at your fingertips. See the accompanying Perl Utilities Guide for more information on how to install modules from the Perl Resource Kit CD

CPAN Mirrors The design of CPAN is to support and maintain many identified sites, or mirrors, across the globe. This ensures that anyone with an Internet connection can have reliable access to its contents at any time. Since the structure of all CPAN sites are the same, a user searching for the current version of Perl can be sure that the latest.tar.gz file is the same on every site. Users can directly connect to a CPAN site if they know the specific address. However, to facilitate the use of CPAN, site maintainers have also developed a multiplexor to automate the downloading of materials from CPAN sites. If a user visiting a multiplexed site (such as http://www.perl.com/CPAN/) selects a file, the multiplexor connects to the CPAN site best suited to the user.

.

How Is CPAN Organized?

Most CPAN materials are distributed "tar-gzipped." tar and gzip are popular UNIX data-archiving formats. Non-UNIX-based users must download software that extracts tar files first. A version of such software for Microsoft Windows 95 is Winzip, which is available from http://www.winzip.com.

Since CPAN provides the same offerings worldwide, the directory structure has been standardized so files can be located in the same location in the directory hierarchy at all CPAN sites. All CPAN sites use CPAN as the root directory, from which the user can select a specific Perl item. The CPAN snapshot that appears on your CD-ROM contains the same directory structure, starting with a CPAN directory.

From the CPAN directory you have the following choices:

Current directory is CPAN
CPAN.html       An HTML formatted CPAN info page
ENDINGS         Describes what the ".tgz" file extensions mean
MIRRORED.BY     A list of sites mirroring CPAN
MIRRORING.FROM  A list of sites mirroring CPAN
README          A brief description of what you'll find on CPAN
README.html     An HTML formatted version of the README file
RECENT          Recent additions to the CPAN site
RECENT.DAY      Recent additions to the CPAN site (daily)
RECENT.html     An HTML formatted list of recent additions
RECENT.WEEK     Recent additions to the CPAN site (weekly)
ROADMAP         What you'll find on CPAN and where
ROADMAP.html    An HTML formatted version of ROADMAP
SITES           An exhaustive list of CPAN sites
SITES.html      An HTML formatted version of SITES
authors         A list of CPAN authors
clpa            An archive of comp.lang.perl.announce
doc             Various Perl documentation, FAQs, etc.
indices         All that is indexed.
latest.tar.gz   The latest Perl distribution sources
misc            Misc Perl stuff like Larry Wall quotes and gifs
modules         Modules for Perl version 5
other-archives  Other things yet uncategorized
ports           Various Perl ports
scripts         Various scripts appearing in Perl books
src             The Perl sources from various versions

by-author   Modules organized by author's registered CPAN name
by-category Modules categorized by subject matter (see below)
by-module   Modules categorized by namespace (i.e., MIME)

02_Perl_Core_Modules
03_Development_Support
04_Operating_System_Interfaces
05_Networking_Devices_Inter_Process
06_Data_Type_Utilities
07_Database_Interfaces
08_User_Interfaces   
09_Interfaces_to_Other_Languages
10_File_Names_Systems_Locking  
11_String_Processing_Language_Text_Process
12_Option_Argument_Parameter_Processing
13_Internationalization_and_Locale     
14_Authentication_Security_Encryption  
15_World_Wide_Web_HTML_HTTP_CGI
16_Server_and_Daemon_Utilities
17_Archiving_and_Compression  
18_Images_Pixmap_Bitmap_Manipulation
19_Mail_and_Usenet_News
20_Control_Flow_Utilities
21_File_Handle_Input_Output
22_Microsoft_Windows_Modules
23_Miscellaneous_Modules
99_Not_In_Modulelist

Here's a sample directory listing from a CPAN site:

ANDK@                           CGI.pm-2.35.tar.gz@
CGI-Out-96.081401.readme@       CGI.pm-2.36.readme@
CGI-Out-96.081401.tar.gz@       CGI.pm-2.36.tar.gz@
CGI-Response-0.03.readme@       CGI_Imagemap-1.00.readme@
CGI-Response-0.03.tar.gz@       CGI_Imagemap-1.00.tar.gz@
CGI-modules-2.75.readme@        CGI_Lite-1.62.pm.gz@
CGI-modules-2.75.tar.gz@        DOUGM@
CGI-modules-2.76.readme@        LDS@
CGI-modules-2.76.tar.gz@        MGH@
CGI.pm-2.32.readme@             MIKEH@
CGI.pm-2.33.readme@             MUIR@
CGI.pm-2.34.readme@             SHGUN@
CGI.pm-2.35.readme@
cdrom:/.21/perl/CPAN/modules/by-module/CGI> 

How Do I Install the Module?

If you have root privileges or write access to the locations where Perl modules are installed on your system, you can easily follow these steps when installing most modules:

perl Makefile.PL
make
make test
make install

For example, to install a module in the directory /home/nvp/Perl/Modules, the PREFIX argument would look like:

perl Makefile.PL PREFIX=/home/nvp/Perl/Modules

make
make test
make install

Can't locate <ModuleName>.pm in @INC.
BEGIN failed--compilation aborted.

#!/usr/local/bin/perl -w
use lib '/home/nvp/Perl/Modules';
use ModuleName;

Where Is the Module Documented?

"Pod" stands for "plain old documentation." If you are familiar with mark-up languages like HTML, you won't have a difficult time understanding pod. Pod-formatted files contain plain text represented by special tags in a Perl module or script that doesn't require an interpreter to be read by humans. Pod tags are not interpreted when the script is executed; programmers may use pod tags as multiline comments. You'll find several examples of auto-generating pod tags in Chapter 13, Contributing to CPAN.

Pod files are installed into a subdirectory of the Perl lib directory, Pod, which contains the base manpages included with your Perl distribution. You can view these pages by using the perldoc command or by converting the pod file to the format of your choice by using one of the pod2XXX tools (e.g., pod2text, which converts to plain text; pod2html, which converts to HTML; or pod2man, which converts to standard manpage (n/troff) format).

For the nonstandard modules installed on your system, you can also use the perldoc command. For example:

perldoc CGI

Most modules were also distributed with manpages formatted in nroff or troff, in which case you can use the man command. If the man command fails, either the manpages have failed to have been installed or the location of the Perl manpages is not in your MANPATH. If the latter is the case, ask your system administrator to add the location of the Perl manpages to your system's global manpath.

How Do I Know What Modules Are Installed on My System?

[2] ENDs can be circumvented by signals that you have to trap on your own.

[3] A module can also call dynamically linked executables or autoload subroutines associated with the module, but this is transparent to the user.

Return to Table of Contents