Starting your perl module

You can create a template for your module with h2xs. Perl modules can be written in just Perl, or a mixture of Perl and C, but for now let's assume you just want to write your module in Perl. To skip generating all the XS stuff that's used to write modules in C, use h2xs -X. We can also give h2xs the name of our module with the -n argument. Let's call this example module Hello::World.

So we're ready to start. Run h2xs -X -n Hello::World. You'll see the following output:

Writing Hello/World/World.pm
Writing Hello/World/Makefile.PL
Writing Hello/World/test.pl
Writing Hello/World/Changes
Writing Hello/World/MANIFEST
The files that are created are "stubs" that can edited freely.

Editing the module

First let's look at the World.pm that is created by h2xs. Here's what it contains:


package Hello::World;

use strict;
use vars qw($VERSION @ISA @EXPORT @EXPORT_OK);

require Exporter;
require AutoLoader;

@ISA = qw(Exporter AutoLoader);
# 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.
@EXPORT = qw(
	
);
$VERSION = '0.01';


# Preloaded methods go here.

# Autoload methods go after =cut, and are processed by the autosplit program.

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

=head1 NAME

Hello::World - Perl extension for blah blah blah

=head1 SYNOPSIS

  use Hello::World;
  blah blah blah

=head1 DESCRIPTION

Stub documentation for Hello::World was created by h2xs. It looks like the
author of the extension was negligent enough to leave the stub
unedited.

Blah blah blah.

=head1 AUTHOR

A. U. Thor, a.u.thor@a.galaxy.far.far.away

=head1 SEE ALSO

perl(1).

=cut
The stub contains all the "boilerplate" code for our module, and also a hint at how to write the documentation for the module.

Now let's start adding code. First, let's create a sub that prints "Hello, World".

sub hello
{
    print "Hello, World\n";
}
Now, we just shove that in someplace after $VERSION and add &hello to @EXPORT. Then we can test it by doing perl Makefile.PL, then make, which sets up a directory structure for us. The we can do perl -Mlib=blib/lib -MHello::World -e hello.

(It's generally considered rude to pollute the caller's namespace, so it's much more polite to use @EXPORT_OK instead of @EXPORT. You'd then have to test with perl -Mlib=blib/lib -MHello::World=hello -e hello.)

Adding an OO interface

First, every OO module needs a new. Here's the simplest:

sub new
{
    my $self=shift;
    my $class=ref($self) || $self;
    return bless {}, $class;
}
That's all we need for new for now.

Now we need to write some OO code. Let's make a sub called just print. It should look something like this:

sub print
{
    my $self=shift;
    carp "called without a reference" if (!ref($self));

    print "Hello, World\n";
}
(We also need to do a use Carp; in the module so we can add that call to carp in the sub.)

Now we can test the module again with perl -Mlib=. -MWorld -e '$hello=Hello::World->new; $hello->print;'. The output of that should look like

Hello, World

Finishing up

All we need to do now is fix up the pod documentation and comments in the file. Technically, we should add test cases to test.pl too, but in this case, there's not much to test.

Here's the final code:

package Hello::World;

use strict;
use vars qw($VERSION @ISA @EXPORT @EXPORT_OK);

use Carp;

require Exporter;
#require AutoLoader;

#@ISA = qw(Exporter AutoLoader);
@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.
@EXPORT_OK = qw(
	&hello
);
$VERSION = '0.01';

sub new
{
    my $self=shift;
    my $class=ref($self) || $self;
    return bless {}, $class;
}

sub print
{
    my $self=shift;
    carp "called without a reference" if (!ref($self));

    print "Hello, World\n";
}

sub hello
{
    print "Hello, World\n";
}

1;
__END__

=head1 NAME

Hello::World - Example "Hello, World" module

=head1 SYNOPSIS

  use Hello::World;
  $hello=Hello::World->new;
  $hello->print;

=head1 DESCRIPTION

Calling the B<print> method on a Hello::World object makes it print
"Hello, World\n".

=head1 AUTHOR

Steven Pritchard, steve@silug.org

=head1 SEE ALSO

perl(1).

=cut

Below is the documentation for Hello::World.

NAME

Hello::World - Example ``Hello, World'' module

SYNOPSIS

  use Hello::World;
  $hello=Hello::World->new;
  $hello->print;

DESCRIPTION

Calling the print method on a Hello::World object makes it print ``Hello, World\n''.

AUTHOR

Steven Pritchard, steve@silug.org

SEE ALSO

perl(1).