2004-04-19

Revision History
Revision 1.0	2004-04-19	OC
first official release

Abstract

This sets out the elementary steps in making a Perl module with two subroutines. Best practice suggests that common subroutines should be placed in a module rather than a library.

Table of Contents

1. Introduction

1.1. Copyright and License
1.2. Disclaimer
1.3. Credits / Contributors
1.4. Feedback
1.5. Conventions

2. First Steps

3. Editing the Module

4. Fix the Documentation

5. The End Game

5.1. Compiling
5.2. Testing
5.3. Further Reading

1. Introduction

The creation of a simple module is easy, all that needs to be done is to follow the instruction below and you will have made your first module. The example here will use two subroutines, one called 'trim' from the Perl Cookbook that trims leading and trailing spaces, the other a formatted time routine called 'yyyymm' that could come from one of the regular Date or Time modules.

2. First Steps

Change into a working directory, whatever takes your fancy for the first command that we will issue will create a directory called "Utilities".

Next, issue the following command;

      
user# h2xs -b 5.6.1 -AX Utilities

This will create a Utilities directory and a number of files;

Writing Utilities/Utilities.pm
Writing Utilities/Makefile.PL
Writing Utilities/README
Writing Utilities/t/1.t
Writing Utilities/Changes
Writing Utilities/MANIFEST

3. Editing the Module

Now change into the Utilities subdirectory and using your favorite text editor, open up the file called Utilities.pm. At this point, just have a read of the file, you may well be able to go it alone from here.

Add to the 'our EXPORT_TAGS' line so it now looks like this;

our %EXPORT_TAGS = ( 'all' => [ qw(trim yyyymm ) ] );

Then go to the '@EXPORT' line and edit it so that it reads;

our @EXPORT = qw(trim yyyymm );

Now scroll down to under the our $VERSION = '0.01'; line and add your two subroutines;

        
sub trim{
        use Carp;
        my @out=@_;
        if (!defined($out[0])){carp "Nothing has been passed to trim\n"}
        for (@out){
        s/^\s+//;
        s/\s+$//;
        }
        return wantarray ? @out : $out[0];
}

sub yyyymm{
	my @t = localtime(time);
	return (sprintf("%04d%02d", $t[5] + 1900, $t[4] + 1));
}

4. Fix the Documentation

That's it except for the documentation. So now go down to where it says; =head1 SYNOPSIS and add underneath it this or your own description.

  use Utilities;

  $yyyymm = yyyymm();# 200401   YYYYMM


  $word = trim($word);# Trims leading and trailing spaces

5. The End Game

5.1. Compiling

Now save your file and at the prompt, issue


#user perl Makefile.PL

and if all goes well you will see

Checking if your kit is complete...
Looks good
Writing Makefile for Utilities

Now issue make


#user make

Again if all goes well you will see;

cp Utilities.pm blib/lib/Utilities.pm
Manifying blib/man3/Utilities.3pm

Then issue 'make test'


user# make test

and you should see something like this;



PERL_DL_NONLAZY=1 /usr/bin/perl5.8.1 "..........'blib/arch')" t/*.t
t/1....ok
All tests successful.
Files=1, Tests=1,  1 wallclock secs ( 0.21 cusr +  0.01 csys =  0.22 CPU)

Now change to root, or super user and issue the command


root# make install

and you should see something like this;

Installing /usr/lib/perl5/site_perl/..../Utilities.pm
Installing /usr/share/man/man3/Utilities.3pm
Writing /usr/lib/perl5/site_perl/........./Utilities/.packlist
Appending installation info to /usr/lib/perl5/......./perllocal.pod

5.2. Testing

And that's it. Go back to 'user' and type perldoc Utilities It will look a bit of a mess, but now you will know how and where to tidy it up. You now might want to test the script by running this little program.

#!/usr/bin/perl

use Utilities;
use strict;
use warnings;

my $word='   blah   '; # Note the spaces befor and after the word
my $timestamp=yyyymm();
$word=trim($word);

print "$word was trimmed and the YYYYMM time is $timestamp\n";