Perl module: Difference between revisions

Revision as of 14:28, 11 February 2011

Latest revision as of 09:46, 29 July 2025

(31 intermediate revisions by 24 users not shown)

Line 1:

[[File:Perl_module.png|thumb|Diagram of the mechanism of using perl modules.]]

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 [[#Perl packages and namespaces|package]] mechanism that has become universally adopted.{{discuss|Packages and modules}}

A '''Perl module''' is a discrete component of [[software]] for the [[Perl]] [[programming language]]. Technically, it is a particular set of [[Convention (norm)|conventions]] for using [[#Perl packages and namespaces|Perl's package mechanism]] that has become universally adopted.{{discuss|Packages and modules}}

A module defines its [[source code]] to be in a ''package'' (much like a [[Java package]]), the Perl mechanism for defining [[Namespace (computer science)|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 (computer science)|class]] when [[object-oriented programming]] is employed.{{discuss|Packages and modules}}

A collection of modules, with accompanying [[Software documentation|documentation]], [[Build automation|build scripts]], and usually a [[test suite]], composecomposes 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'reA developer is as likely to find a module written in a [[Procedural programming|procedural]] style (for example, [httphttps://search.cpanmetacpan.org/distmodule/Test-::Simple Test-::Simple]) as [[Object-oriented programming|object-oriented]] (e.g. [httphttps://search.cpanmetacpan.org/distmodule/XML-::Parser XML-::Parser]), both are considered equally valid according to what the module needs to do. Modules might also be used to [[mixin]] methods ([httphttps://search.cpanmetacpan.org/distmodule/DBIx-::Class DBIx-::Class]) or be a [[compiler directive|pragma]] ([http://perldoc.perl.org/strict.html 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 (programming)|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 [https://web.archive.org/web/20070316052422/http://www.oreilly.com/catalog/pperl3/colophon.html Programming Perl]. Contrast with [[javadoc]] which is specialized to documenting [[Java (programming language)|Java]] classes. By convention, module documentation typically follows the structure of a [[Manual page (Unix)|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.

Line 14 ⟶ 15:

What follows are examples of "[[Hello world program|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 (programming language)|Java]] where a class is always necessary. A real "Hello, World" function would be written like so:

<sourcesyntaxhighlight lang="perl">

sub hello { "Hello, world!\n" }

print hello();

</syntaxhighlight>

</source>

or simply printed in one line:

<sourcesyntaxhighlight lang="perl">

print "Hello, world!\n";

</syntaxhighlight>

</source>

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

----

<sourcesyntaxhighlight lang="perl">

#!/usr/bin/env perl

# Loads the module and imports any functions into our namespace

# (defaults to "main") exported by the module. Hello::World exports

Line 36 ⟶ 37:

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

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

</syntaxhighlight>

</source>

----

====''Hello/World.pm''====

<syntaxhighlight lang="perl">

----

# "package" is the namespace where the module's functionality/data resides.

<source lang="perl">

# It dictates the name of the file if you want it to be "use"d.

# "package" is the namespace where the module's functionality/data resides.

# If more than one word, it constrains the ___location of the module.

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

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;

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

# Similarly, Perl does not issue most compiler or run-time warnings by default.

use strict;

# More complicated scripts, such as most modules, will usually find them very

# helpful for debugging. The warnings pragma turns on optional warnings.

use warnings;

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

# A module's version number is stored in $ModuleName::VERSION; certain

use warnings;

# forms of the "use" built-in depend on this variable being defined.

# A module's version number is stored in $ModuleName::VERSION; certain

our $VERSION = '1.00';

# forms of the "use" built-in depend on this variable being defined.

# Inherit from the "Exporter" module which handles exporting functions.

our $VERSION = '1.00';

# Most procedural modules make use of this.

# Inherit from the "Exporter" module which handles exporting functions.

use base 'Exporter';

# Most procedural modules make use of this.

# When the module is invoked, export, by default, the function "hello" into

use base 'Exporter';

# the namespace of the using code.

# When the module is invoked, export, by default, the function "hello" into

our @EXPORT = qw(hello);

# the namespace of the using code.

# Lines starting with an equal sign indicate embedded POD

our @EXPORT = qw(hello);

# documentation. POD sections end with an =cut directive, and can

# be intermixed almost freely with normal code.

# Lines starting with an equal sign indicate embedded POD

# documentation. POD sections end with an =cut directive, and can

=head1 NAME

# be intermixed almost freely with normal code.

Hello::World - An encapsulation of a common output message

=head1 NAME

=head1 SYNOPSIS

Hello::World - An encapsulation of a common output message

use Hello::World;

=head1 SYNOPSIS

print hello();

print hello("Milky Way");

use Hello::World;

=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("Milky Way"$target);

Returns the famous greeting. If a C<$target> is given it will be used,

=head1 DESCRIPTION

otherwise "world" is the target of your greeting.

This is a procedural module which gives you the famous "Hello, world!"

=cut

message, and it’s even customizable!

# define the function hello().

=head2 Functions

sub hello {

The following functions are exported by default

my $target = shift;

$target = 'world' unless defined $target;

=head3 hello

return "Hello, print hello()$target!\n";

}

print hello($target);

=head1 AUTHOR

Returns the famous greeting. If a C<$target> is given it will be used,

otherwise "world" is the target of your greeting.

Joe Hacker <[e-mail]>

=cut

=cut

# define the function hello().

# 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

sub hello {

# any true value. A module can end with false to indicate failure but

my $target = shift;

# this is rarely used and it would instead die() (exit with an error).

$target = 'world' unless defined $target;

1;

</syntaxhighlight>

return "Hello, $target!\n";

}

=head1 AUTHOR

Joe Hacker <[e-mail]>

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

</source>

----

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

And now hereHere'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

independentindependently offrom other objects.

====''hello_world.pl''====

<syntaxhighlight lang="perl">

----

#!/usr/bin/env perl

<source lang="perl">

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

</source>

----

''use Hello/::World.pm'';

my $hello = Hello::World->new;

----

$hello->print; # prints "Hello, world!\n"

<source lang="perl">

$hello->target("Milky Way");

# In Perl there is no special 'class' definition. A namespace is a class.

$hello->print; # prints "Hello, Milky Way!\n"

package Hello::World;

my $greeting = Hello::World->new(target => "Pittsburgh");

use strict;

$greeting->print; # prints "Hello, Pittsburgh!\n"

use warnings;

$hello->print; # still prints "Hello, Milky Way!\n"

</syntaxhighlight>

====''Hello/World.pm''====

<syntaxhighlight lang="perl">

# 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 <[e-mail]>

=cut

1;

</syntaxhighlight>

</source>

----

==Perl packages and namespaces==

A running Perl program has a built-in [[Namespace (computer science)|namespace]] called "<code>main</code>", which is the default name. For example, a subroutine called <code>Sub1</code> can be called as <code>Sub1()</code> or <code>main::Sub1()</code>. With a variable the appropriate [[Sigil (computer programming)|sigil]] is placed in front of the namespace; so a scalar variable called <code>$var1</code> can also be referred to as <code>$main::var1</code>, or even <code>$::var1</code>. Other namespaces can be created at any time.

<sourcesyntaxhighlight lang="perl">

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

</syntaxhighlight>

</source>

<sourcesyntaxhighlight lang="perl">

$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

</syntaxhighlight>

</source>

Package declarations apply package scope till the next package declaration or the end of the block in which the declaration is made.

<sourcesyntaxhighlight lang="perl">

our $mainVar = 'a';

package Sp1;

Line 296 ⟶ 297:

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

</syntaxhighlight>

</source>

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

<sourcesyntaxhighlight lang="perl">

package CGI;

</syntaxhighlight>

</source>

This module, and its functionality, would commonly be invoked as follows:

<sourcesyntaxhighlight lang="perl">

use CGI (':standard'); # imports many functions, including b()

...

print b('Hello, world'); # outputs <b>Hello, world</b>

</syntaxhighlight>

</source>

A 'missing' subroutine ''could'' be added from the using program's namespace.

<sourcesyntaxhighlight lang="perl">

sub CGI::bi { # define target namespace (CGI) and sub name (bi)

return b(i($_[0]));

}

</syntaxhighlight>

</source>

and invoked as below:

<sourcesyntaxhighlight lang="perl">

print CGI::bi('Hello, world'); # outputs <b><i>Hello, world</i></b>

</syntaxhighlight>

</source>

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.

== Further reading ==

Line 345 ⟶ 346:

{{DEFAULTSORT:Perl Module}}

[[Category:Modularity]]

[[Category:Perl]]

[[es:Módulo de Perl]]

[[ru:Модули Perl]]