Perl module

<h2 id="examples">Examples</h2>
<p>What follows are examples of "<a href="/facts/Hello_world_program/vLn0jLlL">Hello, World</a>" 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 <a href="/facts/Java_(programming_language)/9ScgFyAL">Java</a> where a class is always necessary. A real "Hello, World" function would be written like so:
</p>
sub hello { "Hello, world!\n" }
print hello();

<p>or simply printed in one line:
</p>
print "Hello, world!\n";

<h3>Procedural example</h3>
<p>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.
</p>
<h4><i>hello_world.pl</i></h4>
#!/usr/bin/env 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.
use Hello::World;

print hello();             # prints "Hello, world!\n"
print hello("Milky Way");  # prints "Hello, Milky Way!\n"

<h4><i>Hello/World.pm</i></h4>
# "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.

package Hello::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.
 
use strict;
 
# 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.
 
use warnings;
 
# 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';

# 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().

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;

<p>Since Hello/World.pm is not in your @INC path, you must specify . on the command line to run the above example:
</p><p>perl -I. hello_world.pl
</p>
<h3>Object-oriented example</h3>
<p>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.
</p>
<h4><i>hello_world.pl</i></h4>
#!/usr/bin/env perl

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"

<h4><i>Hello/World.pm</i></h4>
# In Perl there is no special 'class' definition.  A namespace is a class.
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
 
# 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;

<h2 id="perl-packages-and-namespaces">Perl packages and namespaces</h2>
<p>A running Perl program has a built-in <a href="/facts/Namespace/9efXwMtV">namespace</a> called "main", which is the default name. For example, a subroutine called Sub1 can be called as Sub1() or main::Sub1(). With a variable the appropriate <a href="/facts/Sigil_(computer_programming)/dfEKbFk2">sigil</a> is placed in front of the namespace; so a scalar variable called $var1 can also be referred to as $main::var1, or even $::var1. Other namespaces can be created at any time.
</p>
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

<p>Package declarations apply package scope till the next package declaration or the end of the block in which the declaration is made.
</p>
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
# main applies again by default; all package variables still accessible as long as qualified
print "$mainVar\t$Sp1::sp1aVar$Sp2::sp2bVar\n";

<h3>Packages and modules</h3>
<p>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:
</p>
package CGI;

<p>This module, and its functionality, would commonly be invoked as follows:
</p>
use CGI (':standard'); # imports many functions, including b()
...
print b('Hello, world'); # outputs <b>Hello, world</b>

<p>A 'missing' subroutine <i>could</i> be added from the using program's namespace.
</p>
sub CGI::bi { # define target namespace (CGI) and sub name (bi)
    return b(i($_[0]));
}

<p>and invoked as below:
</p>
print CGI::bi('Hello, world'); # outputs <b><i>Hello, world</i></b>

<p>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.
</p>
<h2 id="further-reading">Further reading</h2>
<ul><li><a href="http://perldoc.perl.org/perlmod.html">Perl modules (packages and symbol tables)</a></li>
<li><a href="http://perldoc.perl.org/perlmodlib.html">Constructing new Perl modules and finding existing ones</a></li>
<li><a href="http://perldoc.perl.org/perlmodstyle.html">Perl module style guide</a></li>
<li><a href="http://perldoc.perl.org/perlnewmod.html">Preparing a new module for distribution</a></li>
<li><a href="http://www.togotutor.com/learn-perl/pm-perl.php">Perl module configuration and installation</a></li>
<li><a href="/facts/CPAN/MB7Iv662">CPAN</a></li></ul>

Perl module open-in-new

Perl module