APerl moduleis a discrete component ofsoftwarefor thePerlprogramming language.Technically, it is a particular set ofconventionsfor usingPerl's package mechanismthat has become universally adopted.[discuss]
A module defines itssource codeto be in apackage(much like aJava package), the Perl mechanism for definingnamespaces,e.g.CGIorNet::FTPorXML::Parser;the file structure mirrors thenamespacestructure (e.g. the source code forNet::FTPis inNet/FTP.pm). Furthermore, a module is the Perl equivalent of theclasswhenobject-oriented programmingis employed.[discuss]
A collection of modules, with accompanyingdocumentation,build scripts,and usually atest suite,composes adistribution.The Perl community has a sizable library of distributions available for search and download viaCPAN.
Perl is a language allowing many different styles of programming. A developer is as likely to find a module written in aproceduralstyle (for example,Test::Simple) asobject-oriented(e.g.XML::Parser), both are considered equally valid according to what the module needs to do. Modules might also be used tomixinmethods (DBIx::Class) or be apragma(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 currentscopein which it was loaded.
It is common for Perl modules to have embedded documentation in Perl'sPlain Old Documentationformat. POD imposes little structure on the author. It is flexible enough to be used to write articles, web pages and even entire books such asProgramming Perl.Contrast withjavadocwhich is specialized to documentingJavaclasses. By convention, module documentation typically follows the structure of aUnix 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
editWhat 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 withJavawhere a class is always necessary. A real "Hello, World" function would be written like so:
subhello{"Hello, world!\n"}
printhello();
or simply printed in one line:
print"Hello, world!\n";
Procedural example
editHere 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
edit#!/usr/bin/perl
# 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.
useHello::World;
printhello();# prints "Hello, world!\n"
printhello("Milky Way");# prints "Hello, Milky Way!\n"
Hello/World.pm
edit# "package" is the namespace where the module's functionality/data resides.
# It dictates the name of the file if you want it to be "use" d.
# If more than one word, it constrains the location of the module.
packageHello::World;
# By default Perl allows you to use variables without declaring
# them. This may be convenient for short scripts and one-liners.
# But in a longer unit of code such as a module it is wise to declare
# your variables both to catch typos and to constrain their
# accessibility appropriately from outside the module. The strict pragma
# forces you to declare your variables.
usestrict;
# Similarly, Perl does not issue most compiler or run-time warnings by default.
# More complicated scripts, such as most modules, will usually find them very
# helpful for debugging. The warnings pragma turns on optional warnings.
usewarnings;
# 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.
usebase'Exporter';
# When the module is invoked, export, by default, the function "hello" into
# the namespace of the using code.
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 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
# define the function hello().
subhello{
my$target=shift;
$target='world'unlessdefined$target;
return"Hello, $target!\n";
}
=head1 AUTHOR
Joe Hacker <[email protected]>
=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;
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
editHere'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
edit#!/usr/bin/perl
useHello::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
edit# In Perl there is no special 'class' definition. A namespace is a class.
packageHello::World;
usestrict;
usewarnings;
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
# 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.
subnew{
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
subtarget{
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
subto_string{
my$self=shift;
return"Hello, $self->{target}!";
}
=head3 print
$hello->print;
Outputs the greeting to STDOUT
=cut
subprint{
my$self=shift;
print$self->to_string(),"\n";
}
=head1 AUTHOR
Joe Hacker <[email protected]>
=cut
1;
Perl packages and namespaces
editA running Perl program has a built-innamespacecalled "main",which is the default name. For example, a subroutine calledSub1can be called asSub1()ormain::Sub1().With a variable the appropriatesigilis placed in front of the namespace; so a scalar variable called$var1can also be referred to as$main::var1,or even$::var1.Other namespaces can be created at any time.
packageNamespace1;
$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';
packageSp1;
our$sp1aVar='aa';
print"$main::mainVar\t$sp1aVar\n";# note mainVar needs qualifying
packageSp2;
our$sp2aVar='aaa';
print"$main::mainVar\t$Sp1::sp1aVar\t$sp2aVar\n";# note mainVar and sp1aVar need qualifying
packagemain;
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
packageSp1;
our$sp1bVar='bb';
print"$main::mainVar\t$sp1aVar\t$sp1bVar\n";# note mainVar needs qualifying
{
packageSp2;
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
# main applies again by default; all package variables still accessible as long as qualified
print"$mainVar\t$Sp1::sp1aVar$Sp2::sp2bVar\n";
Packages and modules
editConventionally, 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:
packageCGI;
This module, and its functionality, would commonly be invoked as follows:
useCGI(':standard');# imports many functions, including b()
...
printb('Hello, world');# outputs <b>Hello, world</b>
A 'missing' subroutinecouldbe added from the using program's namespace.
subCGI::bi {# define target namespace (CGI) and sub name (bi)
returnb(i($_[0]));
}
and invoked as below:
printCGI::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.