Using Modules

Chapter 2 - Perl Module Basics
by?Sam Tregar?
Apress ? 2002
Companion Web Site

Using modules in Perl is extremely easy. Simply place a use statement at the top of your program specifying the name of the module. For example, here's a program that lists all the files over 1 megabyte in size below the current directory, using the File::Find module that comes with Perl:

 #!/usr/bin/perl use File::Find; find(sub { print "$_\n" if -s $_ > 1_024_000; }, "."); 

The File::Find module provides the find() function that traverses directories. For every file it finds, it calls the subroutine you pass as the first argument. The name of the current file is made available in the $_ variable. In the preceding example the subroutine examines the size of the file using -s and prints its name if the size is over a megabyte.

You could, of course, write this program without using File::Find. However, it would certainly be much longer than the two lines required to do the job with File::Find. File::Find, like many modules, makes your life easier by providing you with functionality that you can use without having to write it yourself. Like most modules, File::Find provides documentation in POD format (covered in detail in 1]

 $ perldoc File::Find 

File::Find provides its functionality through the find() function. This function is exported. Exporting means that the module provides access to a symbol,^[2] in this case the find() subroutine, in the namespace where the module is used. I'll cover exporting in more depth later in this chapter.

You can use modules without exporting symbols by using require instead of use:

 #!/usr/bin/perl require File::Find; File::Find::find(sub { print "$File::Find::name\n" if -s > 1_024_000; }, '.'); 

As a result, the reference to find must be prefixed with a full package name and written as File::Find::find.

Another difference between the two is that use happens during compile time, whereas require happens at runtime. Perl runs a program in two phases-first, the program and all modules used by the program are compiled into an internal bytecode format. This is known as compile time. Next, the byte-code is executed and the program actually runs. Perl programs can actually go back and forth between runtime and compile time using two mechanisms: BEGIN and eval.

A BEGIN block is a way of getting a bit of runtime during compile time. When Perl encounters a BEGIN block, it executes the code found inside the BEGIN block as soon as it has been compiled, before any code that comes later in the program. For example, this line will print even if there's a compilation error later in the script:

 BEGIN { print "Hello! I'm running in the middle of compiling.\n" } 

An eval with a string argument is a way of getting a bit of compile time during runtime. For example, this code will be compiled and run after the program is in runtime, which allows the code to be built during runtime:

 eval "print 'Hello! I'm compiling in the middle of running.\n"; 

Since use is just a way of doing a require operation and an import operation at compile time, use can be defined in terms of require using BEGIN:

 BEGIN { require File::Find; import File::Find; } 

And require can be defined in terms of use with eval:

 eval "use File::Find ();"; 

The pair of parenthesis after File::Find tells use not to import any symbols, which emulates how require works.

This comprises practically all of the universally applicable directions that can be given about using modules. In practice, you'll have to at least skim the documentation for each module you want to use in order to find out how it's meant to be used. As you'll see in the following text, there are many, many ways to do it!

^[1]UNIX users may also be able to use man to read module documentation. This is generally faster than using perldoc.

^[2]"Symbol" is a fancy word for named things in Perl. Variables, subroutines, and file-handles are all "symbols."