Perl Modules

Slide 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 Fabrizio Coccetti - Stanford Linear Accelerator Center 1 March 21, 2003

Slide 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 Fabrizio Coccetti - Stanford Linear Accelerator Center 2 March 21, 2003

Slide 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  Fabrizio Coccetti - Stanford Linear Accelerator Center 3 March 21, 2003

Slide 4: 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 !! Fabrizio Coccetti - Stanford Linear Accelerator Center 4 March 21, 2003

Slide 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. IEPM::PingER Fabrizio Coccetti - Stanford Linear Accelerator Center 5 March 21, 2003

Slide 6: Let’s 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  Fabrizio Coccetti - Stanford Linear Accelerator Center 6 March 21, 2003

Slide 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)  Fabrizio Coccetti - Stanford Linear Accelerator Center 7 March 21, 2003

Slide 8: 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__ Fabrizio Coccetti - Stanford Linear Accelerator Center 8 March 21, 2003

Slide 9: 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) Fabrizio Coccetti - Stanford Linear Accelerator Center 9 March 21, 2003

Slide 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: use Carp; warn carp die croak Fabrizio Coccetti - Stanford Linear Accelerator Center 10 March 21, 2003

Slide 11: 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'; Fabrizio Coccetti - Stanford Linear Accelerator Center 11 March 21, 2003

Slide 12: 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); Fabrizio Coccetti - Stanford Linear Accelerator Center 12 March 21, 2003

Slide 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 archive: IEPM-PingER-1.03.tar.gz Fabrizio Coccetti - Stanford Linear Accelerator Center 13 March 21, 2003

Slide 14: 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 Fabrizio Coccetti - Stanford Linear Accelerator Center 14 March 21, 2003