NAME

Module::Text::Template::Build - Create a module based on a template to use with Module::Build

SYNOPSIS

 $> create_module --MODULE My::Module --TEMPLATE module_template_directory 

DESCRIPTION

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.

DOCUMENTATION

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

SCRIPT ARGUMENTS

See subroutine create_module

DEFAULT TEMPLATE

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.

Variables available to use in the template

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

Defining other variables

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.

BEFORE THE FIRST RUN

Modify the default template that was installed in your home directory. Grep for the 'MODIFY_ME_BEFORE_FIRST_RUN' string.

SCRIPTS

create_module is installed when you install this module.

SUBROUTINES/METHODS

create_module(@OPTIONS)

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.

create_module_element($template_file, \%template_variables)

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.

broken_template_handler()

Error handler required by the template system.

evaluate_name($name, \%lookup_table))

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

get_template_variables(@command_line_arguments)

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.

BUGS AND LIMITATIONS

None so far.

AUTHOR

        Khemir Nadim ibn Hamouda
        CPAN ID: NKH
        mailto:nadim@khemir.net

LICENSE AND COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SUPPORT

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

SEE ALSO

Module::Starter from which I proudly stole the good ideas while trying to avoid the excessive boilerplate.

h2xs

Module::Template::Setup

Text::Template