module-setup - Generate boilerplate files for a new module
module-setup --author="A.U.Thor" --email=a.u.thor@example.com Foo::Bar
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.
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.
Specifies the email address of the author of the module.
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.
Specifies the GitHub id of the author of the module. Optional.
Specifies the set of templates to use for this module. See "TEMPLATES". Default set is default.
default
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.
Initialises an empty git repository after creating the boilerplate files.
This is a shortcut for --postcmd="git init".
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
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.
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.
templates/default
You can move the templates to the config location if you want to use them for other module projects.
Shows a help message, and exits.
Shows verbose information during the process.
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.
$HOME/.config/module-setup/config
$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.
;
#
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.
::
-
Foo::Bar
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:
modstart
./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.
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.
[% foobar %]
foobar
The following variables are currently supported:
The name of the author, e.g., A.U. Thor.
A.U. Thor
The author's email address, e.g., a.u.thor@example.com,
a.u.thor@example.com
The author's CPAN id, e.g., THORAX.
THORAX
The author's GitHub id, e.g., Thorax.
Thorax
The name of the module to be created, e.g., Foo::Bar.
The initial version of the module, e.g., 0.01.
0.01
The distribution name for the module, e.g., Foo-Bar.
Same, but all lowercase. E.g., foo-bar.
foo-bar
The file name for the module, e.g., Foo/Bar.pm.
Foo/Bar.pm
The license for this module. Defaults to perl_5,
perl_5
The current year, for copyrights and such. E.g., 2013.
2013
The minimal version of perl required for this module. Defaults to 5.008.
5.008
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.
_Module.pm
Johan Vromans, <jv at cpan.org>
<jv at cpan.org>
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.
bug-app-module-setup at rt.cpan.org
You can find documentation for this module with the perldoc command.
perldoc module-setup
You can also look for information at:
RT: CPAN's request tracker
http://rt.cpan.org/NoAuth/Bugs.html?Dist=App-Module-Setup
Search CPAN
http://search.cpan.org/dist/App-Module-Setup
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 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.
To install App::Module::Setup, copy and paste the appropriate command in to your terminal.
cpanm
cpanm App::Module::Setup
CPAN shell
perl -MCPAN -e shell install App::Module::Setup
For more information on module installation, please visit the detailed CPAN module installation guide.