How to write Perl Modules

1
How to write Perl Modules

• Some practical advice about how to build a perl
  module
• March 21, 2003 Stanford Linear Accelerator
  Center
• Fabrizio Coccetti

2
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
3
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

4
Why it is convenient to use PMs

• Installation is straightforwardperl
  Makefile.PL make make install
• The Perl interpreter has a list of directories in
  which it searches for modules (global array _at_INC)
• Installation is platform independent (Solaris,
  Linux, Windows, )
• Easy to use in Perl Programsuse IPEMPingER
• Easy to update both for the maintainers of a Perl
  Module and system administrators at remote sites

Time saving technique !!
5
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. IEPMPingER

6
Lets 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 IEPMPingER
7
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)

8
Some advice on writing the code of a PM

• A PM can use other PMs
• use strict (i.e. IEPMPingERvar)
• use 5.6.1
• VERSION1.03
• _at_EXPORT qw(ping_it)
• sub ping_it
• 1
• __END__

9
How to use a PM in a Perl program
use IEPMPingER answer ping_it
(host.domain.edu)

• Another way is to use _at_EXPORT_OK in the Perl
  Module
• _at_EXPORT_OK qw(ping_it log_it)
• And in the Perl Program
• use IEPMPingER qw(log_it)

10
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

11
Example the beginning of IEPMPingER

• package IEPMPingER
• use 5.008
• use strict
• use warnings
• use Carp
• require Exporter
• our _at_ISA qw(Exporter)
• use TimeCTime
• use DB_File
• our _at_EXPORT qw(log_it ping_it)
• our VERSION '1.03'

12
Example the subroutine ping_it

• PingER.PM
• sub ping_it
• my (ping_cmd,dest_name,dest_ip,
  ping_interval, ping_size, ping_count) _at__
• return (time, packets_sent, packets_rcvd,
  min, avg, max, \_at_seqno, \_at_pingtimes)

• timeping.pl
• use IEPMPingER
• (time, packets_sent, packets_rcvd, min, avg,
  max, seqno, pingtimes) ping_it(ping_cmd,des
  t_name,dest_ip, ping_interval, 1000,
  ping_count)

13
Preparing the package for shipping

• Prepare the package for shipping is
  straightforward
• perl Makefile.PL make make dist
• The commands above create the compressed
  archiveIEPM-PingER-1.03.tar.gz

14
References

• Perl Module Mechanicshttp//world.std.com/swmcd/
  steven/perl/module_mechanics.html
• The Perl Module Libraryhttp//search.cpan.org/aut
  hor/JHI/perl-5.8.0/pod/perlmodlib.pod
• Perl Moduleshttp//search.cpan.org/author/JHI/per
  l-5.8.0/pod/perlmod.pod
• The Perl 5 Modules Listhttp//www.cpan.org/module
  s/00modlist.long.html
• Practical Perl Programming http//www.cs.cf.ac.uk/
  Dave/PERL/node131.html
• Perlnewmod - preparing a new module for
  distributionhttp//www.perlpod.com/5.6.1/perlnewm
  od.html