/ 
ExtUtils-ModuleMaker-0.38
River stage one • 3 direct dependents • 4 total dependents
/ ExtUtils::ModuleMaker::StandardText

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. But nothing prevents a user from calling these methods. Nevertheless, they are documented here primarily so that users writing plug-ins for ExtUtils::ModuleMaker's standard text know what methods need to be subclassed.

The methods below are called in ExtUtils::ModuleMaker::complet_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::new() or ExtUtils::ModuleMaker::complete_build(). So methods called within one of those two public methods 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 check_dir.

check_dir()

Usage     : check_dir( [ 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.
Usage     : $self->print_file($filename, $filetext) within generate_pm_file()
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   :

generate_pm_file

Usage     : $self->generate_pm_file($module) within complete_build()
Purpose   : Create a pm file out of assembled components
Returns   : n/a
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
Comment   : 3 components:  create_pm_basics; compose_pm_file; print_file

Methods Called within complete_build() as an Argument to print_fiile()

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

Methods Called within generate_pm_file()

create_pm_basics

Usage     : $self->create_pm_basics($module) within generate_pm_file()
Purpose   : Conducts check on directory 
Returns   : For a given pm file, sets the FILE key: directory/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
Comment   : References $self keys NAME, Base_Dir, and FILE.  
            Calls method check_dir.

compose_pm_file()

Usage     : $self->compose_pm_file($module) within generate_pm_file()
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
Comment   : [Method name is inaccurate; it's not building a 'page' but
            rather the text for a pm file.

Methods Called within compose_pm_file()

block_begin()

Usage     : $self->block_begin($module) within compose_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

module_value()

Usage     : $self->module_value($module, @keys) 
            within block_begin(), text_test(),
            compose_pm_file(),  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 : First is pointer to module being formed.  Second is an array
            whose members are the section(s) of the POD being written. 
Comment   : [The method's name is very opaque and not self-documenting.
            Function of the code is not easily evident.  Rename?  Refactor?]

block_pod()

Usage     : $self->block_pod($module) inside compose_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_subroutine_header()

Usage     : $self->block_subroutine_header($module) within compose_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 compose_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_final_one()

Usage     : $self->block_final_one() within compose_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; check_dir; 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