1. March 21, 2003 Fabrizio Coccetti - Stanford Linear Accelerator Center1 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. March 21, 2003 Fabrizio Coccetti - Stanford Linear Accelerator Center2Agenda 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. March 21, 2003 Fabrizio Coccetti - Stanford Linear Accelerator Center3 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. March 21, 2003 Fabrizio Coccetti - Stanford Linear Accelerator Center4 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 !!

5. March 21, 2003 Fabrizio Coccetti - Stanford Linear Accelerator Center5 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

6. March 21, 2003 Fabrizio Coccetti - Stanford Linear Accelerator Center6 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

7. March 21, 2003 Fabrizio Coccetti - Stanford Linear Accelerator Center7 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. March 21, 2003 Fabrizio Coccetti - Stanford Linear Accelerator Center8 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__

9. March 21, 2003 Fabrizio Coccetti - Stanford Linear Accelerator Center9 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);

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

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

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

13. March 21, 2003 Fabrizio Coccetti - Stanford Linear Accelerator Center13 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

14. March 21, 2003 Fabrizio Coccetti - Stanford Linear Accelerator Center14References Perl Module Mechanics http://world.std.com/~swmcd/steven/perl/module_mechanics.html 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 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 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 http://www.cpan.org/modules/00modlist.long.html Practical Perl Programming http://www.cs.cf.ac.uk/Dave/PERL/node131.html 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 http://www.perlpod.com/5.6.1/perlnewmod.html