## 41.9. Perl Boot Camp, Part 6: Modules

Modules are Perl's way of extending functionality, in the same way C has library files. Modules can be used to encapsulate a set of related function calls (the way Data::Dumper does), implement pragmas (like `use strict`), or create object classes (like HTML::TokeParser). Whatever a module does, it must first be installed on your system (Section 41.11) before you can use it.

Using a module in Perl is often straightforward. For example, the Data::Dumper module has a function called `Dumper` that takes a reference to a variable and deconstructs the entire structure into a printable string. This is an invaluable debugging tool. The following code shows Data::Dumper in action:

>     use Data::Dumper;
>     print "The current environment is: ", Dumper(\%ENV), "\n";

An abbreviated version of the output from this code is this:

>     The current enviroment is: $VAR1 = {
>               'DISPLAY' => ':0',
>               'COLORTERM' => 'gnome-terminal',
>               'QTDIR' => '/usr/lib/qt-2.3.0',
>               'PVM_RSH' => '/usr/bin/rsh',
>               'OSTYPE' => 'linux-gnu',
>               'PWD' => '/home/jjohn/docs/unix_powertools/upt',
>               'EDITOR' => 'emacs -nw',
>               'LOGNAME' => 'jjohn',
>               'MACHTYPE' => 'i386-redhat-linux-gnu',
>               'SHELL' => '/bin/bash',
>               'MAIL' => '/var/spool/mail/jjohn',
>               '_' => '/usr/local/bin/perl',
>               'HISTSIZE' => '1000',
>               'CVS_RSH' => 'ssh1',
>               'HOSTNAME' => 'marian',
>               'TERM' => 'xterm',
>               ...
>             };

In this code, the Data::Dumper is made available to your script with the use statement. You should be aware that use happens at the script's compile time, meaning that you can't use this statement to dynamically load modules at runtime (but this is possible; see Programming Perl for details). Data::Dumper automatically makes the function `Dumper` available to your script. Here the global hash `%ENV`, which contains all your shell's environment variables, is deconstructed. `Dumper` can take multiple variables, so when looking at a hash or array, be sure to prefix the variable with the reference operator (Section 41.5.4) `\`. Without a passed reference, the output of `Dumper` won't exactly what you expect.

Many Perl modules are object oriented. Although writing object classes may not be trivial, using them is. Here, the CGI module is used to create a very simple HTML page.

>     use CGI;
>     $q = CGI->new;
>     print
>         $q->header,
>         $q->start_html,
>         $q->h1("hello, world!"),
>         $q->end_html;

There's no difference in how object classes are brought into your script with use. New objects are created through a method traditionally called `new` (new is not an operator, as it is in other languages). Sometimes, `new` will require arguments. Once the object (`$q`) is created, all method access must be made through it, using the `->` operator. That's all there is too it. Of course every module is different, so you will need to use perldoc modulename (Section 41.10) to the module's documentation.

Infrequently, you may need to find the module files on your system. Modules are usually files that have the extension .pm and are found in one of the directories listed in the `@INC` array. Every module should declare its own namespace, so that its variables and functions don't overwrite the ones you define in the scripts that use the modules. These namespaces are hierarchical, so so that the module Data::Dumper belongs to the Data module group.[125] When the Data::Dumper module is installed on your system, it is placed somewhere with the rest of your Perl modules in a directory called Data, in which a file called Dumper.pm will be copied. Generally, `:`: in a module name translates to a `/` on the filesystem. You can also use `perldoc -l` `modulename` to list the module's filesystem path.

> [125]Well, that's the theory anyway. In practice, modules that aren't written by the same group of people often have somewhat arbitrary top-level namespaces.

There are many good reasons to learn Perl, but the ace up a Perl programmer's sleeve is the Comprehensive Perl Archive Network (Section 41.11) (CPAN), which is the central repository for Perl modules. There are hundreds of modules on CPAN, ranging from the essential (IO::Socket) to the useful (LWP, DBI, mod_perl), to the frivolous (Acme::Buffy). The main CPAN server is accessible on the web at http://www.cpan.org. CPAN is mirrored all over the world, so look for a mirror near you.

-- JJ

Copyright © 2003 O'Reilly & Associates. All rights reserved.