PIRL:PERL Module Submission Tutorial

PIRL:PERL Module Submission Tutorial

Just a Script

Consider the following PERL script:

#! /bin/perl

my ($text) = @ARGV;
if ($#ARGV != -1){
  $text =~ s|^\s*(.*?)\s*$|$1|;
}
print "$text\n";

Subroutines

The script is a good start, but it lacks modularity. It is easier to create a module, or extend the functionality of an existing module, when given a subroutine. Here is an example of the above script taking advantage of subroutines:

#! /bin/perl

print "Trim_Text(@ARGV)\n";

sub Trim_Text {

my ($text) = @_;

if ($#_ != -1){
  $text =~ s|^\s*(.*?)\s*$|$1|;
  }
  return $text;
}

Documentation

Though functional, the code lacks good documentation. One form of module documentation is a block of comment lines (lines that start with the '#' character) that describe the purpose and use of the subroutine. The recommended documentation for a PERL module is POD, "Plain Old Documentation". Several tutorials exist on how to write POD and the format that should be employed:

At a minimum, the following documentation elements are important for each subroutine you submit:

NAME - The name of the subroutine
SYNOPSIS - A synoposis of the syntax for using the subroutine
DESCRIPTION - A description of the subroutine's purpose
PARAMETERS - An item list of each subroutine parameter and its use
RETURN - The value returned from the subroutine to the caller
AUTHOR - The author(s) of the code and affiliation
VERSION - The code version; Using CVS Revision and Date keywords is preferred.

Here is a version of Trim_Text with POD included:

#! /bin/perl
=pod 

=head1 NAME

Trim_Text

=head1 SYNOPSIS

Trim_Text ($text)

=head1 DESCRIPTION

Removes leading and trailing whitespace. It does not change the
values passed in, but returns the trimmed value.

=head1 PARAMETERS

=over 4

=item $text - Any sequence of characters.

=back

=head1 RETURN

=over 4

=item The input string without leading and trailing whitespace .

=back

=head1 AUTHOR

Drew Davidson, UA/PIRL

=head1 VERSION

1.4 2006/03/29 04:55:09

=cut

sub Trim_Text {

my ($text) = @_;

if ($#_ != -1){
  $text =~ s|^\s*(.*?)\s*$|$1|;
  }
  return $text;
}

A nice man page style formatted terminal listing of the POD can be generated using the "perldoc filename" command. Here's the POD converted to html using pod2html.

Return home