Skip to content
LumenaryAcademy
Professional 65 min

Modules, CPAN and objects

Packages and modules, installing from CPAN with cpanm, and object-oriented Perl from bless to Moo and the new class syntax.

Code tested · 2AI-draftedAwaiting review by a computer scientist
MotivationH

From scripts to software

A 50-line script can live in one file. A 5,000-line application cannot, and neither can code you want to share between scripts, test on its own, or give to the rest of the world. Every language needs a way to split code into named, reusable units and a way to share those units. Perl's are packages and modules, and its sharing system is CPAN, one of the oldest and largest language package archives.

Large programs also need a way to bundle data with the operations that make sense on it, so that a sensor knows how to describe its readings and a bank account refuses a negative deposit. That is object-oriented programming. Perl's approach to objects is famously minimal: an object is just a reference that knows which package its methods live in. That minimalism made Perl flexible and produced a whole ecosystem of object systems on CPAN, of which Moo and Moose are the ones you will meet most. Since Perl 5.38 the language also has a built-in class syntax.

This lesson takes you through all of it, because real Perl code bases contain all of it: modules with Exporter, classes built by hand with bless, newer classes built with Moo, and a growing amount of code using class.

Worked examplesH

Packages and modules

Definition— Package

A namespace for global names, declared with package NAME; or package NAME { ... }. Subroutines and our variables belong to the current package, and can be reached from anywhere by their fully qualified name, such as Text::Tally::word_counts or $Greeting::Default. Code outside any package declaration is in package main. The double colons are only a naming convention: Text::Tally is not "inside" Text.

Definition— Module

A file, ending in .pm, that holds a package of the same name: Text::Tally lives in Text/Tally.pm. use Text::Tally qw(a b); finds that file by searching the directories in the array @INC, loads it once, and calls the package's import method with the list qw(a b), all at compile time. A module must end with a true value, by convention 1;.

The program below writes a small module into a temporary directory, exactly as it would sit under a project's lib/ folder, then loads and uses it. It does by hand, at run time, what use lib 'lib'; use Text::Tally qw(word_counts top_words); does at compile time:

perl
use strict;
use warnings;
use feature qw(say);
use File::Temp qw(tempdir);
use File::Path qw(make_path);

# Write a small module to a temporary library directory, as it would sit in lib/.
my $lib = tempdir(CLEANUP => 1);
make_path("$lib/Text");
open my $fh, '>', "$lib/Text/Tally.pm" or die "Cannot write module: $!";
print {$fh} <<'PM';
package Text::Tally;
use strict;
use warnings;
use Exporter 'import';
our @EXPORT_OK = qw(word_counts top_words);
our $VERSION   = '0.01';

sub word_counts {
    my ($text) = @_;
    my %count;
    $count{ lc $1 }++ while $text =~ /(\w+)/g;
    return \%count;
}

sub top_words {
    my ($counts, $n) = @_;
    my @sorted = sort { $counts->{$b} <=> $counts->{$a} or $a cmp $b } keys %$counts;
    return @sorted[0 .. ($n < @sorted ? $n : @sorted) - 1];
}

1;   # a module must end with a true value
PM
close $fh;

# What 'use lib' and 'use Text::Tally qw(...)' would do, done at run time here.
unshift @INC, $lib;
require Text::Tally;
Text::Tally->import(qw(word_counts top_words));

my $counts = word_counts("The rain in Spain falls mainly on the plain. The end.");
say "top 3: ", join(', ', top_words($counts, 3));
say "Text::Tally version $Text::Tally::VERSION, loaded from ", $INC{'Text/Tally.pm'} =~ s/^\Q$lib\E/LIB/r;
say "fully qualified call: ", Text::Tally::word_counts("a b a")->{a};

# Packages give names a namespace even inside one file.
package Greeting {
    our $Default = 'Hello';
    sub hello { my ($name) = @_; return "$Default, $name" }
}
say Greeting::hello('Yusuf');
$Greeting::Default = 'Salaam';
say Greeting::hello('Yusuf');
say "current package: ", __PACKAGE__;

It printed:

text
top 3: the, end, falls
Text::Tally version 0.01, loaded from LIB/Text/Tally.pm
fully qualified call: 2
Hello, Yusuf
Salaam, Yusuf
current package: main

How the pieces fit:

  • <<'PM' is a here-document with a quoted terminator, so nothing inside it is interpolated: the module's source is written out exactly as typed.
  • Exporter. use Exporter 'import'; gives the package the standard import method. Names in @EXPORT_OK are exported only when the caller asks for them, which is the polite default: @EXPORT (export without asking) clutters the caller's namespace and is discouraged for new modules.
  • $VERSION is how tools and other modules check which version is installed; use Text::Tally 0.02; would die if the installed one were older.
  • %INC records every module loaded and the file it came from, which is how require knows not to load a module twice, and how you find out which copy of a module your program actually used.
  • use is require plus import, at compile time. use Foo qw(x); is exactly BEGIN { require Foo; Foo->import(qw(x)); }. That is why a use statement takes effect even if it appears below the code that relies on it.
  • package NAME { ... } (Perl 5.14) limits the package to a block. our $Default creates a package variable visible from outside as $Greeting::Default. Prefer lexical my variables and subroutines to share state; package variables are global and should be rare.

In a real project the layout is lib/Text/Tally.pm for modules, bin/ or script/ for programs, t/ for tests, and the program starts with use FindBin; use lib "$FindBin::Bin/../lib"; or is run as perl -Ilib bin/tool.pl.

ExplanationH

CPAN, cpanm and dependencies

The Comprehensive Perl Archive Network has collected Perl modules since 1995. You browse and search it at metacpan.org, where every module's documentation, source, issues, test reports and reverse dependencies are a click away.

Installing. Perl ships with a client called cpan, but most Perl programmers use cpanm (App::cpanminus), which is smaller, quieter and needs no configuration:

bash
cpanm Path::Tiny                    # install a module (and what it needs)
cpanm -L local Text::CSV            # install into ./local instead of the system
cpanm --installdeps .               # install everything this project's cpanfile lists
perl -MPath::Tiny -e 1              # check that it loads
perldoc Path::Tiny                  # read its documentation

On a server, do not install modules into the system Perl with sudo: the operating system's own packages depend on it. Use a Perl of your own (perlbrew or plenv), a container, or the local::lib convention, which puts modules under your home directory.

Pinning dependencies. A project lists what it needs in a file called cpanfile:

perl
requires 'Moo', '2.005';
requires 'Text::CSV';
requires 'Path::Tiny', '0.144';

on test => sub {
    requires 'Test2::V0';
};

Carton reads it, installs everything into ./local, and writes cpanfile.snapshot with the exact versions it chose. Commit both files; on another machine, carton install --deployment reproduces the same set, and carton exec perl bin/tool.pl runs with it. It plays the same role as a lock file in other ecosystems.

Choosing a module. For most tasks CPAN offers several modules, some abandoned. Before depending on one, look on MetaCPAN at the date of the latest release, the test results from CPAN Testers (volunteers who test every upload on many platforms and Perl versions), the number of other distributions that depend on it, and its open issues. Community-curated lists such as Task::Kensho suggest well-regarded choices for common jobs: Path::Tiny for files, Text::CSV for CSV, DateTime or Time::Moment for dates, Mojolicious or Dancer2 for web applications, DBI with DBD::Pg or DBD::SQLite for databases.

Worked examplesH

Objects with bless

Perl's object model needs only three ideas:

Definition— Perl's object model

A class is a package. An object is a reference, usually to a hash, that has been blessed into a package with bless $ref, $class. A method is an ordinary subroutine in that package, called with the arrow, $object->method(ARGS), which passes the object itself as the first argument (by convention named $self). Calling Class->method(ARGS) passes the class name as the first argument instead, which is how constructors such as new work.

When you call a method that the object's own package does not define, Perl searches its parent classes, listed in the package's @ISA array (normally set with use parent). That is inheritance.

perl
use strict;
use warnings;
use feature qw(say);

package Sensor {
    use Carp qw(croak);
    my $count = 0;                                   # class data, private to this block

    sub new {
        my ($class, %args) = @_;
        croak "name is required" unless defined $args{name};
        my $self = { name => $args{name}, readings => [] };
        $count++;
        return bless $self, $class;                  # bless: this hash is now an object of $class
    }
    sub name     { $_[0]{name} }                     # read-only accessor
    sub unit     { '' }                              # subclasses override this
    sub count    { $count }                          # a class method
    sub add {
        my ($self, @values) = @_;
        push @{ $self->{readings} }, @values;
        return $self;                                # returning $self allows chaining
    }
    sub average {
        my ($self) = @_;
        my @r = @{ $self->{readings} } or return;    # empty list: no average
        my $sum = 0;
        $sum += $_ for @r;
        return $sum / @r;
    }
    sub describe {
        my ($self) = @_;
        my $avg = $self->average;
        return sprintf "%s: %s", $self->name,
            defined $avg ? sprintf("%.1f%s", $avg, $self->unit) : 'no data';
    }
}

package Thermometer {
    use parent -norequire, 'Sensor';                # inherit from Sensor
    sub unit { ' C' }
    sub describe {
        my ($self) = @_;
        my $text = $self->SUPER::describe();         # extend the parent's method
        my $avg  = $self->average;
        $text .= ' (frost risk)' if defined $avg && $avg < 3;
        return $text;
    }
}

package RainGauge {
    use parent -norequire, 'Sensor';
    sub unit { ' mm' }
}

package main;

my @sensors = (
    Thermometer->new(name => 'Ushuaia')->add(1, 4, 2),
    Thermometer->new(name => 'Luanda')->add(27, 29),
    RainGauge->new(name => 'Cherrapunji')->add(120, 85, 240),
    RainGauge->new(name => 'Atacama'),
);
say $_->describe for @sensors;                       # one call, the right method for each

say "sensors created: ", Sensor->count;
my $t = $sensors[0];
say "ref: ", ref $t, "; isa Sensor: ", ($t->isa('Sensor') ? 'yes' : 'no'),
    "; can add: ", ($t->can('add') ? 'yes' : 'no'), "; can fly: ", ($t->can('fly') ? 'yes' : 'no');

my $ok = eval { Sensor->new(unit => 'x'); 1 };
say "error: ", $@ =~ s/ at .*//sr unless $ok;
say "underneath: ", join ',', sort keys %$t;         # still a hash: Perl trusts you not to poke inside

It printed:

text
Ushuaia: 2.3 C (frost risk)
Luanda: 28.0 C
Cherrapunji: 148.3 mm
Atacama: no data
sensors created: 4
ref: Thermometer; isa Sensor: yes; can add: yes; can fly: no
error: name is required
underneath: name,readings

What each part does

  • The constructor. Thermometer->new(name => 'Ushuaia') finds no new in Thermometer, so Perl looks in its parent, Sensor, and calls Sensor::new('Thermometer', name => 'Ushuaia'). Because new blesses into $class, which is 'Thermometer', the object belongs to the subclass. Always bless into the $class you were given, never a hard-coded name, or inheritance breaks.
  • Validation with croak. Carp's croak dies with the line number of the caller, which is where the mistake was made.
  • Accessors. sub name { $_[0]{name} } returns a field. Code outside the class should call $obj->name, not reach into $obj->{name}: the hash is an implementation detail, and the last line shows that Perl will not stop you from looking. Discipline, not the language, keeps it private.
  • Polymorphism. The loop calls describe on each sensor without knowing its class. Each object finds its own unit, and the Thermometer finds its own describe, which extends the parent's through SUPER::describe.
  • Chaining. add returns $self, so construction and filling fit on one line.
  • my @r = ... or return; A list assignment in a boolean context counts the elements on its right, so the method returns early, with an empty list, when there are no readings.
  • Introspection. ref $obj gives the class name, $obj->isa('Sensor') asks about inheritance, and $obj->can('add') returns a reference to the method if one exists. blessed from Scalar::Util tells you whether a value is an object at all.
  • use parent -norequire sets up inheritance for a parent defined in the same file; for a parent in its own module, write use parent 'Sensor'; and it loads it for you.

If a class defines a method called DESTROY, Perl calls it when the object's last reference disappears; with reference counting this happens at a predictable moment, so DESTROY is a reasonable place to release a lock or close a connection.

Misconception

"new Sensor(name => 'Lima') is just another way to write Sensor->new(name => 'Lima')." You will see this indirect object syntax in old code and in documentation copied from C++ or Java habits, and it usually works. But Perl has to guess what it means, and the guess changes depending on which subroutines happen to be defined in the current package: if your package has its own subroutine called new, the line calls that instead. Always use the arrow. Perl 5.36's use v5.36 turns the indirect syntax off entirely, so that any such guess becomes a compile-time error.

Classes can also customise operators with the core overload pragma: use overload '""' => sub { $_[0]->describe }; makes an object print as its description when interpolated into a string, and '==', '+' or '<=>' can be given meanings for, say, a money or vector class. Use it where the meaning is obvious to a reader; an overloaded + that does something surprising is worse than a method with a clear name.

ExplanationH

Moo, Moose and the class feature

Writing constructors and accessors by hand gets repetitive. Since the late 2000s most Perl teams have used an object system from CPAN instead. Moose is the full-featured one, with types, roles (reusable bundles of methods) and a meta-object protocol. Moo offers most of what people use from Moose, starts much faster, and has no non-Perl dependencies. The Sensor class in Moo looks like this (a fragment, since Moo is not a core module):

perl
package Sensor;
use Moo;

has name     => (is => 'ro', required => 1);
has readings => (is => 'ro', default => sub { [] });

sub add {
    my ($self, @values) = @_;
    push $self->readings->@*, @values;
    return $self;
}

package Thermometer;
use Moo;
extends 'Sensor';

has declares an attribute and generates its accessor; is => 'ro' makes it read-only; required makes the constructor die if it is missing, with a message such as Missing required arguments: name; extends sets the parent. The constructor is written for you.

Perl 5.38 added a built-in, still experimental, class syntax that brings these ideas into the language itself. Real encapsulation arrives with it: fields are true private variables, not hash entries. On Perl 5.38 or newer, the same classes look like this (also a fragment, since the Perl 5.34 that checks this course does not have the feature):

perl
use v5.38;
use feature 'class';
no warnings 'experimental::class';

class Sensor {
    field $name :param;          # filled from new(name => ...)
    field @readings;             # private: no outside code can touch it

    method name { $name }
    method add (@values) { push @readings, @values; return $self }
    method average {
        return unless @readings;
        my $sum = 0;
        $sum += $_ for @readings;
        return $sum / @readings;
    }
}

class Thermometer :isa(Sensor) {
    method unit { ' C' }
}

Methods get $self automatically and take signatures; :param connects a field to a constructor argument; :isa(...) declares the parent. Later releases extended it, for example with a :reader attribute (Perl 5.40) that generates an accessor for a field. Because the feature is still marked experimental, check perlclass for your version before relying on it in production. For code that must run on the Perls that servers have today, Moo is the safe, common choice; for code you only read, all three styles will keep appearing for many years.

Misconception

"Perl objects are just hashes, so object-oriented Perl is not real OO." Blessed hashes are a deliberately small mechanism, and you have just seen that they support constructors, encapsulation by convention, inheritance, method overriding, polymorphism and introspection. What Perl leaves out is enforcement: it trusts you not to reach into an object's hash. Moo and Moose add declarative structure on top, and the class feature adds true private fields. Choose the level of rigour your project needs.

Exercises

Exercises

1. Modules, CPAN and objects

Warm-upHuman

use Data::Report; searches each directory in @INC for a file. What is that file's path relative to the directory? (For example, Text::Tally is Text/Tally.pm.)

2. Modules, CPAN and objects

CoreHuman

Which is exactly equivalent to use Text::Tally qw(word_counts);?

Choose one

3. Modules, CPAN and objects

CoreComputational

What does this program print? It prints two lines; type them separated by a single space.

use strict;
use warnings;
use feature qw(say);

package Instrument {
    sub new   { my ($class, %args) = @_; return bless {%args}, $class }
    sub sound { 'a note' }
    sub play  { my ($self) = @_; return "$self->{name} plays " . $self->sound }
}
package Drum {
    use parent -norequire, 'Instrument';
    sub sound { 'boom' }
}
package main;
say Drum->new(name => 'Kofi')->play;
say Instrument->new(name => 'Mei')->play;

4. Modules, CPAN and objects

CoreComputational

What does this program print?

use strict;
use warnings;
use feature qw(say);
my $obj = bless [], 'Queue';
say ref($obj), ' ', ($obj->isa('Queue') ? 1 : 0), ' ', ref([]);

5. Modules, CPAN and objects

StretchComputational

What does this program print?

use strict;
use warnings;
use feature qw(say);

package Base { sub new { return bless {}, shift } sub hello { 'base' } }
package Mid  { use parent -norequire, 'Base'; sub hello { my ($s) = @_; return 'mid+' . $s->SUPER::hello() } }
package Top  { use parent -norequire, 'Mid';  sub hello { my ($s) = @_; return 'top+' . $s->SUPER::hello() } }
package main;
say Top->new->hello;

6. Modules, CPAN and objects

StretchComputational

What number does this program print?

use strict;
use warnings;
use feature qw(say);

package Ticket {
    my $issued = 0;
    sub new    { my ($class) = @_; $issued++; return bless { number => $issued }, $class }
    sub issued { $issued }
    sub number { $_[0]{number} }
}
package VipTicket { use parent -norequire, 'Ticket' }
package main;
my @t = map { Ticket->new } 1 .. 2;
my @v = map { VipTicket->new } 1 .. 3;
say Ticket->issued + $v[-1]->number;

7. Modules, CPAN and objects

CoreHuman

A team is starting a Perl service that uses several CPAN modules. Which practices are sound? Choose all that apply.

Choose all that apply

Further reading and resources

  • perlmodPackages, symbol tables, BEGIN blocks and how modules work.
  • perlootutThe official object-oriented programming tutorial, which also surveys the OO systems on CPAN.
  • perlobjThe reference for Perl's built-in object model: bless, method resolution, SUPER, DESTROY.
  • perlclassThe class, field and method syntax added experimentally in Perl 5.38.
  • App::cpanminuscpanm, the small, popular command-line client for installing CPAN modules.
  • CartonPer-project dependency management with a cpanfile and a snapshot of exact versions.
  • MooA light, fast object system widely used in modern Perl code.