Perl module

A Perl module is a discrete component of software for the Perl programming language. Technically, it is a particular set of conventions for using Perl's package mechanism that has become universally adopted.
A module defines its source code to be in a "package" (much like a Java package), the Perl mechanism for defining namespaces, e.g. "CGI" or "Net::FTP" or "XML::Parser"; the file structure mirrors the namespace structure (e.g. the source code for "Net::FTP" is in "Net/FTP.pm"). Furthermore, a module is the Perl equivalent of the class when object-oriented programming is employed.
A collection of modules, with accompanying documentation, build scripts, and usually a test suite, composes 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. A developer is as likely to find a module written in a procedural style (for example, Test::Simple) as object-oriented (e.g. 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 language. 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 occasions 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.
Examples.
What follows are 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:
print hello();
or simply printed in one line:
print "Hello, world!\n";
Procedural example.
Here is "Hello, World" implemented as a procedural module with a customizable target for the greeting, just to make things interesting. Also included is a short script to illustrate the module's use.
"hello_world.pl".
use Hello::World;
print hello(); # prints "Hello, world!\n"
print hello("Milky Way"); # prints "Hello, Milky Way!\n"
"Hello/World.pm".
package Hello::World;
use strict;
use warnings;
our $VERSION = '1.00';
use base 'Exporter';
our @EXPORT = qw(hello);
=head1 NAME
Hello::World - An encapsulation of a common 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 it’s 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
sub hello {
 my $target = shift;
 $target = 'world' unless defined $target;
 return "Hello, $target!\n";
=head1 AUTHOR
Joe Hacker <joe@joehacker.org>
=cut
1;
Since Hello/World.pm is not in your @INC path, you must specify . on the command line to run the above example:
perl -I. hello_world.pl
Object-oriented example.
Here's an example of the same thing done in an object-oriented
style. The advantage of an OO module is that each object can be configured
independently from other objects.
"hello_world.pl".
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".
package Hello::World;
use strict;
use warnings;
our $VERSION = "1.00";
=head1 NAME
Hello::World - An encapsulation of a common 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
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;
Perl packages and namespaces.
A running Perl program has a built-in namespace called "codice_1", which is the default name. For example, a subroutine called codice_2 can be called as codice_3 or codice_4. With a variable the appropriate sigil is placed in front of the namespace; so a scalar variable called codice_5 can also be referred to as codice_6, or even codice_7. Other namespaces can be created at any time.
package Namespace1;
$var1 = 1; # created in namespace Namespace1, which is also created if not pre-existing
our $var2 = 2; # also created in that namespace; our required if use strict is applied
my $var3 = 3; # lexically-scoped my-declared - NOT in any namespace, not even main
$Namespace2::var1 = 10; # created in namespace Namespace2, also created if not pre-existing
our $Namespace2::var2 = 20; # also created in that namespace
my $Namespace2::var3 = 30;#compilation error:my-declared variables CAN'T belong to a package
Package declarations apply package scope till the next package declaration or the end of the block in which the declaration is made.
our $mainVar = 'a';
package Sp1;
our $sp1aVar = 'aa';
print "$main::mainVar\t$sp1aVar\n"; # note mainVar needs qualifying
package Sp2;
our $sp2aVar = 'aaa';
print "$main::mainVar\t$Sp1::sp1aVar\t$sp2aVar\n";# note mainVar and sp1aVar need qualifying
package main;
print "$mainVar\t$Sp1::sp1aVar\t$Sp2::sp2aVar\n"; # note sp1aVar and sp2aVar need qualifying
$mainVar = 'b';
 # NOTE previously created packages and package variables still accessible
 package Sp1;
 our $sp1bVar = 'bb';
 print "$main::mainVar\t$sp1aVar\t$sp1bVar\n"; # note mainVar needs qualifying
 package Sp2;
 our $sp2bVar = 'bbb';
 print "$main::mainVar\t$Sp1::sp1aVar$Sp1::sp1bVar\t$sp2aVar$sp2bVar\n";
 } # note mainVar and sp1...Var need qualifying
 print "$main::mainVar\t$sp1bVar$sp1aVar\t$Sp2::sp2bVar$Sp2::sp2aVar\n";
} # note package Sp1 applies by default
print "$mainVar\t$Sp1::sp1aVar$Sp2::sp2bVar\n";
Packages and modules.
Conventionally, namespaces are associated with modules; in practice, there is usually one namespace per module and vice versa, but that's not mandated by the language. For example, the 'standard' module CGI.pm has the following declaration at its top:
package CGI;
This module, and its functionality, would commonly be invoked as follows:
use CGI (':standard'); # imports many functions, including b()
print b('Hello, world'); # outputs <b>Hello, world</b>
A 'missing' subroutine "could" be added from the using program's namespace.
sub CGI::bi { # define target namespace (CGI) and sub name (bi)
 return b(i($_[0]));
and invoked as below:
print CGI::bi('Hello, world'); # outputs <b><i>Hello, world</i></b>
However, though technically feasible, that would be dubious programming practice. You might just as well define the sub in the calling namespace, and call it from that namespace.