Module::Text::Template::Build - Create a module based on a template to use with Module::Build
$> create_module --MODULE My::Module --TEMPLATE module_template_directory
This script allows you to simply create perl modules from a template. A default template is provided but you can easily create your own or modify the default template.
Given a template structure like this one:
module_template/ |-- Build.PL |-- Changes |-- Makefile.PL |-- README |-- Todo |-- lib | `-- $MODULE_ROOT+$MODULE_NAME.pm |-- scripts `-- t |-- 001_load.t |-- 002_pod_coverage.t |-- 003_pod.t `-- 004_perl_critic.t
Running the command:
$>create_module --MODULE CONFIG::XYZ --TEMPLATE module_template
Will create this file structure under your current directory:
CONFIG/ `-- XYZ |-- Build.PL |-- Changes |-- Makefile.PL |-- README |-- Todo |-- lib | `-- CONFIG | `-- XYZ.pm `-- t |-- 001_load.t |-- 002_pod_coverage.t |-- 003_pod.t `-- 004_perl_critic.t
All the file in the module template directory are run through Text::Template. Any perl code within '{{' and '}}' will be evaluated.
This allows you to do variable replacement like this:
module_name => '{{$FULL_MODULE_NAME}}',
or
{{$MODULE_NAME}} {{'=' x length $MODULE_NAME}}
Thanks to "Text::Template " you can do advanced query and replacements. You can, for example, query the module description if you haven't given it on the command line.
{{ $|++ ; unless(defined $MODULE_DESCRIPTION) { print q{'MODULE_DESCRIPTION' needed for template: '} . __FILE__ . "'.\n" ; print STDOUT "Please input module description: " ; $MODULE_DESCRIPTION = <STDIN> ; } }}
See subroutine create_module
create_module
The default template that is installed is based on my experience and may be very different from what you expect. It's a good template if you haven't created Perl modules for distribution on CPAN before.
I use Module::Builder as a build system and I use git as a version control system. This is reflected in the default template.
The xt/author contains many extra tests that are executed when you run:
./Build author_test
Changing the template is very easy and you should not hesitate to do it. Being able to very simply change the template was the reason I wrote this module.
Also note that the default license is the perl license.
create_module will display the available variables and the values they had when creating the module.
Using these template variables: |- DATE = Mon Nov 27 11:42:13 2006 |- DISTRIBUTION = CONFIG-XYZ |- DISTRIBUTION_DIRECTORY = CONFIG/XYZ |- DISTRIBUTION_ENV_VARIABLE = CONFIG_XYZ |- FULL_MODULE_NAME = CONFIG::XYZ |- MODULE = CONFIG::XYZ |- MODULE_HIERARCHY = CONFIG:: |- MODULE_NAME = XYZ |- MODULE_ROOT = CONFIG/ |- MODULE_ROOT+ = CONFIG/ |- RT_NAME = config-xyz |- TEMPLATE = module_template/ `- YEAR = 2006
You can very easily define variables on the command line that you can use in your personal template:
create_module --MY_VARIABLE 'something I need badly' --MODULE My::Module ...
You can now use {{$MY_VARIABLE}} in your templates and even check if it defined before using it.
Modify the default template that was installed in your home directory. Grep for the 'MODIFY_ME_BEFORE_FIRST_RUN' string.
create_module is installed when you install this module.
Creates a module skeleton based on a template.
create_module('My::Next::Module') ; or create_module ( '--MODULE' => 'My::Next::Module', '--MODULE_DESCRIPTION' => 'Short description', '--TEMPLATE' => 'path_to_template_directory', ) ;
Arguments
Accepts a single argument, the module name, or a set of key=value pairs.
MODULE - The name of the module to create. For example My::Next::Module.
MODULE_DESCRIPTION - Short description for the module. You'll be prompted for one if none is given.
TEMPLATE - The template location. It is either passed as an argument to create_module or is automatically searched for in your home directory under ~/.perl_module_template.
OUTPUT_DIRECTORY - The directory under which the module will be generated, must exist. Defaults to your current directory.
Returns - Nothing
Exceptions - croaks, with a message, if the arguments are wrong or the creation doesn't succeed.
Runs the given file through the template system and adds it to the module directory
$template_file - The file to be run through the template system.
\%template_variables - Variables available during the template system run.
Returns - Nothing.
Exceptions - croaks in case of error.
Error handler required by the template system.
Interpolates variables embedded i a string.
$name - A string with, possibly, embedded variables to interpolate
\%lookup_table - A hash where the keys are the variable names and the keys their values
Returns - A string with the, possibly, embedded variables interpolated
Verify the variables passed as arguments. It also creates new variables to be made available to the template system.
Arguments - Same arguments as sub create_module
Returns - A variable look-up table (a hash where the keys are the variable names and the keys their values).
Exceptions croaks if the options are not passed as key and value pairs or if required definitions are missing.
None so far.
Khemir Nadim ibn Hamouda CPAN ID: NKH mailto:nadim@khemir.net
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
You can find documentation for this module with the perldoc command.
perldoc Module::Text::Template::Build
You can also look for information at:
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/Module-Text-Template-Build
RT: CPAN's request tracker
Please report any bugs or feature requests to L <bug-module-text-template-build@rt.cpan.org>.
We will be notified, and then you'll automatically be notified of progress on your bug as we make changes.
Search CPAN
http://search.cpan.org/dist/Module-Text-Template-Build
Module::Starter from which I proudly stole the good ideas while trying to avoid the excessive boilerplate.
h2xs
Module::Template::Setup
Text::Template
1 POD Error
The following errors were encountered while parsing the POD:
L<> starts or ends with whitespace
To install Module::Text::Template::Build, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Module::Text::Template::Build
CPAN shell
perl -MCPAN -e shell install Module::Text::Template::Build
For more information on module installation, please visit the detailed CPAN module installation guide.