How to write Perl Modules

Some practical advice about how to build a perl module

March 21, 2003 Stanford Linear Accelerator Center Fabrizio Coccetti

March 21, 2003

Fabrizio Coccetti - Stanford Linear Accelerator Center

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

March 21, 2003

Fabrizio Coccetti - Stanford Linear Accelerator Center

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

March 21, 2003

Fabrizio Coccetti - Stanford Linear Accelerator Center

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 !!

March 21, 2003

Fabrizio Coccetti - Stanford Linear Accelerator Center

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

March 21, 2003 Fabrizio Coccetti - Stanford Linear Accelerator Center 5

Lets start to make a Perl Module

Create the Perl Module Tree:

$ h2xs -AX -n IEPM::PingER

-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

March 21, 2003

Fabrizio Coccetti - Stanford Linear Accelerator Center

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)

March 21, 2003

Fabrizio Coccetti - Stanford Linear Accelerator Center

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__

March 21, 2003

Fabrizio Coccetti - Stanford Linear Accelerator Center

How to use a PM in a Perl program

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

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)

March 21, 2003 Fabrizio Coccetti - Stanford Linear Accelerator Center 9

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 die carp croak

10

March 21, 2003

Fabrizio Coccetti - Stanford Linear Accelerator Center

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';

March 21, 2003 Fabrizio Coccetti - Stanford Linear Accelerator Center 11

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);

March 21, 2003 Fabrizio Coccetti - Stanford Linear Accelerator Center 12

Preparing the package for shipping

Prepare the package for shipping is straightforward:

$ perl Makefile.PL; make; make dist;

The commands above create the compressed archive:

IEPM-PingER-1.03.tar.gz

March 21, 2003

Fabrizio Coccetti - Stanford Linear Accelerator Center

13

References
Perl Module Mechanics

http://world.std.com/~swmcd/steven/perl/module_mechanics.html The Perl Module Library http://search.cpan.org/author/JHI/perl-5.8.0/pod/perlmodlib.pod Perl Modules http://search.cpan.org/author/JHI/perl-5.8.0/pod/perlmod.pod The Perl 5 Modules List http://www.cpan.org/modules/00modlist.long.html Practical Perl Programming http://www.cs.cf.ac.uk/Dave/PERL/node131.html Perlnewmod - preparing a new module for distribution http://www.perlpod.com/5.6.1/perlnewmod.html

March 21, 2003

Fabrizio Coccetti - Stanford Linear Accelerator Center

14