Perl Modules

How to write Perl Modules Some practical advice about how to build a perl module March 21, 2003 – Stanford Linear Accelerator Center Fabrizio Coccetti

Agenda

What a Perl Module is

Why it is convenient to use Perl Modules

How to make Perl Modules

An example of a Perl Module

Preparing the package for shipping

Perl Module are easy to make and handy to use

What a Perl Module is

A Perl Module is a self-contained piece of [Perl] code that can be used by a Perl program (or by other Perl modules)

It is conceptually similar to:

a C link library

a C++/Java class

Why it is convenient to use PMs

Installation is straightforward: perl Makefile.PL; make; make install

The Perl interpreter has a list of directories in which it searches for modules (global array @INC)

Installation is platform independent (Solaris, Linux, Windows, …)

Easy to use in Perl Programs: use IPEM::PingER

Easy to update both for the maintainers of a Perl Module and system administrators at remote sites

Time saving technique !!

Before making a PM

Chose an appropriate name for the PM

Each Perl Module has an unique name. Perl provides a hierarchal name space for modules, similar to the name space for Java classes.

Components of a module name are separated by double colons “::”. i.e. IEPM::PingER

Let’s start to make a Perl Module

Create the Perl Module Tree:

-A omits the Autoloader code (best used by modules that define a large number of infrequently used subroutines)

-X omits XS elements (eXternal Subroutine, where eXternal means external to Perl, i.e. C)

-n specifies the name of the module

$ h2xs -AX -n IEPM::PingER

What h2xs does for the developer

Creates subdirs: ./IEPM/PingER/

Creates the following files and the t/ dir:

Changes

Makefile.PL

MANIFEST (contains the list of all files in the package )

README

t/ (test files)

PingER.pm (perl code goes here)

Some advice on writing the code of a PM

A PM can use other PMs

use strict; (i.e. $IEPM::PingER::var)

use 5.6.1;

$VERSION=’1.03’;

@EXPORT = qw(ping_it);

sub ping_it {… … …}

1;

__END__

How to use a PM in a Perl program

Another way is to use @EXPORT_OK in the Perl Module:

@EXPORT_OK = qw(ping_it log_it);

And in the Perl Program

use IEPM::PingER qw(log_it)

use IEPM::PingER; $answer = ping_it (host.domain.edu);

Use Carp in Perl Modules

The Carp module allows to present error messages from the caller's perspective

warn "No hostname given"; No hostname given at /usr/local/lib/perl5/site_perl/5.6/IEPM/PingER.pm line 143. carp "No hostname given"; No hostname given at perl_script.pl line 5.

Recipe:

use Carp; warn carp die croak

Example: the beginning of IEPM::PingER

package IEPM::PingER;

use 5.008;

use strict;

use warnings;

use Carp;

require Exporter;

our @ISA = qw(Exporter);

use Time::CTime;

use DB_File;

our @EXPORT = qw(log_it ping_it);

our $VERSION = '1.03';

Example: the subroutine ping_it

PingER.PM

sub ping_it {

my ($ping_cmd,$dest_name,$dest_ip, $ping_interval, $ping_size, $ping_count) = @_ ;

… … … …

return ($time, $packets_sent, $packets_rcvd, $min, $avg, $max, @seqno, @pingtimes) ;

}

timeping.pl

use IEPM::PingER;

($time, $packets_sent, $packets_rcvd, $min, $avg, $max, $seqno, $pingtimes) = ping_it ($ping_cmd,$dest_name,$dest_ip, $ping_interval, 1000, $ping_count);

Preparing the package for shipping