Johan Vromans > App-Module-Setup-0.04 > module-setup

Download:
App-Module-Setup-0.04.tar.gz

Annotate this POD

View/Report Bugs
Source   Latest Release: App-Module-Setup-0.06

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.

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

--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

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.

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.

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.

current.year

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

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

syntax highlighting: