NAME

module-setup - Generate boilerplate for a new module

SYNOPSIS

module-setup --author="A.U.Thor" --email=a.u.thor@example.com Foo::Bar

DESCRIPTION

module-setup is a boilerplate generator to new Perl modules.

Why, yet another one?

All existing boilerplate generators suit many users, but abhor others. They can do too much, or too little, or use conventions that not everyone uses.

module-setup uses a set of customisable templates so everyone can tailer it to whatever needs may arise.

COMMAND LINE OPTIONS

--author=name

Specifies the name of the author of the module.

If this option is not given, the name will be taken from the system account information.

This option can be preset in an optional configuration file.

--email=mailaddr

Specifies the email address of the author of the module.

This option can be preset in an optional configuration file.

--cpanid=id

Specifies the CPAN id of the author of the module.

If this option is not given, the id will be inferred from the email address is possible.

This option can be preset in an optional configuration file.

--templates=set

Specifies the set of templates to use for this module. See TEMPLATES. Default value is default.

This option can be preset in an optional configuration file.

--module=name

Specifies the name of the new module to be created.

Alternatively, the module name may also be specified as a command line argument, e.g.

module-setup Foo::Bar
--config=config

Specifies the name of an alternate config file to be loaded. See "CONFIG FILES".

--help

Shows a help message, and exits.

--verbose

Shows verbose information during the process.

CONFIG FILES

Some information can be preset in a config file. This is particulary useful for global information that is not likely to change, like the author's name and email address.

module-setup tries to find a config file in two location. First it tries $HOME/.config/module-setup/config, if this is missing, it tries $HOME/.module-setup/config .

The config file should contain settings like:

name = A.U. Thor
email: a.u.thor@example.com
cpanid = thorax
templates = default

Empty lines and lines starting with ; or # are ignored.

TEMPLATES

module-setup creates the distribution directory and populates it with boilerplate files. The distribution directory is the same as the name of the module, with all :: replaced with -. E.g., the directory for Foo::Bar would be Foo-Bar.

After creating this directory, module-setup copies all files from the templates directory into the distribution directory.

If the selected templates set is modstart, then the following locations are tried:

./templates/modstart/
$HOME/.config/module-setup/templates/modstart/
$HOME/.module-setup/templates/modstart/

The default templates set is named default. If no suitale templates can be found in any of the locations, a default set is provided by module-setup.

Variable substitution

While copying the templates, variable substitution is performed on the contents. Variables can be specified in the templates in Template Toolkit notation, e.g.,

... in some text the occurrence of [% foobar %] will be replaced ...

In the above example, [% foobar %] will be replaced with the value of the variable foobar.

The following variables are currently supported:

author.name

E.g., A.U. Thor

author.email

E.g., a.u.thor@example.com

author.cpanid

E.g., THORAX

module.name

E.g., Foo::Bar

module.version

E.g., 0.01

module.distname

E.g., Foo-Bar

module.distnamelc

E.g., foo-bar

module.filename

E.g., Foo/Bar.pm

current.year

E.g., 2013

Default templates

The default set of templates are

Changes
lib/_Module.pm
Makefile.PL
MANIFEST
README
t/00-load.t

Note that the name _Module.pm is magic, the template will be copied as the name of the new module.

AUTHOR

Johan Vromans, <jv at cpan.org>

BUGS

Please report any bugs or feature requests to bug-app-module-setup at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=App-Module-Setup. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc App::Module::Setup

You can also look for information at:

ACKNOWLEDGEMENTS

David Golden, for giving me the final incentive to write this module.

Sawyer X, for writing Module::Starter where I borrowed many ideas from.

COPYRIGHT & LICENSE

Copyright 2013 Johan Vromans, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.