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 Fabrizio Coccetti - Stanford Linear Accelerator Center

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

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

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

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

6. 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 Fabrizio Coccetti - Stanford Linear Accelerator Center

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

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

9. 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); Fabrizio Coccetti - Stanford Linear Accelerator Center

10. Use Carp in Perl Modules use Carp;warn carp die croak • 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: Fabrizio Coccetti - Stanford Linear Accelerator Center

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

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

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

14. References • Perl Module Mechanicshttp://world.std.com/~swmcd/steven/perl/module_mechanics.html • The Perl Module Libraryhttp://search.cpan.org/author/JHI/perl-5.8.0/pod/perlmodlib.pod • Perl Moduleshttp://search.cpan.org/author/JHI/perl-5.8.0/pod/perlmod.pod • The Perl 5 Modules Listhttp://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 distributionhttp://www.perlpod.com/5.6.1/perlnewmod.html Fabrizio Coccetti - Stanford Linear Accelerator Center