/ 
App-Module-Setup-0.09
River stage zero No dependents
/ module-setup

NAME

module-setup - Generate boilerplate files 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 for 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 agrees with.

module-setup uses a set of customisable templates so everyone can tailor it to whatever needs may arise. Its design goal is to be extremely simple for unexperienced users, while still being useful for more advanced module writing.

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 if possible.

This option can be preset in an optional configuration file.

--githubid=id

Specifies the GitHub id of the author of the module. Optional.

This option can be preset in an optional configuration file.

--template=set

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

This option can be preset in an optional configuration file.

--postcmd=cmd

Specifies a command to execute after creating the boilerplate files. The command will be executed in the distribution directory using the system shell. This can be used to postprocess the created files, set up a git repository, and so on.

This option can occur multiple times, all commands will be executed. This option can be preset in an optional configuration file.

--git

Initialises an empty git repository after creating the boilerplate files.

This is a shortcut for --postcmd="git init".

--module=name

Specifies the name of the new module to be created.

Alternatively, the module name can 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".

Note that the config file is processed at the point it appears on the command line, possibly overwriting values already specified.

--install-templates

Installs the default set of templates to the local disk, suitable for tailoring to one's needs. No further processing is done.

The templates are installed in subdirectory templates/default under the current directory, and will be used instead of the built-in templates for subsequent runs of module-setup in the same directory.

You can move the templates to the config location if you want to use them for other module projects.

--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 locations. 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
template = default
postcmd = git init

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

TEMPLATES

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

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

The source directory for the templates can be selected with a --template option or template setting in the config file. For example, if the selected template set is modstart, then the following locations are tried:

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

The default template set is named default. If no suitable 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. If there is no value available, a warning will be given and the substitution is not done.

The following variables are currently supported:

author.name

The name of the author, e.g., A.U. Thor.

author.email

The author's email address, e.g., a.u.thor@example.com,

author.cpanid

The author's CPAN id, e.g., THORAX.

author.githubid

The author's GitHub id, e.g., Thorax.

module.name

The name of the module to be created, e.g., Foo::Bar.

module.version

The initial version of the module, e.g., 0.01.

module.distname

The distribution name for the module, e.g., Foo-Bar.

module.distnamelc

Same, but all lowercase. E.g., foo-bar.

module.filename

The file name for the module, e.g., Foo/Bar.pm.

module.license

The license for this module. Defaults to perl_5,

current.year

The current year, for copyrights and such. E.g., 2013.

perl.minversion

The minimal version of perl required for this module. Defaults to 5.008.

Default templates

The default set of templates consists of the following files:

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

Note that the filename _Module.pm is magic, this template will be copied under the filename 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 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,2018 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.