Perl Best Practices

17.8. Creating Modules

Build new module frameworks automatically.

The "bones" of every new module are basically the same:

package

<MODULE NAME>; use version; our $VERSION = qv('0.0.1'); use warnings; use strict; use Carp;

# Module implementation here 1;

# Magic true value required at end of module __END_ _ =head1 NAME

<MODULE NAME> - [One line description of module's purpose here] =head1 VERSION This document describes

<MODULE NAME> version 0.0.1 =head1 SYNOPSIS use <MODULE NAME>;

# And the rest of the documentation template here

# (as described in Chapter 7)

So it makes sense to create each new module automatically, reusing the same templates for each. This rule applies not just to the .pm file itself, but also to the other standard components of a module distribution: the MANIFEST file, the Makefile.PL, the Build.PL, the README, the Changes file, and the lib/ and t/ subdirectories.

The easiest way to create all those components consistently is to use the Module::Starter CPAN module. After installing Module::Starter and setting up a minimal ~/.module-starter/config file:

author: Yurnaam Heere email: YHEERE@cpan.org

you can then simply type:

> module-starter --module=New::Module::Name

on the command line. Module::Starter will immediately construct a new subdirectory named New-Module-Name/ and populate it with the basic files that are needed to create a complete module.

Better still, Module::Starter has a simple plug-in architecture that allows you do specify how it creates each new module directory and its contents. For example, you can use the Module::Starter::PBP plugin (also on the CPAN) to cause Module::Starter to use the module templates, documentation proformas, and testing tools recommended in this book.

After installing the Module::Starter::PBP module, you can type:

> perl -MModule::Starter::PBP=setup

on the command line and the plug-in will automatically configure itself, prompting for any information it needs in order to do so. Once Module::Starter::PBP is set up, you can easily edit the standard templates it will have installed, to customize the boilerplate code to your own needs.