Introduction to Perl Modules
Brian Mathis

What is a Perl module?
In a nutshell, a Perl Module is a collection of functions that 
perform a set of tasks that work towards a common goal.
For example:
The FTP module has a group of functions that allows you to 
FTP a file from one place to another.
    
Types of modules
There are at least 3 types of modules.  They are: 
    - Pragmatic modules
    - Library modules
    - Object modules

Pragmatic Modules 
I'm not going to talk much about these.  A pragmatic 
module changes the way the compiler works.  Examples of 
pragmatic modules include: strict, English, integer, vars, 
etc…

There's more info about this in the 'perlmodlib' page.  
There's also other stuff in there about modules, a lot of 
which probably overlaps what I'm going to be talking about.

Library Modules
A library module simply contains a library of functions, 
usually related to performing a given task. Packaging a 
library into a module greatly simplifies the reuse of those 
functions.

Object Modules
An object module is similar to a library module, except that 
it uses an object-oriented style of reference.  This allows 
each "object" to store information internally to each piece 
of data, such as state information, etc..

The difference between Library modules and Object modules 
isn’t very clear, as far as using them goes.  The usage differs 
slightly in how you ‘use()’ the module, and create a new 
instance.  Sometimes you create a new object, and other 
times you access the module members directly.

Using modules
Whichever type of module you want to use, you can make 
them available to your program using the same function: 'use'.
For Example:
    use CGI;
will make the CGI module available for use in your program.

NOTE: Modules in the file system have the extension '.pm' on 
the end of them.  So the CGI module is located in the CGI.pm 
file.  Do not include the .pm extension in your 'use' statement.

[See Example 1]

Using modules, with options
Some modules will provide you with more than one method of 
use()ing them.  This is useful to keep the modules functions 
organized into a particular grouping.  It also allows you to 
import that module’s functions directly into your program’s 
namespace.

For example:
    use CGI qw( :cgi );
will import only the "cgi" set of CGI functions.  The :cgi group 
only includes those functions needed to handle CGI requests, 
such as the param() method.

Calling the module in this way allows you to call the module’s 
members directly, without having to create a specific reference 
for that module.  This is the equivalent of defining your own 
subroutines in your Perl program.

Other options for the CGI modules are:
    :form :html2 :html3 :netscape :html :standard :all
Each of these is described in detail in the CGI perldoc page.

If you want to include more than one option, you would use the 
form:
    use CGI qw( :html3 :cgi );

By the way, qw is a perl operator.  It means "world list".  Words 
are strings that are separated by spaces.  It can have any 
character specified as a delimiter, much like using the m// 
operator. There are other operators like this listed in the 
'perlop' page.

[See Example 2]

Groups of modules
Some modules are grouped together by type, such as the 
Net:: group of modules which includes: Net::FTP, Net::Telnet, 
and Net::Ping.

Module categories are organized on disk in subdirectories.  
For example the Net::FTP module is stored in Net/FTP.pm on 
the disk.

Installing modules
Manually
Perl comes installed with a large number of modules, but 
there are also many more available from the Central Perl 
Archive Network (CPAN). CPAN modules are available for 
download in a tar.gz format.

Installing a module (on unix) is pretty straighforward.  After 
unpacking the files and 'cd' into the directory, there are 
generally 3 steps to follow (as root):
	%> perl Makefile.PL
	%> make
	%> make install
After this, your new module is installed and ready for use.

Via the CPAN Module
You can also install a module, not surprisingly, with a 
module.  The CPAN module will automatically download, 
uncompress, make, install, and install any other modules 
that this module requires.  To use the CPAN module:
	%> perl -MCPAN -e'shell'
will start up the cpan shell that allows you to install your 
modules. To install a module:
	cpan> install Module
The CPAN module has many other options that you can 
play with (perldoc CPAN).

The first time you run CPAN, you will have to configure the 
module.  It usually figures everything else out for itself, so 
you can just accept the defaults.  If you don’t have a 
particular package on your system, don’t worry, in most 
cases it can figure out how to use something else.  NOTE: 
I have had little luck getting this module to work behind a 
proxy server.

Accessing module documentation with 'perldoc':
All modules come with thier own documentation built in.  To 
access the docs, you can use the perl-installed 'perldoc' 
program.  To get info on the CGI module, you can simply type:
    	perldoc CGI | more
and everything you ever needed to know about the CGI 
module will be displayed.

In addition to the reading module documentation, perldoc can 
access all of the perl man pages.  'perldoc perlop' is the same 
as 'man perlop'.  Sometimes the system isn't configured for 
man to look in the proper place for Perl's man pages, and this 
is how you can access them.

One other feature of perldoc is the -f switch.  The -f switch 
allows you to access Perl function documentation without 
opening up the whole perlfunc man page.  If you want info on 
the 'print' function:
    	perldoc -f print
will display only that function's docs.

If you notice formatting problems with perldoc's output, include 
the -t switch, which will force it to display in pure text, and not 
try to do things like bold and underline.

___________________________________
Resources:
    %> perldoc
	Installed on your system already.  This allows you to 
access
	all the docs for all the modules that come standard with 
Perl.

    %> perldoc CGI
	Info about the standard CGI module.  If you get a message 
like
	"No documentation found for CGI", you need to upgrade 
your
	Perl installation.

    http://www.perl.com
	Searchable Perl resources.

    http://www.perl.com/CPAN
	Main site for all available Perl modules
		Page 1