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

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

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

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 Carp in Perl Modules

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

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

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

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