How to write Perl Modules - SLAC

whooploafSoftware and s/w Development

Dec 13, 2013 (3 years and 10 months ago)

91 views

March 21, 2003

Fabrizio Coccetti
-

Stanford Linear Accelerator Center

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

March 21, 2003

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

March 21, 2003

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


March 21, 2003

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 !!

March 21, 2003

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


March 21, 2003

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

March 21, 2003

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)

March 21, 2003

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__


March 21, 2003

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

March 21, 2003

Fabrizio Coccetti
-

Stanford Linear Accelerator Center

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.

use Carp;

warn




carp

die




croak


Recipe:

March 21, 2003

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';

March 21, 2003

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

March 21, 2003

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

March 21, 2003

Fabrizio Coccetti
-

Stanford Linear Accelerator Center

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