نديم ابن ﺤﻣﻮﺪﺓ الخمير - Nadim Khemir > Module-Text-Template-Build-0.05.10 > Module::Text::Template::Build

Download:
Module-Text-Template-Build-0.05.10.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  1
Open  0
View/Report Bugs
Module Version: 0.05   Source  

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.

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

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

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:

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

syntax highlighting: