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

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

DESCRIPTION
    *Note: ExtUtils::ModuleMaker has changed substantially in recent
    releases and ExtUtils::ModuleMaker::TT has similarly changed
    substantially to be compatible with these changes. Please report any
    bugs you may find.*

    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)

    *   Creates a template directory containing the default templates for
        subsequent user customization

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

    *   Included command-line program *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. These config files extend and/or override an
        `ExtUtils::ModuleMaker::Personal::Defaults' file. The program can
        create full distributions, single modules, single methods, default
        configuration files or default template directories

    Notable changes from ExtUtils::ModuleMaker:

    *   Default templates are generally simpler, as users are expected to
        customize their own

    *   .t files for single .pm files created *after* the original build are
        named after their corresponding .pm file rather than being
        sequentially numbered.

    *   In the command-line program, *COMPACT* style is set by default

USAGE
    ExtUtils::ModuleMaker::TT is designed to be used with the *ALT_BUILD*
    parameter of ExtUtils::ModuleMaker. It replaces much of the
    functionality of ExtUtils::ModuleMaker::StandardText.

     use ExtUtils::ModuleMaker;
     my $mmtt = ExtUtils::ModuleMaker->new (
         NAME => 'My::New::Module',
         ALT_BUILD => 'ExtUtils::ModuleMaker::TT',
     );

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

        makeperlmod -n Sample::Module

    See the makeperlmod manual page for details on creating a custom
    configuration file (for setting author details and other
    ExtUtils::ModuleMaker options) that will extend or override defaults set
    in an ExtUtils::ModuleMaker::Personal::Defaults file. The CUSTOMIZING
    TEMPLATES section below contains other examples.

    When specified as the ALT_BUILD, ExtUtils::ModuleMaker::TT provides
    several additional methods as described below. The makeperlmod source
    provides a practical example of such usage.

PUBLIC METHODS
  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 prior *complete_build()* call), the caller must be in a
    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 subroutine 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 TT2 to fill in the given template and write it to the output file.
    Requires a template name, a hash reference of parameters (typically just
    the `$mmtt' object itself), 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.

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 or add it to either the
    ExtUtils::ModuleMaker::Personal::Defaults file or to a `makeperlmod'
    config file.

  Changes from earlier versions

    ExtUtils::ModuleMaker now stores author information in the main object
    rather than in a separate hash datastructure. This will break old
    templates.

     # Old
     { 
       AUTHOR => { NAME => "John Doe", EMAIL => "john@doe.org" } 
     }
 
     # New
     {
       AUTHOR => "John Doe",
       EMAIL  => "john@doe.org",
     }

  Customizing with makeperlmod

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

        makeperlmod -d 

    This will create a default configuration file and print its location.
    See the makeperlmod manual for details on creating and using named
    configuration files.

    Next, create a template directory. Choose a location that is appropriate
    for your operating system. E.g., for unix:

        makeperlmod -t ~/.makeperlmod.templates

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

    Edit the default configuration file and add a *TEMPLATE_DIR* parameter.
    Use whatever directory you chose to hold the templates. Make any other
    desired edits to AUTHOR, etc. For example:

      TEMPLATE_DIR ~/.makeperlmod.templates
      AUTHOR John Q. Public

    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 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*, to
    the ExtUtils::ModuleMaker::Personal::Defaults file, or to a makeperlmod
    config file) and use these in custom templates. Be careful not to
    overwrite any class data needed elsewhere in the module.

  Default templates

    Templates included are:

        * README
        * Changes
        * Todo
        * Build.PL
        * Makefile.PL
        * Proxy_Makefile.PL
        * MANIFEST.SKIP
        * test.t
        * module.pm
        * method
        * pod.t
        * pod_coverage.t
    
INSTALLATION
     perl Build.PL
     perl Build
     perl Build test
     perl Build install

REQUIRES
    Required for operation

        Config::General
        Data::Dumper
        ExtUtils::ModuleMaker
        Getopt::Long
        Path::Class
        Pod::Usage
        Template

    Required for testing

        File::Copy
        File::pushd
        IPC::Run3
        Probe::Perl
        Test::More

    Template Toolkit PPM for ActiveState is available from the University of
    Winnipeg PPM repository:

    http://theoryx5.uwinnipeg.ca/ppms/

BUGS
    Please report bugs using the CPAN Request Tracker at
    http://rt.cpan.org/NoAuth/Bugs.html?Dist=ExtUtils-ModuleMaker-TT

    When submitting a bug or request, please include a test-file or a patch
    to an existing test-file that illustrates the bug or desired feature.

AUTHOR
    David A Golden (DAGOLDEN)

    dagolden@cpan.org

    http://dagolden.com/

COPYRIGHT
    Copyright (c) 2004-2005 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.

