Module Creation

[mvaline]

Up to this point, my perl experience has been largely in general scripting tasks and one large application. When DrZaius told me that my Find Ethernet Card Manufacturer script might be better as a module, I realized that this was an area in which I had little experience.

I've read the appropriate sections in the Camel book a couple of times, along with perlmod and perlmodlib and even browsed around CPAN a bit, thinking that they might at least have some guidelines for module creation. For the first time in my perl career, I am feeling rather dissatisfied with the documentation I've read.

For example, in the post mentioned above, DrZaius suggested that I include the mac address database into the __DATA__ section of a module. For the life of me, I can't seem to find any documentation about the __DATA__ section of a module.

I'm also curious about the ramifications of use and require statements, when it make more sense to use an object-oriented approach, etc.

Does you have any pointers to resources that might help me explore this facet of perl? Or perhaps you think I'm making the topic overcomplicated and can enlighten me in that regard.

[dragonchild]

__DATA__ isn't just for modules. It's a keyword that says "From this spot onwards, treat the rest of the file as if it was another file, called DATA".

One big resource would be Advanced Perl Programming. It has a number of sections on modules, both creation and maintenance.

The basic point behind modules is to encapsulate code that's used more than once by creating another namespace. (Don't worry about the namespace stuff, but remember it in the back of your mind.)

A standard package, if you're creating a set of functions to be used, would look something like:

use strict;
use 5.6.0;

package MyModule;

use Exporter;
our @ISA=qw(Exporter);

our @EXPORT_OK = qw(foo bar);

my $var1 = "Some value";

sub foo {
    ... # Maybe use $var1 here...
}

sub bar {
    ... # If not, use $var1 here.
}

1;

The 1; at the end is critical. Modules (or packages ... same thing) are pulled in with do, which requires that the last line be a true value.

$var1 is scoped so that ONLY functions within the package MyModule can access it. (That's not quite true, but you should code as if it is until you're more comfortable.)

Now, in your main program, you'd have a line similar to

use MyModule (foo);

That means that, in your main script, you can call foo() as if it was defined in your main script. However, you cannot call bar().

You've seen the use syntax a lot, I'm sure. If you put a symbol name (functions, usually) in @EXPORT (instead of @EXPORT_OK), then the function would be there, whether or not you requested it. A lot of CPAN modules that use Exporter do this, though it's generally considered somewhat rude programming style. (If you write a package like this, you're polluting my namespace, which is sorta rude if you think about it.)

This should be enough to give you an idea as to what questions you need to ask. I'm figuring that it's not that you don't know anything, cause that's obvious. It's more that you don't know what you don't know, which means you don't know what questions to ask.

[mvaline]

Thanks, you hit the nail on the head when you said that I don't know what questions to ask. I read the documentation I had and didn't really feel any smarter.

I'll pick up a copy of Advanced Perl Programming -- I just browsed the table of contents on the O'Reilly site, and I think it will be very helpful.

[lhoward]

One word of advice on creating your own modules: Use h2xs to generate your module. It builds all the necessary bits (Makefile.PL, POD stub, etc..) and makes it easy to bundle the module for redistribution and testing cpan style...

$ h2xs -A -X -n Example::Plugh
Writing Example/Plugh/Plugh.pm
Writing Example/Plugh/Makefile.PL
Writing Example/Plugh/test.pl
Writing Example/Plugh/Changes
Writing Example/Plugh/MANIFEST

After h2xs has built the boilerplate, just fill in all your code and you're ready to go.

[dragonchild]

This isn't for building modules, this is for building distributables. Building standard modules doesn't need 90% of what h2xs does. (It's all really good stuff, but completely unnecessary.)

[TGI]

Tom Christianson and/or Nathan Torkington seem to think this is a good idea, as they advocate this technique in the Perl Cookbook. I haven't tried it, but it looks like it takes care of a bunch of boring crap automagically (creating directories and a module skeleton along with other stuff). The syntax they recommend is: h2xs -XA -n Foo X suppresses the creation of XS components, the A says that the module won't use the autoloader, and the -n flag marks the name of the module.


TGI says moo

[lhoward]

It may be unnecessary, but sure is handy to have in case you ever start distributing that module that was "just for internal use"... And it doesn't hurt to have the extra stuff that h2xs adds.

[TGI]

The Perl Cookbook, which is a great all around resource, has a chapter on module creation that is very useful and a good companion to the info in Advanced Perl Programming. It even includes an explanation of how to prep your module for distribution. Buy this book, you will be glad you have it.


TGI says moo

[Cubes]

If you haven't yet, I'd suggest picking up a copy of Advanced Perl Programming. I think you'll find many of your answers there.

[TStanley]

I just wrote a review on a book called Instant Perl Modules that also might come in handy. It follows up on the comments made by lhoward concerning h2xs, and more specifically how to use it.

TStanley
--------
There's an infinite number of monkeys outside who want to talk to us
about this script for Hamlet they've worked out
-- Douglas Adams/Hitchhiker's Guide to the Galaxy

[Anonymous Monk]

The __DATA__ handle and __END__ tokens are described in perldata.pod, perlpod.pod, and perltoc.pod.

Try to use OO techniques when you want your libraries to be big, difficult, and slow.

Others have apparently recommended the use of h2xs, note that h2xs has internal pod documentation, as does ExtUtils::MakeMaker. After using h2xs to create a skeletal directory, and after you have edited all the files appropriately be sure to use:

    perl Makefile.PL
    make dist

in order to package your module in a manner suitable for putting on CPAN via PAUSE.

[WayneEarl]

I would avoid the use of __DATA__ when coding your module; this would make your module incompatable with mod_perl (see: http://perl.apache.org/dist/mod_perl_traps.html for more info.)

Perhaps it is not your intention to use mod_perl, but my basic philosophy is to write code that is as flexable as possible; better to write it this way in the first place, then have to re-write it later.

I would also suggest writing all modules using h2xs. Not only does this lead to a more consistant programming style, you don't have to worry about use lib statements, nor do you have to worry about access permissions to your module files.