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

  complete_build

        $mmtt->complete_build();

    or

        $mmtt->complete_build( NAME => 'Sample::Module' );

    Builds a complete distribution skeleton. Any named parameters are added
    to the configuration (overwriting any existing values) prior to
    building. It returns the distribution directory created. (Helpful in
    scripts.)

  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.

INTERNAL METHODS
    These methods are used internally. They are documented for developer
    purposes only and may change in future releases. End users are
    encouraged to avoid using them.

  Create_Base_Directory

    Overrides the parent. Same function, but sets the Base_Dir parameter to
    an absolute file path. (Helpful for single-module builds)

  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

