How do you create a Perl module?

How do you write a module for Perl? In Python you can use:

# module.py
def helloworld(name):
    print "Hello, %s" % name

# main.py
import module
module.helloworld("Jim")

Answers


A class:

# lib/Class.pm
package Class;
use Moose;

# define the class

1;

A module that exports functions:

# lib/A/Module.pm
package A::Module;
use strict;
use warnings;
use Sub::Exporter -setup => {
    exports => [ qw/foo bar/ ],
};

sub foo { ... }
sub bar { ... }

1;

A script that uses these:

# bin/script.pl
#!/usr/bin/env perl

use strict;
use warnings;

use FindBin qw($Bin);
use lib "$Bin/../lib";

use Class;
use A::Module qw(foo bar);


print Class->new;
print foo(), bar();

Basically you create a file named Yourmodulename.pm, whose contents are:

package Yourmodulename;

# Here are your definitions

1; # Important, every module should return a true value

Then the program that uses the module will look like:

#!/usr/bin/perl
use strict;            # These are good pragmas
use warnings;      

# Used modules
use Carp;              # A module that you'll probably find useful
use Yourmodulename;    # Your module

You may want to organize your modules in a hierarchical (and hopefully logical) way. To do so you create a tree of directories like:

Your/Module.pm Your/Other/Module.pm

And then in your program:

use Your::Module;
use Your::Other::Module;

There are more facilities to export functions and variables from your module, you can take a look at Henning Koch's "Writing serious Perl: The absolute minimum you need to know".


An "exact" equivalent of your Python example in Perl would look like this:

# MyModule.pm
package MyModule;

sub helloworld { 
    my ( $name ) = @_;
    print "Hello, $name\n";
}

1;

# main.pl
use MyModule;
MyModule::helloworld( 'Jim' );

For more, see the entry for package in perlfunc documentation. For much more, see the perlmod documentation.


The last third of Intermediate Perl is devoted to module creation.

Whenever you want to know how to do something in Perl, check perltoc, the table of contents for the Perl documentation:

% perldoc perltoc

Several parts of the core Perl documentation can help you:

Good luck,


One minor detail that the answers so far haven't mentioned is that, if you have a (preferably small) module which is purpose-specific enough that it will never be reused, you can put it into the same file as the main program or another package:

# main.pl

# Since this is a beginner question, I'll also point out that you should
# *always* use strict and warnings.  It will save you many headaches.
use strict;
use warnings;

MyModule::helloworld('Jim');
AnotherModule::helloworld('Jim');

package MyModule; # Still in main.pl!

sub helloworld { 
    my ( $name ) = @_;
    print "Hello, $name\n";
}

package AnotherModule; # Yep, still main.pl

sub helloworld {
    my $name = shift;
    print "Another hello to $name\n";
}

This isn't used often because it gives you a package that's defined in a file whose name isn't the same as the package's, which can get confusing because you have to use/require the filename, but reference it in code by the package name.

Also note that the 1; is only needed as the final line of each file which is included via use/require. In this case, I didn't need it because it's in main.pl. If you put multiple packages into the same file, you only need a 1; at the end of the file, not after each package.


The most traditional way of setting up a module is as follows:

package Foo::Bar;
our @ISA       = qw(Exporter);       # Tells perl what to do with...
our @EXPORT    = qw(sub1 sub2 sub3); # automatically exported subs
our @EXPORT_OK = qw(sub4 sub5);      # exported only when demanded

# code for subs, constants, package variables here

1;  # Doesn't actually have to be 1, just a 'true' value.

and as others have said, you can use it like so:

use Foo::Bar;

h2xs -XA -n My::Module

h2xs is a utility that comes as standard with perl, intended for assisting in building linked modules including linked C headers/code, but which can be used to build a complete skeleton of a pure perl module (with the -XA flags), including things like a test directory, a README file, a Makefile, and a Manifest. (a good article outlining the details here: http://perltraining.com.au/tips/2005-09-26.html )

It's kinda old-school, but it's worth looking at even if just for all the reminders it gves you about getting everything right (tests, documentation, version numbers, export and export_ok lists, all the easy-to-forget stuff...)

You'll end up with a "Module.pm" file inside a "My" directory (from the "My::Module") that looks like this:

package My::Module;

use 5.008008;
use strict;
use warnings;

require Exporter;

our @ISA = qw(Exporter);

# Items to export into callers namespace by default. Note: do not export
# names by default without a very good reason. Use EXPORT_OK instead.
# Do not simply export all your public functions/methods/constants.

# This allows declaration       use My::Module ':all';
# If you do not need this, moving things directly into @EXPORT or @EXPORT_OK
# will save memory.
our %EXPORT_TAGS = ( 'all' => [ qw(

) ] );

our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );

our @EXPORT = qw(

);

our $VERSION = '0.01';


# Preloaded methods go here.

1;
__END__
# Below is stub documentation for your module. You'd better edit it!

=head1 NAME

My::Module - Perl extension for blah blah blah

cpanm Module::Starter::PBP
perl -MModule::Starter::PBP=setup
module-starter --module=My::Module

Need Your Help

Running a shell command from Node.js without buffering output

node.js child-process

I'm trying to launch a shell command from Node.js, without redirecting that command's input and output -- just like shelling out to a command using a shell script, or using Ruby's system command. I...

knockoutjs - multiple bindings on click event

javascript javascript-events knockout.js

I would like to know if it is possible to create multiple bindings on an event in knockout.js