Perl Modules Guide — Creating, Exporting, and Using CPAN Modules

In this tutorial, you will learn about Perl Modules Guide. We cover key concepts, practical examples, and best practices to help you master this topic.

Perl modules are reusable .pm files that define packages, using Exporter.pm to control which symbols are exported to calling code -- installed via CPAN and loaded with use for compile-time or require for runtime.

Creating a Module

# File: lib/MyUtils.pm
package MyUtils;

use strict;
use warnings;
use Exporter 'import';

our @EXPORT_OK = qw(trim slugify capitalize);
our @EXPORT    = qw(trim);  # exported by default

sub trim {
    my $s = shift;
    $s =~ s/^\s+|\s+$//g;
    return $s;
}

sub slugify {
    my $s = shift;
    $s = lc($s);
    $s =~ s/[^a-z0-9]+/-/g;
    $s =~ s/^-|-$//g;
    return $s;
}

1;  # true return required

Using a Module

# Load module
use MyUtils;                    # imports default exports
use MyUtils qw(slugify);        # import specific symbols
use MyUtils qw(:DEFAULT);       # import defaults

# Function now available
my $clean = trim("  hello  ");
print $clean;  # hello

# Or with fully qualified name
my $slug = MyUtils::slugify("Hello World!");
print $slug;  # hello-world

Finding Modules

# Check if module is installed
use Module::Loaded;
print is_loaded("MyUtils");  # 1 or undef

# Load at runtime
require MyUtils;
MyUtils::import();

# Load only if available
eval { require JSON::PP };
if (!$@) {
    print JSON::PP::encode_json({a => 1});
}

CPAN Installation

# Install from CPAN
cpan Module::Name
cpanm Module::Name  # using cpanminus

# Common modules
cpanm Moose           # OOP framework
cpanm DBI             # Database interface
cpanm Plack           # Web server toolkit
cpanm Catalyst        # Web framework

Common Mistakes

1. Forgetting the 1; at end

A module must return true. Forgetting the 1; causes a compile error: "did not return a true value".

2. Not using @EXPORT_OK

Exporting too many symbols pollutes the caller's namespace. Use @EXPORT_OK and let users choose what to import.

3. Module file path mismatch

Module Foo::Bar must be in Foo/Bar.pm somewhere in @INC. Path must match the package name.

Practice Questions

1. What must every Perl module return? A true value, typically 1; at the end of the file.

2. How do you export symbols from a module? Use Exporter: use Exporter 'import' then define @EXPORT and @EXPORT_OK.

3. What is the difference between use and require? use loads at compile time and calls import. require loads at runtime and doesn't call import.

FAQ

{{< faq question="Where does Perl look for modules?" >}} In directories listed in @INC, including system directories, Perl-specific paths, and PERL5LIB. {{< /faq >}}

{{< faq question="How do I add a local module directory?" >}} use lib '/path/to/modules'; adds to @INC. Or set PERL5LIB=/path/to/modules in the environment. {{< /faq >}}

{{< faq question="What is the difference between .pm and .pl?" >}} .pm files are Perl modules (libraries). .pl files are Perl scripts (programs). Modules are meant to be used, scripts executed. {{< /faq >}}

What's Next

Now learn about object-oriented Perl.