Using a Perl Module

Designing and Using a Perl Module – Part 2

Foreword: In this part of the series, I explain how to use a Perl module.

By: Chrysanthus Date Published: 2 Apr 2016

Introduction

This is part 2 of my series, Designing and Using a Perl Module. In this part of the series, I explain how to use a Perl module. You should have read the previous part of the series because this is a continuation.

The Special @INC Variable
There is a predefined special array in Perl called, @INC. Here, INC means include. You place your modules in a subdirectory. You have to add the subdirectory path as an element to this array. In my system, the following paths were added automatically during installation:

C:/Perl/site/lib
C:/Perl/lib
.

Note that the dot (.) is the working directory. With the exception of the working directory, it is in these subdirectories where the Perl standard modules are kept. Whenever your (current) program wants a standard module, Perl (interpreter) looks for the module in the two directories. Whenever the current program wants any module, Perl looks for the module in any of these three directories. The paths to these three directories are always in the @INC array. So Perl actually looks for the directory paths in which modules are kept, in the array. From there, it knows the directories from where it will look for the modules.

You do not have to place your (custom) module in these subdirectories (of installation). You can place them in your own subdirectory, but place the path of your subdirectory in the @INC array. Whenever any program wants a module, Perl looks for the module in the subdirectories, whose paths are found in the @INC array.

A module you have written is called a custom module. Assume that your custom modules are in the subdirectory, C:/myDir. To push this directory path to the @INC array, you would type:

push (@INC, ("C:/myDir "));

Note: you can also place your custom module in your working directory (directory that has your current Perl program).

Note, in my Windows system if you push the directory path into the @INC array, the appended element is not saved; so when the computer is shut down, the path appended will no longer be in the array.

The Name of a Module
The name of a module typed in the program (current program) that is to use the module, is a “bareword”. It can be something like, Bar. You do not type the “.pm” extension. It can also be something like, Foo::Bar.

The program (script) that needs the module is the current program. This program file must always have the extension “.pl”. On the other hand “.pm” stands for Perl Module, which the module file should have (but the module name in the current program should not have).

If the name of the module typed has the double colon, then the double colon means forward slash, but do not type forward slash in its place. So Foo::Bar means Foo/Bar.pm where Foo is the name of the subdirectory in which the Bar.pm module is stored.

Assume that the module name typed in the current program is Foo::Bar and so the module is Bar.pm. Also assume that the path to the Foo subdirectory pushed into the @INC array is, C:/myDir . So, this path and the module become C:/myDir/Foo/Bar.pm . While searching for the module (file), when Perl gets C:/myDir from the @INC array, it would append Foo/Bar.pm to it to obtain the full path (and module).

Including a Module
A module has common functions and maybe a few variables to be used by many independent programs. To use a module, you have to include the module into the current program. You need just one statement to include the module. When you include a module, the module code replaces the include statement line, as if the module code was typed there. However you, the programmer does not see the code of the module. There are two predefined functions to use to include a module: you have the “require” function and the “use” function.

The require Function
The main syntax of the require function to include a module is:

require ModuleName;

The Perl interpreter will then use the @INC array to know the possible subdirectories (paths) that can have the module. It will then search the different subdirectories for the module. If it sees the module, it gets it. Remember, the module name in the subdirectory should have “.pm”, but this extension is not typed in the current program.

The require statement is normally typed at the top of the current program (script) and it would include a module only if that module has not already been included.

The use Function
The main syntax of the use function to include a module is:

use ModuleName VERSION;

The Perl interpreter will then use the @INC array to know the possible subdirectories (paths) that can have the module. It will then search the different subdirectories for the module. If it sees the module, it gets it. Remember, the module name in the subdirectory should have “.pm”, but this extension is not typed in the current program.

Here, VERSION is the version of the module, something like, 2.01 .

The use statement is normally typed at the top of the current program (script) and it would include a module only if that module has not already been included.

Using the Variables and functions of the Included Module
You use the entities (functions, variables, class) of the included module as if the module code was typed up in the current program.

Illustration
Consider the following module:

use strict;

package TestMod;

    our $VERSION = "1.01";

    our $var = 5;

    sub new  #optional
        {
            bless {}, $_[0];
        }

    sub funct
        {
            print "I am of a module.";
        }

    our $modObj = TestMod->new();

    1;

In my system, this file can be conveniently saved in the working directory or in the Perl library directories, C:/Perl/site/lib or C:/Perl/lib . The file is saved as TestMod.pm with the extension, “.pm”. Under this condition, you will type at the top of the current program either,

    require TestMod;

or

    use TestMod;

without typing the extension.

In the current program, to access the variable, $var, you would type,

    $TestMod::var

To use the package function in static manner, you would type something like, either of the following,

    TestMod::funct();
    TestMod->funct();

To instantiate your own object from the class of the module and use its function, type something like,

    my $anObj = TestMod->new();
    $anObj->funct();

To access the instantiated object inside the module, type:

    $TestMod::modObj

To Import Subroutines
Assume that you have a module with the functions, fn1(), fn2(), fn3() and fn4(). If you only want to use the functions, fn()1 and fn3(), then you will import them as follows:

use ModulName "fn1, fn3";

or

use ModulName qw|fn1, fn3|;

where in the second case, the operator qw|| provides the quotes.

Main difference between require and use
When a Perl script (program) is executed, there is some minimal compilation before the script is run. “use” loads the module (into memory for the script) at compile time, while “require” loads the module at runtime.

That is it for this part of the series. We stop here and continue in the next part.

Chrys

Broad Network

Related Articles

Using a Perl Module

Designing and Using a Perl Module – Part 2

Introduction

Related Links

Comments