NAME

ExtUtils::ModuleMaker::TT - Makes skeleton modules with Template Toolkit templates

SYNOPSIS

 use ExtUtils::ModuleMaker::TT;
 my $mmtt = ExtUtils::ModuleMaker::TT->new (
     NAME => 'My::New::Module',
     TEMPLATE_DIR => '~/.perltemplates'
 );
 $mmtt->complete_build();

DESCRIPTION

Note: ExtUtils::ModuleMaker has changed substantially in recent releases. This version of ExtUtils::ModuleMaker::TT has been updated to be minimally compatible with these changes, but has not yet been completely overhauled to reflect new capabilities in ExtUtils::ModuleMaker (e.g. configuration file support) and unwind some tightly-coupled functions. Documentation is likewise lagging slightly. Please report any bugs you may find. I am working closely with the maintainer of ExtUtils::ModuleMaker to improve the integration of these two modules.

This module extends ExtUtils::ModuleMaker to use Template Toolkit 2 (TT2) to build skeleton files for a new module. Templates may either be default templates supplied within the module or user-customized templates in a directory specified with the TEMPLATE_DIR parameter.

Summary of Features/Enhancements:

• Supports building full module skeletons with all the functionality of ExtUtils::ModuleMaker

• Supports adding a single .pm file (and corresponding .t file) to an existing module distribution tree.

• Supports creating skeleton text for a single method (generally to be called via a script from within your favorite editor)

• Can create a template directory containing the default templates for subsequent user customization

• Templates can access any parameter in the creating object (e.g. $mmtt, above). This supports transparent, user-extensible template variables for use in custom templates

• Included script makeperlmod provides a command line user interface for module creation. Supports reading default configuration settings from a file and will create a default config file if requested. Can create full distributions, single modules, single methods, or default template directories

Notable changes from ExtUtils::ModuleMaker:

• complete_build now takes arguments that are added to or overwrite the current configuration

• Default templates are generally simpler and more compact

• Also creates a MANIFEST.SKIP file with reasonable default contents

• Tests are named after their corresponding .pm files rather than being sequentially numbered. This change supports the "single .pm" mode more consistently. E.g., for "Sample::Module", a test file "Sample_Module.t" is created

• Supports both 'Module::Build and Proxy' and 'Module::Build and proxy Makefile.PL' as BUILD_SYSTEM synonyms to cover discrepancy between ExtUtils::ModuleMaker code and pod

USAGE

Generally, users should just use the included script, makeperlmod. For example, the following command will create a module distribution using default settings:

    makeperlmod -n Sample::Module

See the makeperlmod man page for details on creating a custom configuration file (for setting author details and other ExtUtils::ModuleMaker options). The "CUSTOMIZING TEMPLATES" section below contains other examples.

ExtUtils::ModuleMaker::TT can also be used programatically via the object methods defined below. The makeperlmod source provides a practical example of this approach.

PUBLIC METHODS

new

    $mmtt = ExtUtils::ModuleMaker::TT->new ( %config );

Uses the same configuration options as ExtUtils::ModuleMaker. Users may also define a TEMPLATE_DIR parameter, in which case that directory will be used as the source for all templates. See "CUSTOMIZING TEMPLATES", below. Returns a new ExtUtils::ModuleMaker::TT object.

build_single_pm

    $mmtt->build_single_pm( $module );

Creates a new .pm file and a corresponding .t file.

The $module parameter may be either a hash reference containing configuration options (including NAME) or a string containing the name of a module, in which case the default configuration will be used. E.g.:

    $module = { NAME => 'Sample::Module', NEED_POD => 0 };

or

    $module = 'Sample::Module';
 

This method must be able to locate the base directory of the distribution in order to correctly place the .pm and .t files. A complete_build() call sets the Base_Dir parameter appropriately as it creates the distribution directory. When called on a standalone basis (without a complete_build() call), the caller must be in a working directory within the distribution tree. When Base_Dir is not set, this method will look in the current directory for both a 'MANIFEST' file and a 'lib' directory. If neither are found, it will scan upwards in the directory tree for an appropriate directory. Requiring both files prevents mistakenly using either a template directory or a unix root directory. The method will croak if a proper directory cannot be found. The working directory in use prior to the method being called will be restored when the method completes or croaks. Returns a true value if successful.

build_single_method

    $mmtt->build_single_method( $method_name );

Returns a string with a skeleton method header for the given $method_name. Used internally, but made available for use in scripts to be called from your favorite editor.

create_template_directory

    $mmtt->create_template_directory( $directory );

Creates the named $directory and populates it with a file for each default template. These can be customized and the directory used in conjunction with the TEMPLATE_DIR configuration options. See "CUSTOMIZING TEMPLATES", below. Returns a true value if successful.

process_template

    $mmtt->process_template( $template, \%data, $outputfile );

Calls TT to fill in the template and write it to the output file. Requires a template name, a hash reference of parameters, and an outputfile (relative to the base distribution directory). If the TEMPLATE_DIR parameter is set, templates will be taken from there, otherwise the default templates are used. Returns a true value if successful.

default_templates

    $mmtt->default_templates();
 

Generates the default templates from <<HERE statements in the code. Returns a hash containing the default templates

Templates included are:

    * README
    * Changes
    * Todo
    * Build.PL
    * Makefile.PL
    * Proxy_Makefile.PL
    * MANIFEST.SKIP
    * test.t
    * module.pm

CUSTOMIZING TEMPLATES

Overview

Use the makeperlmod script to create a directory containing a copy of the default templates. Alternatively, use the create_template_directory method directly. Edit these templates to suit personal taste or style guidelines. Be sure to specify a TEMPLATE_DIR configuration option when making modules.

Customizing with makeperlmod

This can all be done quite easily with makeperlmod. Begin with:

    makeperlmod -d ~/.makeperlmod.config
    makeperlmod -t ~/.makeperlmod.templates

Edit .makeperlmod.config and add TEMPLATE_DIR ~/.makeperlmod.templates. Make any other desired edits to AUTHOR, COMPACT, etc. (COMPACT is recommended.)

Edit the resulting templates as needed. Templates are written with the Template Toolkit to allow for easy user customization of the contents and layout. See the Template module for the full syntax or just examine the default templates for quick changes.

Presto! Customization is done. Now start making modules with

    makeperlmod -n My::New::Module

Creating custom template variables (use with caution)

When templates are processed, the entire ExtUtils::ModuleMaker::TT object is passed to the Template Toolkit. Thus any class data is available for use in templates. Users may add custom configuration options ( to new or in a ~/.makeperlmod.config file and use these in custom templates. Be careful not to overwrite any class data needed elsewhere in the module.

INSTALLATION

 perl Build.PL
 Build
 Build test
 Build install

REQUIRES

 ExtUtils::ModuleMaker
 Template
 Cwd
 File::Path
 Getopt::Long
 Pod::Usage
 File::Spec::Functions
 File::Basename
 Config::General
 Data::Dumper
    

BUGS

None reported yet, though there must be some. E-mail bug reports to the author.

SUPPORT

E-mail the author

AUTHOR

 David A. Golden
 david@dagolden.com
 http://dagolden.com/
    

COPYRIGHT

Copyright (c) 2004 by David A. Golden

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

The full text of the license can be found in the LICENSE file included with this module.

SEE ALSO

perl, ExtUtils::ModuleMaker, Template