NAME

       ExtUtils::ModuleMaker::StandardText - Methods used within ExtUtils::ModuleMaker

DESCRIPTION

       The methods described below are 'quasi-private' methods which are called by the publicly
       available methods of ExtUtils::ModuleMaker and ExtUtils::ModuleMaker::Interactive.  They
       are 'quasi-private' in the sense that they are not intended to be called by the everyday
       user of ExtUtils::ModuleMaker.  Nothing prevents a user from calling these methods, but
       they are documented here primarily so that users writing plug-ins for
       ExtUtils::ModuleMaker's standard text will know what methods need to be subclassed.

       The methods below are called in "ExtUtils::ModuleMaker::complete_build()" but not in that
       same package's "new()".  For methods called in "new()", please see
       ExtUtils::ModuleMaker::Initializers.

       The descriptions below are presented in hierarchical order rather than alphabetically.
       The order is that of ''how close to the surface can a particular method called?'', where
       'surface' means being called within "ExtUtils::ModuleMaker::complete_build()".  So methods
       called within "complete_build()" are described before methods which are only called within
       other quasi-private methods.  Some of the methods described are also called within
       ExtUtils::ModuleMaker::Interactive methods.  And some quasi-private methods are called
       within both public and other quasi-private methods.  Within each heading, methods are
       presented more or less as they are first called within the public or higher-order quasi-
       private methods.

       Happy subclassing!

METHODS

   Methods Called within "complete_build()"
       "create_base_directory"

         Usage     : $self->create_base_directory within complete_build()
         Purpose   : Create the directory where all the files will be created.
         Returns   : $DIR = directory name where the files will live
         Argument  : n/a
         Comment   : $self keys Base_Dir, COMPACT, NAME.  Calls method create_directory.

       "create_directory()"

         Usage     : create_directory( [ I<list of directories to be built> ] )
                     in complete_build; create_base_directory; create_pm_basics
         Purpose   : Creates directory(ies) requested.
         Returns   : n/a
         Argument  : Reference to an array holding list of directories to be created.
         Comment   : Essentially a wrapper around File::Path::mkpath.  Will use
                     values in $self keys VERBOSE and PERMISSIONS to provide
                     2nd and 3rd arguments to mkpath if requested.
         Comment   : Adds to death message in event of failure.

       "print_file()"

         Usage     : $self->print_file($filename, $filetext) within complete_build()
         Purpose   : Adds the file being created to MANIFEST, then prints text to new
                     file.  Logs file creation under verbose.  Adds info for
                     death_message in event of failure.
         Returns   : n/a
         Argument  : 2 arguments: filename and text to be printed
         Comment   :

   Methods Called within "complete_build()" as an Argument to "print_file()"
       "text_README()"

         Usage     : $self->text_README() within complete_build()
         Purpose   : Build README
         Returns   : String holding text of README
         Argument  : n/a
         Throws    : n/a
         Comment   : This method is a likely candidate for alteration in a subclass

       "text_Todo()"

         Usage     : $self->text_Todo() within complete_build()
         Purpose   : Composes text for Todo file
         Returns   : String with text of Todo file
         Argument  : n/a
         Throws    : n/a
         Comment   : This method is a likely candidate for alteration in a subclass
         Comment   : References $self key NAME

       "text_Changes()"

         Usage     : $self->text_Changes($only_in_pod) within complete_build;
                     block_pod()
         Purpose   : Composes text for Changes file
         Returns   : String holding text for Changes file
         Argument  : $only_in_pod:  True value to get only a HISTORY section for POD
                                    False value to get whole Changes file
         Throws    : n/a
         Comment   : This method is a likely candidate for alteration in a subclass
         Comment   : Accesses $self keys NAME, VERSION, timestamp, eumm_version

       "text_test()"

         Usage     : $self->text_test within complete_build($testnum, $module)
         Purpose   : Composes text for a test for each pm file being requested in
                     call to EU::MM
         Returns   : String holding complete text for a test file.
         Argument  : Two arguments: $testnum and $module
         Throws    : n/a
         Comment   : This method is a likely candidate for alteration in a subclass
                     Will make a test with or without a checking for method new.

       "text_Makefile()"

         Usage     : $self->text_Makefile() within complete_build()
         Purpose   : Build Makefile
         Returns   : String holding text of Makefile
         Argument  : n/a
         Throws    : n/a
         Comment   : This method is a likely candidate for alteration in a subclass

       "text_Buildfile()"

         Usage     : $self->text_Buildfile() within complete_build()
         Purpose   : Composes text for a Buildfile for Module::Build
         Returns   : String holding text for Buildfile
         Argument  : n/a
         Throws    : n/a
         Comment   : This method is a likely candidate for alteration in a subclass,
                     e.g., respond to improvements in Module::Build
         Comment   : References $self keys NAME and LICENSE

       "text_proxy_makefile()"

         Usage     : $self->text_proxy_makefile() within complete_build()
         Purpose   : Composes text for proxy makefile
         Returns   : String holding text for proxy makefile
         Argument  : n/a
         Throws    : n/a
         Comment   : This method is a likely candidate for alteration in a subclass

       "text_MANIFEST_SKIP()"

         Usage     : $self->text_MANIFEST_SKIP() within complete_build()
         Purpose   : Composes text for MANIFEST.SKIP file
         Returns   : String with text of MANIFEST.SKIP file
         Argument  : n/a
         Throws    : n/a
         Comment   : References $self key NAME
         Comment   : Adapted from David Golden's ExtUtils::ModuleMaker::TT

       "text_pod_coverage_test()"

         Usage     : $self->text_pod_coverage_test() within complete_build()
         Purpose   : Composes text for t/pod-coverage.t
         Returns   : String with text of t/pod-coverage.t
         Argument  : n/a
         Throws    : n/a
         Comment   : Adapted from Andy Lester's Module::Starter
         Comment   : I don't think of much of this metric, but Andy and Damian do,
                     so if you want it you set INCLUDE_POD_COVERAGE_TEST => 1

       "text_pod_test()"

         Usage     : $self->text_pod_test() within complete_build()
         Purpose   : Composes text for t/pod.t
         Returns   : String with text of t/pod.t
         Argument  : n/a
         Throws    : n/a
         Comment   : Adapted from Andy Lester's Module::Starter
         Comment   : I don't think of much of this metric, but Andy and Damian do,
                     so if you want it you set INCLUDE_POD_TEST => 1

       "text_pm_file()"

         Usage     : $self->text_pm_file($module) within complete_build()
         Purpose   : Composes a string holding all elements for a pm file
         Returns   : String holding text for a pm file
         Argument  : $module: pointer to the module being built
                     (as there can be more than one module built by EU::MM);
                     for the primary module it is a pointer to $self

   Methods Called within "text_pm_file()"
       "block_begin()"

         Usage     : $self->block_begin($module) within text_pm_file()
         Purpose   : Composes the standard code for top of a Perl pm file
         Returns   : String holding code for top of pm file
         Argument  : $module: pointer to the module being built
                     (as there can be more than one module built by EU::MM);
                     for the primary module it is a pointer to $self
         Throws    : n/a
         Comment   : This method is a likely candidate for alteration in a subclass,
                     e.g., you don't need Exporter-related code if you're building
                     an OO-module.
         Comment   : References $self keys NAME and (indirectly) VERSION

       "process_attribute()"

         Usage     : $self->process_attribute($module, @keys)
                     within block_begin(), text_test(),
                     text_pm_file(),  block_pod(), complete_build()
         Purpose   :
                     For the particular .pm file now being processed (value of the
                     NAME key of the first argument: $module), see if there exists a
                     key whose name is the second argument.  If so, return it.
                     Otherwise, return the value of the key by that name in the
                     EU::MM object.  If we have a two-level hash (currently only in
                     License_Parts, process down to that level.
         Arguments : First argument is a reference to an anonymous hash which has at
                     least one element with key NAME and value of the module being
                     processed.  Second is an array of key names, although in all but
                     one case it's a single-element (NAME) array.
         Comment   : [The method's name is very opaque and not self-documenting.
                     Function of the code is not easily evident.  Rename?  Refactor?]

       "block_subroutine_header()"

         Usage     : $self->block_subroutine_header($module) within text_pm_file()
         Purpose   : Composes an inline comment for pm file (much like this inline
                     comment) which documents purpose of a subroutine
         Returns   : String containing text for inline comment
         Argument  : $module: pointer to the module being built
                     (as there can be more than one module built by EU::MM);
                     for the primary module it is a pointer to $self
         Throws    : n/a
         Comment   : This method is a likely candidate for alteration in a subclass
                     E.g., some may prefer this info to appear in POD rather than
                     inline comments.

       "block_new_method()"

         Usage     : $self->block_new_method() within text_pm_file()
         Purpose   : Build 'new()' method as part of a pm file
         Returns   : String holding sub new.
         Argument  : $module: pointer to the module being built
                     (as there can be more than one module built by EU::MM);
                     for the primary module it is a pointer to $self
         Throws    : n/a
         Comment   : This method is a likely candidate for alteration in a subclass,
                     e.g., pass a single hash-ref to new() instead of a list of
                     parameters.

       "block_include_file_in_pm()"

         Usage     : $self->block_include_file_in_pm() within text_pm_file()
         Purpose   : Include text from an arbitrary file on disk in .pm file,
                     e.g., subroutine stubs you want in each of several extra
                     modules.
         Returns   : String holding text of arbitrary file.
         Argument  : $module: pointer to the module being built
                     (as there can be more than one module built by EU::MM);
                     for the primary module it is a pointer to $self
         Throws    : n/a
         Comment   : References $self->{INCLUDE_FILE_IN_PM}, whose value must be a
                     path to a single, readable file

       "block_pod()"

         Usage     : $self->block_pod($module) inside text_pm_file()
         Purpose   : Compose the main POD section within a pm file
         Returns   : String holding main POD section
         Argument  : $module: pointer to the module being built
                     (as there can be more than one module built by EU::MM);
                     for the primary module it is a pointer to $self
         Throws    : n/a
         Comment   : This method is a likely candidate for alteration in a subclass
         Comment   : In StandardText formulation, contains the following components:
                     warning about stub documentation needing editing
                     pod wrapper top
                     NAME - ABSTRACT
                     SYNOPSIS
                     DESCRIPTION
                     USAGE
                     BUGS
                     SUPPORT
                     HISTORY (as requested)
                     AUTHOR
                     COPYRIGHT
                     SEE ALSO
                     pod wrapper bottom

       "block_final()"

         Usage     : $self->block_final() within text_pm_file()
         Purpose   : Compose code and comment that conclude a pm file and guarantee
                     that the module returns a true value
         Returns   : String containing code and comment concluding a pm file
         Argument  : $module: pointer to the module being built
                     (as there can be more than one module built by EU::MM);
                     for the primary module it is a pointer to $self
         Throws    : n/a
         Comment   : This method is a likely candidate for alteration in a subclass,
                     e.g., some may not want the comment line included.

   All Other Methods
       "death_message()"

         Usage     : $self->death_message( [ I<list of error messages> ] )
                     in validate_values; create_directory; print_file
         Purpose   : Croaks with error message composed from elements in the list
                     passed by reference as argument
         Returns   : [ To come. ]
         Argument  : Reference to an array holding list of error messages accumulated
         Comment   : Different functioning in modulemaker interactive mode

       "log_message()"

         Usage     : $self->log_message( $message ) in print_file;
         Purpose   : Prints log_message (currently, to STDOUT) if $self->{VERBOSE}
         Returns   : n/a
         Argument  : Scalar holding message to be logged
         Comment   :

       "pod_section()"

         Usage     : $self->pod_section($heading, $content) within
                     block_pod()
         Purpose   : When writing POD sections, you have to 'escape'
                     the POD markers to prevent the compiler from treating
                     them as real POD.  This method 'unescapes' them and puts header
                     and closer around individual POD headings within pm file.
         Arguments : Variables holding POD section name and text of POD section.

       "pod_wrapper()"

         Usage     : $self->pod_wrapper($string) within block_pod()
         Purpose   : When writing POD sections, you have to 'escape'
                     the POD markers to prevent the compiler from treating
                     them as real POD.  This method 'unescapes' them and puts header
                     and closer around main POD block in pm file, along with warning
                     about stub documentation.
         Argument  : String holding text of POD which has been built up
                     within block_pod().
         Comment   : $head and $tail inside pod_wrapper() are optional and, in a
                     subclass, could be redefined as empty strings;
                     but $cutline is mandatory as it supplies the last =cut

SEE ALSO

       ExtUtils::ModuleMaker, ExtUtils::ModuleMaker::Initializers.