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

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

Arguments

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

Arguments

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