Perl module - AbsoluteAstronomy.com

A Perl module is a discrete component of software for the Perl

Perl

Perl is a high-level, general-purpose, interpreted, dynamic programming language. Perl was originally developed by Larry Wall in 1987 as a general-purpose Unix scripting language to make report processing easier. Since then, it has undergone many changes and revisions and become widely popular...

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

Java package

A Java package is a mechanism for organizing Java classes into namespaces similar to the modules of Modula. Java packages can be stored in compressed files called JAR files, allowing classes to download faster as a group rather than one at a time...

), the Perl mechanism for defining namespaces

Namespace (computer science)

A namespace is an abstract container or environment created to hold a logical grouping of unique identifiers or symbols . An identifier defined in a namespace is associated only with that namespace. The same identifier can be independently defined in multiple namespaces...

, e.g. CGI or Net::FTP or XML::Parser; the file structure mirrors the namespace structure (e.g. the source code

Source code

In computer science, source code is text written using the format and syntax of the programming language that it is being written in. Such a language is specially designed to facilitate the work of computer programmers, who specify the actions to be performed by a computer mostly by writing source...

for Net::FTP is in Net/FTP.pm). Furthermore, a module is the Perl equivalent of the class

Class (computer science)

In object-oriented programming, a class is a construct that is used as a blueprint to create instances of itself – referred to as class instances, class objects, instance objects or simply objects. A class defines constituent members which enable these class instances to have state and behavior...

when object-oriented programming

Object-oriented programming

Object-oriented programming is a programming paradigm using "objects" – data structures consisting of data fields and methods together with their interactions – to design applications and computer programs. Programming techniques may include features such as data abstraction,...

is employed.

A collection of modules, with accompanying documentation, build scripts, and usually a test suite, compose a distribution. The Perl community has a sizable library of distributions available for search and download via CPAN

CPAN

CPAN, the Comprehensive Perl Archive Network, is an archive of nearly 100,000 modules of software written in Perl, as well as documentation for it. It has a presence on the World Wide Web at and is mirrored worldwide at more than 200 locations...

.

Perl is a language allowing many different styles of programming. You're as likely to find a module written in a procedural

Procedural

Procedural may refer to:*Procedural programming, a computer programming concept*Procedural generation, a term used in connection with computer graphics applications to indicate that data is created algorithmically rather than directly specified by an artist...

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

Mixin

In object-oriented programming languages, a mixin is a class that provides a certain functionality to be inherited or just reused by a subclass, while not meant for instantiation , Mixins are synonymous functionally with abstract base classes...

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

Scope (programming)

In computer programming, scope is an enclosing context where values and expressions are associated. Various programming languages have various types of scopes. The type of scope determines what kind of entities it can contain and how it affects them—or semantics...

in which it was loaded.

It is common for Perl modules to have embedded documentation in Perl's Plain Old Documentation

Plain Old Documentation

Plain Old Documentation, abbreviated pod, is a lightweight markup language used to document the Perl programming language.-Design:pod is designed to be a simple, clean language with just enough syntax to be useful. It purposefully does not include mechanisms for fonts, images, colors or tables...

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

Javadoc

Javadoc is a documentation generator from Sun Microsystems for generating API documentation in HTML format from Java source code.The "doc comments" format used by Javadoc is the de facto industry standard for documenting Java classes. Some IDEs, such as Netbeans and Eclipse automatically generate...

which is specialized to documenting Java

Java (programming language)

Java is a programming language originally developed by James Gosling at Sun Microsystems and released in 1995 as a core component of Sun Microsystems' Java platform. The language derives much of its syntax from C and C++ but has a simpler object model and fewer low-level facilities...

classes. By convention, module documentation typically follows the structure of a Unix man page

Manual page (Unix)

Man pages are the extensive documentation that comes preinstalled with almost all substantial Unix and Unix-like operating systems. The Unix command used to display them is man. Each page is a self-contained document.- Usage :...

.

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

Hello world program

A "Hello world" program is a computer program that outputs "Hello world" on a display device. Because it is typically one of the simplest programs possible in most programming languages, it is by tradition often used to illustrate to beginners the most basic syntax of a programming language, or to...

" 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

Java (programming language)

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";

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
----

!/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.

use Hello::World;

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

----
Hello/World.pm
----

# "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

=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;

----

Object-oriented example

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

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;

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

=cut

1;

----

Perl packages and namespaces

A running Perl program has a built-in namespace

Namespace (computer science)

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 sigil

Sigil (computer programming)

In computer programming, a sigil is a symbol attached to a variable name, showing the variable's datatype or scope. In 1999 Philip Gwyn adopted the term "to mean the funny character at the front of a Perl variable".- Historical context:...

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.

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

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

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 Hello, world

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 Hello, world

However, though technically feasible, that would be somewhat dubious programming practice. You might just as well define the sub in the calling namespace, and call it from that namespace.

Examples

Procedural example

Object-oriented example

Perl packages and namespaces

Packages and modules

Further reading