A Perl module is a discrete component of software for the Perl programming language. A module is distinguished by a unique namespace, e.g. "CGI" or "Net::FTP" or "XML::Parser" and a filename similarly named (ie. Net::FTP lives in Net/FTP.pm). A collection of one or more modules, with accompanying documentation and build scripts, compose a distribution. The Perl community has a sizable library of distributions available for search and download via CPAN.
Perl is a language allowing many different styles of programming. You're as likely to find a module written in a procedural style (for example, Test-Simple) as object-oriented (ex. XML-Parser), both are considered equally valid according to what the module needs to do. Modules might also be used to mixin methods (DBIx-Class) or be a pragma (strict.pm) which has an effect immediately upon being loaded. Modules can even be used to alter the syntax of the langauge. The effect of Perl modules are usually limited to the current scope in which it was loaded.
It is common for Perl modules to have embedded documentation in Perl's Plain Old Documentation format. POD imposes little structure on the author. It is flexible enough to be used to write articles, web pages and even entire books such as Programming Perl. Contrast with javadoc which is specialized to documenting Java classes. By convention, module documentation typically follows the structure of a Unix man page.
The language of Perl is defined by the single implementation (referred to as "perl") and is added to (and in rare occassions taken away from) each new release. For this reason it is important for a module author to be aware what features they're making use of and what the minimum required version of perl is. The code on this page requires perl 5.6.0 which is considered rather old by now.
What follows is examples of "Hello, World" implemented in different styles of modules. It must be understood that a module is not necessary in Perl, functions and code can be defined and used anywhere, this is just for example purposes. Contrast with Java where a class is always necessary. A real "Hello, World" function would be written like so:
sub hello { "Hello, world!\n" }
print hello();
or simply printed in one line.
print "Hello, world!\n";
Here is "Hello, World" implemented as a procedural module with a customizable target for the greeting, just to make things interesting.
hello_world.pl
#!/usr/bin/perl -w
# Loads the module and imports any functions into our namespace
# (defaults to "main") exported by the module. Hello::World exports
# hello() by default. Exports can usually be controlled by the caller.
use Hello::World;
print hello(); # prints "Hello, world!\n"
print hello("Milky Way"); # prints "Hello, Milky Way\n"
Hello/World.pm
# "package" gives the namespace the module will reside in and also
# dictates the name of the file if you want it to be "use"d.
package Hello::World;
# A module's version number is stored in $ModuleName::VERSION; certain
# forms of the "use" built-in depend on this variable being defined.
our $VERSION = '1.00';
# Inherit from the "Exporter" module which handles exporting functions.
# Most procedural modules make use of this.
use base 'Exporter';
# Export, by default, the function "hello" into the namespace of
# any code which uses this module.
our @EXPORT = qw(hello);
# Lines starting with an equal sign indicate embedded POD
# documentation. POD sections end with an =cut directive, and can
# be intermixed almost freely with normal code.
=head1 NAME
Hello::World - An encapsulation of a commonly output message
=head1 SYNOPSIS
use Hello::World;
print hello();
print hello("Milky Way");
=head1 DESCRIPTION
This is a procedural module which gives you the famous "Hello, world!"
message, and its even customizable!
=head2 Functions
The following functions are exported by default
=head3 hello
print hello();
print hello($target);
Returns the famous greeting. If a C<$target> is given it will be used,
otherwise "world" is the target of your greeting.
=cut
# define the function hello().
sub hello {
my $target = shift;
$target = 'world' unless defined $target;
return "Hello, $target!\n";
}
=head1 AUTHOR
Joe Hacker <joe@joehacker.org>
=cut
# A Perl module must end with a true value or else it is considered not to
# have loaded. By convention this value is usually 1 though it can be
# any true value. A module can end with false to indicate failure but
# this is rarely used and it would instead die() (exit with an error).
1;
And now here's an example of the same thing done in an object oriented
style. The advantage of an OO module is each object can be configured
independent of other objects.
hello_world.pl
#!/usr/bin/perl -w
use Hello::World;
my $hello = Hello::World->new;
$hello->print; # prints "Hello, world!\n"
$hello->target("Milky Way");
$hello->print; # prints "Hello, Milky Way!\n"
my $greeting = Hello::World->new(target => "Pittsburgh");
$greeting->print; # prints "Hello, Pittsburgh!\n"
$hello->print; # still prints "Hello, Milky Way!\n"
Hello/World.pm
# In Perl there is no special 'class' definition. A namespace is a class.
package Hello::World;
our $VERSION = "1.00";
=head1 NAME
Hello::World - An encapsulation of a commonly output message
=head1 SYNOPSIS
use Hello::World;
my $hello = Hello::World->new();
$hello->print;
=head1 DESCRIPTION
This is an object-oriented library which can print the famous "H.W."
message.
=head2 Methods
=head3 new
my $hello = Hello::World->new();
my $hello = Hello::World->new( target => $target );
Instantiates an object which holds a greeting message. If a C<$target> is
given it is passed to C<< $hello->target >>.
=cut
# The constructor of an object is called new() by convention. Any
# method may construct an object and you can have as many as you like.
sub new {
my($class, %args) = @_;
my $self = bless({}, $class);
my $target = exists $args{target} ? $args{target} : "world";
$self->target($target);
return $self;
}
=head3 target
my $target = $hello->target;
$hello->target($target);
Gets and sets the current target of our message.
=cut
sub target {
my $self = shift;
if( @_ ) {
my $target = shift;
$self->{target} = $target;
}
return $self->{target};
}
=head3 to_string
my $greeting = $hello->to_string;
Returns the $greeting as a string
=cut
sub to_string {
my $self = shift;
return "Hello, $self->{target}!";
}
=head3 print
$hello->print;
Outputs the greeting to STDOUT
=cut
sub print {
my $self = shift;
print $self->to_string(), "\n";
}
=head1 AUTHOR
Joe Hacker <joe@joehacker.org>
=cut
1;