Provided by: libextutils-modulemaker-perl_0.56-1_all bug

NAME

       ExtUtils::ModuleMaker - Better than h2xs for creating modules

SYNOPSIS

       At the command prompt:

           %   modulemaker

       Inside a Perl program:

           use ExtUtils::ModuleMaker;

           $mod = ExtUtils::ModuleMaker->new(
               NAME => 'Sample::Module'
           );

           $mod->complete_build();

           $mod->dump_keys(qw|
               ...  # key provided as argument to constructor
               ...  # same
           |);

           $mod->dump_keys_except(qw|
               ...  # key provided as argument to constructor
               ...  # same
           |);

           $license = $mod->get_license();

           $mod->make_selections_defaults();

VERSION

       This document references version 0.56 of ExtUtils::ModuleMaker, released to CPAN on
       January 30 2017.

DESCRIPTION

       This module is a replacement for the most typical use of the h2xs utility bundled with all
       Perl distributions:  the creation of the directories and files required for a pure-Perl
       module to be installable with make and distributable on the Comprehensive Perl Archive
       Network (CPAN).

       h2xs has many options which are useful -- indeed, necessary -- for the creation of a
       properly structured distribution that includes C code as well as Perl code.  Most of the
       time, however, h2xs is used as follows

           %   h2xs -AXn My::Module

       to create a distribution containing only Perl code.  ExtUtils::ModuleMaker is intended to
       be an easy-to-use replacement for this use of h2xs.

       While you can call ExtUtils::ModuleMaker from within a Perl script (as in the SYNOPSIS
       above), it's easier to use with a command-prompt invocation of the modulemaker script
       bundled with this distribution:

           %   modulemaker

       Then respond to the prompts.  For Perl programmers, laziness is a virtue -- and
       modulemaker is far and away the laziest way to create a pure Perl distribution which meets
       all the requirements for worldwide distribution via CPAN.

USAGE

   Usage from the command-line with modulemaker
       The easiest way to use ExtUtils::ModuleMaker is to invoke the modulemaker script from the
       command-line.  You can control the content of the files built by modulemaker either by
       supplying command-line options or -- easier still -- replying to the screen prompts in
       modulemaker's interactive mode.

       If you are encountering ExtUtils::ModuleMaker for the first time, you should turn now to
       the documentation for modulemaker which is bundled this distribution.  Return to this
       document once you have become familiar with modulemaker.

   Use of Public Methods within a Perl Program
       You can use ExtUtils::ModuleMaker within a Perl script to generate the directories and
       files needed to begin work on a CPAN-ready Perl distribution.  You will need to call
       "new()" and "complete_build()", both of which are described in the next section.  These
       two methods control the building of the file and directory structure for a new Perl
       distribution.

       There are four other publicly available methods in this version of ExtUtils::ModuleMaker.
       "dump_keys", "dump_keys_except" and "get_license" are intended primarily as shortcuts for
       trouble-shooting problems with an ExtUtils::ModuleMaker object.
       "make_selections_defaults" enables you to be even lazier in your use of
       ExtUtils::ModuleMaker by saving keystrokes entered for attributes.

       "new"

       Creates and returns an ExtUtils::ModuleMaker object.  Takes a list containing key-value
       pairs with information specifying the structure and content of the new module(s).  (In
       this documentation, we will sometimes refer to these key-value pairs as the attributes of
       the ExtUtils::ModuleMaker object.)  With the exception of key "EXTRA_MODULES" (see below),
       the values in these pairs are all strings.  Like most such lists of key-value pairs, this
       list is probably best held in a hash.   Keys which may be specified are:

       •   Required Argument

           •   NAME

               The only required feature.  This is the name of the primary module (with '"::"'
               separators if needed).  Will no longer support the older, Perl 4-style separator
               ''"'"'' like the module D'Oh.  There is no current default for NAME; you must
               supply a name explicitly.

       •   Other Important Arguments

           •   ABSTRACT

               A short description of the module.  CPAN likes to use this feature to describe the
               module.  If the abstract contains an apostrophe ("'"), then the value
               corresponding to key "ABSTRACT" in the list passed to the constructor must be
               double-quoted; otherwise Makefile.PL gets messed up.  Certain CPAN indexing
               features still work better if the abstract is 44 or fewer characters in length,
               but this does not appear to be as mandatory as in the past.  (Defaults to dummy
               copy.)

           •   VERSION

               A string holding the version number.  For alpha releases, include an underscore to
               the right of the dot like "0.31_21". (Default is 0.01.)

           •   LICENSE

               Which license to include in the Copyright section.  You can choose one of the
               standard licenses by including 'perl', 'gpl', 'artistic', and 18 others approved
               by opensource.org.  The default is to choose the 'perl' flavor which is to share
               it ''under the same terms as Perl itself.''

               Other licenses can be added by individual module authors to
               ExtUtils::ModuleMaker::Licenses::Local to keep your company lawyers happy.

               Some licenses include placeholders that will be replaced with AUTHOR information.

           •   BUILD_SYSTEM

               This can take one of three values:

               •   'ExtUtils::MakeMaker'

                   The first generates a basic Makefile.PL file for your module.

               •   'Module::Build'

                   The second creates a Build.PL file.

               •   'Module::Build and Proxy'

                   The third creates a Build.PL along with a proxy Makefile.PL script that
                   attempts to install Module::Build if necessary, and then runs the Build.PL
                   script.  This option is recommended if you want to use Module::Build as your
                   build system.  See Module::Build::Compat for more details.

                   Note:  To correct a discrepancy between the documentation and code in earlier
                   versions of ExtUtils::ModuleMaker, we now explicitly provide this synonym for
                   the third option:

                       'Module::Build and proxy Makefile.PL'

                   (Thanks to David A Golden for spotting this bug.)

           •   COMPACT

               For a module named ''Foo::Bar::Baz'' creates a base directory named
               ''Foo-Bar-Baz'' instead of Foo/Bar/Baz.  (Default is off.)

           •   VERBOSE

               Prints messages to STDOUT as it creates directories, writes files, etc. (Default
               is off.)

           •   PERMISSIONS

               Used to create new directories.  (Default is 0.56:  group and world can not
               write.)

           •   USAGE_MESSAGE

               Message given when the module "die"s.  Scripts should set this to the same string
               it would print if the user asked for help.  (A reasonable default is provided.)

           •   NEED_POD

               Include POD section in *.pm files created.  (Default is on.)

           •   NEED_NEW_METHOD

               Include a simple "new()" method in the *.pm files created.  (Default is on.)

           •   CHANGES_IN_POD

               Omit a Changes file, but instead add a HISTORY section to the POD.  (Default is
               off).

           •   INCLUDE_MANIFEST_SKIP

               Boolean value which, if true, includes a MANIFEST.SKIP file in the distribution
               with reasonable default values facilitating use of the make manifest command
               during module development.  (Thanks to David A Golden for this feature.  Default
               is off.)

           •   INCLUDE_TODO

               Boolean value which, if true, includes a Todo file in the distribution in which
               the module's author or maintainer can discuss future lines of development.
               (Default is on.)

           •   INCLUDE_LICENSE

               Boolean value which, if true, includes a LICENSE file in the distribution.  (Which
               LICENSE file is determined in the LICENSE option.)  (Default is on.)

           •   INCLUDE_SCRIPTS_DIRECTORY

               Boolean value which, if true, includes a scripts/ directory (at the same level as
               lib/ or t/).  (Default is on.)

           •   INCLUDE_WARNINGS

               Boolean value which, if true, inserts "use warnings;" in all Perl modules created
               by use of this module.  (Default is off.)

           •   INCLUDE_ID_LINE

               Boolean value which, if true, inserts "#$Id$" in all Perl modules created by use
               of this module for the purpose of inserting a Subversion file 'Id' string.
               (Default is off.)

       •   Arguments Related to the Module's Author

           •   AUTHOR

               Name of the author.  If the author's name contains an apostrophe ("'"), then the
               corresponding value in the list passed to the constructor must be double-quoted;
               otherwise Makefile.PL gets messed up.  (Defaults to dummy copy.)

           •   EMAIL

               Email address of the author.  If the author's e-mail address contains an
               apostrophe ("'"), then the corresponding value in the list passed to the
               constructor must be double-quoted; otherwise Makefile.PL gets messed up.
               (Defaults to dummy copy.)

           •   CPANID

               The CPANID of the author.  If this is omitted, then the line will not be added to
               the documentation.  (Defaults to dummy copy.)

           •   WEBSITE

               The personal or organizational website of the author.  If this is omitted, then
               the line will not be added to the documentation.  (Defaults to dummy copy.)

           •   ORGANIZATION

               Company or group owning the module.  If this is omitted, then the line will not be
               added to the documentation.  (Defaults to dummy copy.)

       •   Argument Related to Multiple Modules within a Distribution

           •   EXTRA_MODULES

               A reference to an array of hashes, each of which contains values for additional
               modules in the distribution.

                   $mod = ExtUtils::ModuleMaker->new(
                       NAME           => 'Alpha::Beta',
                       EXTRA_MODULES  => [
                           { NAME => 'Alpha::Beta::Gamma' },
                           { NAME => 'Alpha::Beta::Delta' },
                           { NAME => 'Alpha::Beta::Gamma::Epsilon' },
                       ],
                   );

               As with the primary module, the only attribute required for each extra module is
               "NAME".  Other attributes may be supplied but the primary module's values will be
               used if no value is given here.

               Each extra module will be created in the correct relative place in the lib
               directory.  By default, a test file will also be created in the t directory
               corresponding to each extra module to test that it loads properly.  (See
               EXTRA_MODULES_SINGLE_TEST_FILE below to learn how to change this behavior.)
               However, no other supporting documents (e.g., README, Changes) will be created.

               This is one major improvement over the earlier h2xs as you can now build multi-
               module packages.

       •   Arguments Related to Test Files

           •   FIRST_TEST_NUMBER

               A non-negative natural number from which the count begins in test files that are
               numerically ordered.  (Default is 1.)

           •   TEST_NUMBER_FORMAT

               In test files that are numerically ordered, a Perl "sprintf" formatting string
               that specifies how FIRST_TEST_NUMBER is to be formatted.  (Default is "%03d".)

           •   TEST_NAME

               String forming the core of the name of a test file.  (Default is "load").

           •   TEST_NAME_DERIVED_FROM_MODULE_NAME

               Boolean value which, when true, tells ExtUtils::ModuleMaker to create a file in
               the test suite with a name derived from the .pm package it is testing, thereby
               overriding any value set in the TEST_NAME attribute.  For example, for a module
               called 'Alpha::Sigma::Tau', a test file named t/Alpha_Sigma_Tau.t will be created.
               (Default is off.)

           •   TEST_NAME_SEPARATOR

               String holding the character which joins components of a test file's name, e.g.,
               the character used to join 001 and <load> in a file named 001_load.t.  (Defaults
               to an underscore "_".)

           •   EXTRA_MODULES_SINGLE_TEST_FILE

               Boolean value which, when true and when extra modules have been specified in the
               EXTRA_MODULES attribute, will put tests for those extra modules in a single test
               file rather than in individual test files corresponding to each module.  (Default
               is off.)

           •   INCLUDE_POD_COVERAGE_TEST

               Boolean value which, if true, causes a test file called t/pod-coverage.t to be
               included in the t/ directory.  This test is advocated by some Perl quality
               assurance experts and module authors.  However, since the maintainer of
               ExtUtils::ModuleMaker is not persuaded of its worth, default is off.

           •   INCLUDE_POD_TEST

               Boolean value which, if true, causes a test file called t/pod.t to be included in
               the t/ directory.  This test is advocated by some Perl quality assurance experts
               and module authors.  However, since the maintainer of ExtUtils::ModuleMaker is not
               persuaded of its worth, default is off.

           •   INCLUDE_FILE_IN_PM

               String holding a path to a file containing Perl code and/or documentation which
               will be included in each lib/*.pm file created in a particular distribution. By
               default, such content is placed after any constructor and before the main POD
               block.  This could, for example, be used to insert stub subroutines in each
               package within a distribution.  Default is off.

       •   Arguments for Advanced Usages

           •   INTERACTIVE

               Activates interactive mode in modulemaker utility.  The interactive mode presents
               the user with a series of menus from which the user selects features by entering
               text at the command prompt.  This attribute should only be used by interactive
               scripts like modulemaker.  (Default is off.)

           •   ALT_BUILD

               Name of a Perl package holding methods which override those called withiin
               "complete_build" to shape the content of files created by using
               ExtUtils::ModuleMaker.  See "An Alternative Approach to Subclassing" below.

       "complete_build"

       Creates all directories and files as configured by the key-value pairs passed to
       "ExtUtils::ModuleMaker::new".  Returns a true value if all specified files are created --
       but this says nothing about whether those files have been created with the correct
       content.

       "dump_keys"

       When troubleshooting problems with an ExtUtils::ModuleMaker object, it is often useful to
       use Data::Dumper to dump the contents of the object.  Use "dump_keys()" when you only need
       to examine a few of the object's attributes.

           $mod->dump_keys( qw| NAME ABSTRACT | );

       "dump_keys_except"

       When troubleshooting problems with an ExtUtils::ModuleMaker object, it is often useful to
       use Data::Dumper to dump the contents of the object.  However, since certain elements of
       that object are often quite lengthy (e.g, the values of keys "LicenseParts" and
       "USAGE_MESSAGE"), it's handy to have a dumper function that dumps all keys except certain
       designated keys.

           $mod->dump_keys_except(qw| LicenseParts USAGE_MESSAGE |);

       "get_license"

       Returns a string which nicely formats a short version of the License and Copyright
       information.

           $license = $mod->get_license();
           print $license;

       ... will print something like this:

           =====================================================================
           =====================================================================
           [License Information]
           =====================================================================
           =====================================================================
           [Copyright Information]
           =====================================================================
           =====================================================================

       (Earlier versions of ExtUtils::ModuleMaker contained a "Display_License" function in each
       of submodules ExtUtils::ModuleMaker::Licenses::Standard and
       ExtUtils::ModuleMaker::Licenses::Local.  These functions were never publicly documented or
       tested.  "get_license()" is intended as a replacement for those two functions.)

       "make_selections_defaults()"

       Saves the values you entered as arguments passed to "new()" in a personal defaults file so
       that they supersede the defaults provided by ExtUtils::ModuleMaker itself.

       This is an advanced usage of ExtUtils::ModuleMaker.  If you have used
       ExtUtils::ModuleMaker more than once, you have probably typed in a choice for "AUTHOR",
       "EMAIL", etc., more than once.  To save unnecessary typing and reduce typing errors,
       ExtUtils::ModuleMaker now offers you the possibility of establishing personal default
       values which override the default values supplied with the distribution and found in
       lib/ExtUtils/ModuleMaker/Defaults.pm.

       Suppose that you have called "ExtUtils::ModuleMaker::new()" as follows:

           $mod = ExtUtils::ModuleMaker->new(
               NAME            => 'Sample::Module',
               ABSTRACT        => 'Now is the time to join the party',
               AUTHOR          => 'Hilton Stallone',
               CPANID          => 'RAMBO',
               ORGANIZATION    => 'Parliamentary Pictures',
               WEBSITE         => 'http://parliamentarypictures.com',
               EMAIL           => 'hiltons@parliamentarypictures.com',
           );

       While $mod is still in scope, you can call:

           $mod->make_selections_defaults()

       and the values selected  -- with two important exceptions -- will be saved in a
       Personal/Defaults.pm file stored in your home directory.  The next time you invoke
       ExtUtils::ModuleMaker, the new values will appear in the appropriate locations in the
       files created by "complete_build()".  They will also appear in the menus provided on
       screen by the modulemaker utility.

       What are those two important exceptions?

       •   "NAME"

           You cannot enter a default value for "NAME":  the name of the module you are creating.
           ExtUtil::ModuleMaker's own defaults file omits a value for "NAME" to prevent you from
           overwriting an already existing module.  (More precisely, the default value is an
           empty string.  ExtUtil::ModuleMaker will throw an error if you attempt to create a
           module whose name is empty.)  This precaution applies to your personal defaults file
           as well.

       •   "ABSTRACT"

           Since every module you create presumably has its own unique purpose, every module must
           have a unique "ABSTRACT" to summarize that purpose.  ExtUtil::ModuleMaker supplies the
           following string as the default value for the "ABSTRACT" key:

               Module abstract (<= 44 characters) goes here

           ... a string which, not coincidentally, happens to be exactly 44 characters long -- so
           you can just overstrike it.  This will be the default value for "ABSTRACT" in any
           Personal/Defaults.pm file you create as well.

CUSTOMIZATION

       ExtUtils::ModuleMaker is designed to be customizable to your needs and to offer you more
       flexibility as you become more experienced with it.

   Via modulemaker Utility Interactive Mode
       As with everything else about ExtUtils::ModuleMaker, the easiest, laziest way to get
       started is via the modulemaker utility; see its documentation.  Suppose that you have
       entered your correct name, email address and website at the prompts in modulemaker's
       Author Menu.

         ------------------------

         modulemaker: Author Menu

             Feature       Current Value
         N - Author        'John Q Public'
         C - CPAN ID       'MODAUTHOR'
         O - Organization  'XYZ Corp.'
         W - Website       'http://public.net/~jqpublic'
         E - Email         'jqpublic@public.net'

         R - Return to main menu
         X - Exit immediately

         Please choose which feature you would like to edit:

       Why should you ever have to enter this information again?  Return to the modulemaker Main
       Menu ("R").

         ------------------------

         modulemaker: Main Menu

             Feature                     Current Value
         N - Name of module              ''
         S - Abstract                    'Module abstract (<= 44 characters) goes here'
         A - Author information
         L - License                     'perl'
         D - Directives
         B - Build system                'ExtUtils::MakeMaker'

         G - Generate module
         H - Generate module;
             save selections as defaults

         X - Exit immediately

         Please choose which feature you would like to edit:

       Select "H" instead of "G" to generate the distribution.  An internal call to
       "make_selections_defaults()" will save those selections in a personal defaults file and
       present them to you on the Author Menu the next time you go to use it.

   Via modulemaker Utility Command-Line Options Mode
       For simplicity, not all of ExtUtils::ModuleMaker's default values are represented on
       modulemaker's menus.  Those that are not represented on those menus cannot be changed from
       there.  They can, however, in many cases be specified as options passed to modulemaker on
       the command-line and automatically saved as personal defaults by including the "s" flag as
       one of those options.  If, for example, your name is 'John Q Public' and you want all
       modules you create to have compact top-level directories, you would call:

           %   modulemaker -Icsn Sample::Module -u 'John Q Public'

       A distribution with a top-level directory Sample-Module would be created.  'John Q Public'
       would appear in appropriate places in Sample-Module/Makefile.PL and
       Sample-Module/lib/Sample/Module.pm.  You could then throw away the entire Sample-Module
       directory tree.  The next time you call "modulemaker", the call

           %   modulemaker -In Second::Module

       would suffice to generate a compact top-level directory and 'John Q Public' would appear
       in appropriate locations instead of the dreaded 'A. U. Thor'.

   Via "ExtUtils::ModuleMaker::new()"
       In all cases, ExtUtils::ModuleMaker's default values can be overridden with arguments
       passed to "new()" inside a Perl program.  The overriding can then be made permanent by
       calling "make_selections_defaults()".

       Suppose, for example,

       1.  that you want the files in your test suite to appear in a numerical order starting
           from 0 rather than ExtUtils::ModuleMaker's own default starting point of 1;

       2.  that you want the number in the test file's name to be formatted as a two-digit string
           padded with zeroes rather than ExtUtils::ModuleMaker's own default format of a three-
           digit, zero-padded string;

       3.  that you want the numerical part of the test filename to be joined to the lexical part
           with a dot (".") rather than ExtUtils::ModuleMaker's own default linkage character of
           an underscore ("_"); and

       4.  that you want the lexical part of the test filename to reflect the module's name
           rather than ExtUtils::ModuleMaker's default of "load".

       Your Perl program would look like this:

           #!/usr/local/bin/perl
           use strict;
           use warnings;
           use ExtUtils::ModuleMaker;

           my $mod = ExtUtils::ModuleMaker->new(
               NAME        => 'Sample::Module',
               AUTHOR      => 'John Q Public',
               COMPACT     => 1,
               FIRST_TEST_NUMBER    => 0,
               TEST_NUMBER_FORMAT   => "%02d",
               TEST_NAME_SEPARATOR  => q{.},
               TEST_NAME_DERIVED_FROM_MODULE_NAME => 1,
           );

           $mod->make_selections_defaults();

       A subsequent call to the modulemaker utility,

           %    modulemaker -In Second::Balcony::Jump

       would generate a directory tree with a compact top-level, 'John Q Public' in appropriate
       locations in Second-Balcony-Jump/Makefile.PL and
       Second-Balcony-Jump/lib/Second/Balcony/Jump.pm and a test file called
       Second-Balcony-Jump/t/00.Second.Balcony.Jump.t.

   Via Subclassing ExtUtils::ModuleMaker
       If you're a power-user, once you start playing with ExtUtils::ModuleMaker, you won't be
       able to stop.  You'll ask yourself, ''Self, if I can change the default values, why can't
       I change the 'boilerplate' copy that appears inside the files which ExtUtils::ModuleMaker
       creates?''

       Now, you can.  You can hack on the methods which "ExtUtils::ModuleMaker::new()" and
       "complete_build()" call internally to customize their results to your heart's desire.  The
       key:  build an entirely new Perl extension whose lib/*.pm file has methods that override
       the methods you need overridden -- and only those methods.  Follow these steps:

       1. Study ExtUtils::ModuleMaker::Defaults, ::Initializers and ::StandardText

       ExtUtils::ModuleMaker's default values are stored in lib/ExtUtils/ModuleMaker/Defaults.pm,
       specifically, in its "default_values()" method.  Identify those values which you wish to
       change.

       ExtUtils::ModuleMaker's other internal methods are found in two other files:
       /lib/ExtUtils/ModuleMaker/Initializers.pm and lib/ExtUtils/ModuleMaker/StandardText.pm.
       Rule of thumb:  If an internal method is called within "new()", it is found in
       ExtUtils::ModuleMaker::Initializers.  If it is called within "complete_build()", it is
       found in ExtUtils::ModuleMaker::StandardText.  Study these two packages to identify the
       methods you wish to override.

       Hint:  If changing a default value in ExtUtils::ModuleMaker::Defaults will achieve your
       objective, make that change rather than trying to override methods in
       ExtUtils::ModuleMaker::Initializers or ExtUtils::ModuleMaker::StandardText.

       Hint:  You should probably think about overriding methods in
       ExtUtils::ModuleMaker::StandardText before overriding those in
       ExtUtils::ModuleMaker::Initializers.

       2. Use modulemaker to Create the Framework for a New Distribution

       You're creating a new Perl extension.  Who ya gonna call?  modulemaker, natch!  (If you
       have not read the documentation for modulemaker by this point, do so now.)

       Suppose that you've gotten on the 'Perl Best Practices' bandwagon and want to create all
       your Perl extensions in the style recommended by Damian Conway in the book of the same
       name.  Use modulemaker to create the framework:

           %    modulemaker -Icqn ExtUtils::ModuleMaker::PBP \
                -u 'James E Keenan' \
                -p JKEENAN \
                -o 'Perl Seminar NY' \
                -w http://search.cpan.org/~jkeenan/

       You used the "-q" option above because you do not want or need a constructor in the new
       package you are creating.  That package will inherit its constructor from
       ExtUtils::ModuleMaker.

       3. Edit the lib/*.pm File

       Open up the best text-editor at your disposal and proceed to hack:

           %    vi ExtUtils-ModuleMaker-PBP/lib/ExtUtils/ModuleMaker/PBP.pm

       Add this line near the top of the file:

           use base qw{ ExtUtils::ModuleMaker };

       so that ExtUtils::ModuleMaker::PBP inherits from ExtUtils::ModuleMaker (which, in turn,
       inherits from ExtUtils::ModuleMaker::Defaults, ExtUtils::ModuleMaker::Initializers and
       ExtUtils::ModuleMaker::StandardText).

       If you have carefully studied ExtUtils::ModuleMaker::Defaults,
       ExtUtils::ModuleMaker::StandardText and Perl Best Practices, you will write methods
       including the following:

           sub default_values {
               my $self = shift;
               my $defaults_ref = $self->SUPER::default_values();
               $defaults_ref->{COMPACT}                        = 1;
               $defaults_ref->{FIRST_TEST_NUMBER}              = 0;
               $defaults_ref->{TEST_NUMBER_FORMAT}             = "%02d";
               $defaults_ref->{EXTRA_MODULES_SINGLE_TEST_FILE} = 1;
               $defaults_ref->{TEST_NAME_SEPARATOR}            = q{.};
               $defaults_ref->{INCLUDE_TODO}                   = 0;
               $defaults_ref->{INCLUDE_POD_COVERAGE_TEST}      = 1;
               $defaults_ref->{INCLUDE_POD_TEST}               = 1;
               return $defaults_ref;;
           }

           sub text_Makefile {
               my $self = shift;
               my $Makefile_format = q~
           use strict;
           use warnings;
           use ExtUtils::MakeMaker;

           WriteMakefile(
               NAME            => '%s',
               AUTHOR          => '%s <%s>',
               VERSION_FROM    => '%s',
               ABSTRACT_FROM   => '%s',
               PL_FILES        => {},
               PREREQ_PM    => {
                   'Test::More'    => 0,
                   'version'       => 0,
               },
               dist            => { COMPRESS => 'gzip -9f', SUFFIX => 'gz', },
               clean           => { FILES => '%s-*' },
           );
           ~;
               my $text_of_Makefile = sprintf $Makefile_format,
                   map { my $s = $_; $s =~ s{'}{\\'}g; $s; }
                       $self->{NAME},
                       $self->{AUTHOR},
                       $self->{EMAIL},
                       $self->{FILE},
                       $self->{FILE},
                       $self->{FILE};
               return $text_of_Makefile;
           }

       Of course, for true Perl laziness, you'll use CPAN distribution
       ExtUtils::ModuleMaker::PBP, written by the author of ExtUtils::ModuleMaker as an exemplar
       of subclassing ExtUtils::ModuleMaker and generating the same output as Damian Conway's
       Module::Starter::PBP.

       4. Test

       How do you know you have correctly subclassed ExtUtils::ModuleMaker?  With a test suite,
       of course.  With careful editing, you can use many of ExtUtils::ModuleMaker's own tests in
       your new distribution.  You will, of course, have to change a number of tests, because the
       default values implied by Conway's recommendations are different from
       ExtUtils::ModuleMaker's own defaults.  Among other things, you will have to do a search-
       and-replace on all constructor calls.

           %    perl -pi'*.bak' -e 's{ExtUtils::ModuleMaker->new}{ExtUtils::ModuleMaker::PBP->new}g;'

       Of course, you should have written your tests first, right?

       5. Install and Use

       You would install your new distribution as you would any other Perl distribution, i.e.,
       with either ExtUtils::MakeMaker or Module::Build, depending on which you chose in creating
       your subclass.

           #!/usr/local/bin/perl
           use strict;
           use warnings;
           use ExtUtils::ModuleMaker::PBP;

           my $mod = ExtUtils::ModuleMaker::PBP->new(
               NAME        => 'Sample::Module',
           );

           $mod->complete_build();

       For an adaptation of the modulemaker utility to work with ExtUtils::ModuleMaker::PBP, see
       mmkrpbp which is bundled with the latter package.

       An Alternative Approach to Subclassing

       There is one other way to subclass to ExtUtils::ModuleMaker which bears mentioning, more
       because the author used it in the development of this version of ExtUtils::ModuleMaker
       than because it is recommended.  If for some reason you do not wish to create a full-
       fledged Perl distribution for your subclass, you can simply write the subclassing package
       and store it in the same directory hierarchy on your system in which your personal
       defaults file is stored.

       For example, suppose you are experimenting and only wish to override one method in
       ExtUtils::ModuleMaker::StandardText.  You can create a package called
       ExtUtils::ModuleMaker::AlternativeText.  If you are working on a Unix-like system, you
       would move that file such that its path would be:

           "$ENV{HOME}/.modulemaker/ExtUtils/ModuleMaker/AlternativeText.pm"

       You would then add one argument to your call to "ExtUtils::ModuleMaker::new()":

           my $mod = ExtUtils::ModuleMaker->new(
               NAME        => 'Sample::Module',
               ALT_BUILD   => 'ExtUtils::ModuleMaker::AlternativeText',
           );

CAVEATS

       •   Tests Require Perl 5.6

           While the maintainer has attempted to make the code in lib/ExtUtils/Modulemaker.pm and
           the modulemaker utility compatible with versions of Perl older than 5.6, the test
           suite currently requires 5.6 or later.  The tests which require 5.6 or later are
           placed in SKIP blocks.  Since the overwhelming majority of the tests do require 5.6,
           running the test suite on earlier Perl versions won't report much that is meaningful.

       •   Testing of modulemaker's Interactive Mode

           The easiest, laziest and recommended way of using this distribution is the command-
           line utility modulemaker, especially its interactive mode.  However, this is
           necessarily the most difficult test, as its testing would require capturing the STDIN,
           STDOUT and STDERR for a process spawned by a "system('modulemaker')" call from within
           a test file.  For now, the maintainer has relied on repeated visual inspection of the
           screen prompts generated by modulemaker.  With luck, Expect-based tests will be
           available in a future version.

       •   Testing modulemaker on Non-*nix-Like Operating Systems

           Since testing the modulemaker utility from within the test suite requires a "system()"
           call, a clean test run depends in part on the way a given operating system parses
           command-line arguments.  The maintainer has tested this on Darwin and Win32 and,
           thanks to a suggestion by A.  Sinan Unur, solved a problem on Win32.  Results on other
           operating systems may differ; feedback is welcome.

TO DO

       •   Tests for modulemaker's interactive mode.

       •   Possible new "USE_AS_BASE" attribute which would insert modules from which user's new
           module will inherit.

               USE_AS_BASE => [ qw|
                   Template::Toolkit
                   Module::Build
                   Lingua::Romana::Perligata
                   Acme::Buffy
               | ],

           Such an attribute would require replacement copy for
           "ExtUtils::ModuleMaker::StandardText::block_begin()".

       •   Creation of a mailing list for ExtUtils::ModuleMaker.

AUTHOR/MAINTAINER

       ExtUtils::ModuleMaker was originally written in 2001-02 by R. Geoffrey Avery (modulemaker
       [at] PlatypiVentures [dot] com).  Since version 0.33 (July 2005) it has been maintained by
       James E. Keenan (jkeenan [at] cpan [dot] org).

SUPPORT

       Send email to jkeenan [at] cpan [dot] org.  Please include 'modulemaker' in the subject
       line.  Please report any bugs or feature requests to
       "bug-ExtUtils-ModuleMaker@rt.cpan.org", or through the web interface at
       <http://rt.cpan.org>.

       Development repository: <https://github.com/jkeenan/extutils-modulemaker>

ACKNOWLEDGMENTS

       Thanks first and foremost to Geoff Avery for creating ExtUtils::Modulemaker and
       popularizing it via presentations I attended at YAPC::NA::2003 (Boca Raton) and
       YAPC::EU::2003 (Paris).

       Soon after I took over maintenance of ExtUtils::ModuleMaker, David A Golden became a
       driving force in its ongoing development, providing suggestions for additional
       functionality as well as bug reports.  David is the author of ExtUtils::ModuleMaker::TT
       which, while not a pure subclass of ExtUtils::ModuleMaker, extends its functionality for
       users of Template::Toolkit.

       Thanks for suggestions about testing the modulemaker utility to Michael G Schwern on
       perl.qa and A Sinan Unur and Paul Lalli on comp.lang.perl.misc.  Thanks for help in
       dealing with a nasty bug in the testing to Perlmonks davidrw and tlm.  That well known
       Perl hacker, Anonymous Guest, contributed another bug report  on rt.cpan.org.

       As development proceeded, several issues were clarified by members of Perlmonks.org.
       CountZero, xdg, Tanktalus, holli, TheDamian and nothingmuch made particularly useful
       suggestions, as did Brian Clarkson.

       Thanks also go to the following beta testers:  Alex Gill, Marc Prewitt, Scott Godin,
       Reinhard Urban and imacat.

       Version 0.39 of ExtUtils::ModuleMaker encountered spurious testing failure reports from
       testers.cpan.org.  These were eventually diagnosed as being due to bugs in the automated
       testing programs and/or their operating environments on different systems -- i.e., to
       problems outside ExtUtils::ModuleMaker itself.  Several Perlmonks helped investigate this
       problem:  chromatic, dave_the_m, randyk, and njh.

       Thanks to Paul M Sirianni for reporting bugs that led to versions 0.48 and 0.51.

       Thanks to Chris Kirke for pointing to reports at
       http://cpants.cpanauthors.org/dist/ExtUtils-ModuleMaker of inconsistent $VERSION numbers
       across the component files.

COPYRIGHT

       Copyright (c) 2001-2002 R. Geoffrey Avery.  Revisions from v0.33 forward (c) 2005-2015
       James E. Keenan.  All rights reserved.  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.

DISCLAIMER OF WARRANTY

       BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE,
       TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE
       COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE ''AS IS'' WITHOUT WARRANTY OF
       ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
       WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO
       THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE
       DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

       IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT
       HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY
       THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
       INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
       SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR
       LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY
       OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
       SUCH DAMAGES.

SEE ALSO

       modulemaker, perlnewmod, h2xs, ExtUtils::MakeMaker, Module::Build,
       ExtUtils::ModuleMaker::PBP, ExtUtils::ModuleMaker::TT, mmkrpbp.