.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "ExtUtils::ModuleMaker::StandardText 3pm" .TH ExtUtils::ModuleMaker::StandardText 3pm "2023-01-27" "perl v5.36.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" ExtUtils::ModuleMaker::StandardText \- Methods used within ExtUtils::ModuleMaker .SH "DESCRIPTION" .IX Header "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. .PP The methods below are called in \f(CW\*(C`ExtUtils::ModuleMaker::complete_build()\*(C'\fR but not in that same package's \f(CW\*(C`new()\*(C'\fR. For methods called in \&\f(CW\*(C`new()\*(C'\fR, please see ExtUtils::ModuleMaker::Initializers. .PP 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 \&\f(CW\*(C`ExtUtils::ModuleMaker::complete_build()\*(C'\fR. So methods called within \f(CW\*(C`complete_build()\*(C'\fR 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. .PP Happy subclassing! .SH "METHODS" .IX Header "METHODS" .ie n .SS "Methods Called within ""complete_build()""" .el .SS "Methods Called within \f(CWcomplete_build()\fP" .IX Subsection "Methods Called within complete_build()" \fI\f(CI\*(C`create_base_directory\*(C'\fI\fR .IX Subsection "create_base_directory" .PP .Vb 5 \& 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. .Ve .PP \fI\f(CI\*(C`create_directory()\*(C'\fI\fR .IX Subsection "create_directory()" .PP .Vb 9 \& Usage : create_directory( [ I ] ) \& 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. .Ve .PP \fI\f(CI\*(C`print_file()\*(C'\fI\fR .IX Subsection "print_file()" .PP .Vb 7 \& 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 : .Ve .ie n .SS "Methods Called within ""complete_build()"" as an Argument to ""print_file()""" .el .SS "Methods Called within \f(CWcomplete_build()\fP as an Argument to \f(CWprint_file()\fP" .IX Subsection "Methods Called within complete_build() as an Argument to print_file()" \fI\f(CI\*(C`text_README()\*(C'\fI\fR .IX Subsection "text_README()" .PP .Vb 6 \& 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 .Ve .PP \fI\f(CI\*(C`text_Todo()\*(C'\fI\fR .IX Subsection "text_Todo()" .PP .Vb 7 \& 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 .Ve .PP \fI\f(CI\*(C`text_Changes()\*(C'\fI\fR .IX Subsection "text_Changes()" .PP .Vb 9 \& 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 .Ve .PP \fI\f(CI\*(C`text_test()\*(C'\fI\fR .IX Subsection "text_test()" .PP .Vb 8 \& 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. .Ve .PP \fI\f(CI\*(C`text_Makefile()\*(C'\fI\fR .IX Subsection "text_Makefile()" .PP .Vb 6 \& 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 .Ve .PP \fI\f(CI\*(C`text_Buildfile()\*(C'\fI\fR .IX Subsection "text_Buildfile()" .PP .Vb 8 \& 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 .Ve .PP \fI\f(CI\*(C`text_proxy_makefile()\*(C'\fI\fR .IX Subsection "text_proxy_makefile()" .PP .Vb 6 \& 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 .Ve .PP \fI\f(CI\*(C`text_MANIFEST_SKIP()\*(C'\fI\fR .IX Subsection "text_MANIFEST_SKIP()" .PP .Vb 10 \& 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 : Originally adapted from David Golden\*(Aqs ExtUtils::ModuleMaker::TT \& Comment : Updated to reflect ExtUtils::Manifest 1.70 \& (distributed with Perl 5.26) plus travis and appveyor \& configuration files .Ve .PP \fI\f(CI\*(C`text_pod_coverage_test()\*(C'\fI\fR .IX Subsection "text_pod_coverage_test()" .PP .Vb 8 \& 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\*(Aqs Module::Starter \& Comment : I don\*(Aqt think of much of this metric, but Andy and Damian do, \& so if you want it you set INCLUDE_POD_COVERAGE_TEST => 1 .Ve .PP \fI\f(CI\*(C`text_pod_test()\*(C'\fI\fR .IX Subsection "text_pod_test()" .PP .Vb 8 \& 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\*(Aqs Module::Starter \& Comment : I don\*(Aqt think of much of this metric, but Andy and Damian do, \& so if you want it you set INCLUDE_POD_TEST => 1 .Ve .PP \fI\f(CI\*(C`text_pm_file()\*(C'\fI\fR .IX Subsection "text_pm_file()" .PP .Vb 6 \& 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 .Ve .ie n .SS "Methods Called within ""text_pm_file()""" .el .SS "Methods Called within \f(CWtext_pm_file()\fP" .IX Subsection "Methods Called within text_pm_file()" \fI\f(CI\*(C`block_begin()\*(C'\fI\fR .IX Subsection "block_begin()" .PP .Vb 11 \& 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\*(Aqt need Exporter\-related code if you\*(Aqre building \& an OO\-module. \& Comment : References $self keys NAME and (indirectly) VERSION .Ve .PP \fI\f(CI\*(C`process_attribute()\*(C'\fI\fR .IX Subsection "process_attribute()" .PP .Vb 10 \& 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\*(Aqs a single\-element (NAME) array. \& Comment : [The method\*(Aqs name is very opaque and not self\-documenting. \& Function of the code is not easily evident. Rename? Refactor?] .Ve .PP \fI\f(CI\*(C`block_subroutine_header()\*(C'\fI\fR .IX Subsection "block_subroutine_header()" .PP .Vb 11 \& 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. .Ve .PP \fI\f(CI\*(C`block_new_method()\*(C'\fI\fR .IX Subsection "block_new_method()" .PP .Vb 10 \& Usage : $self\->block_new_method() within text_pm_file() \& Purpose : Build \*(Aqnew()\*(Aq 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. .Ve .PP \fI\f(CI\*(C`block_include_file_in_pm()\*(C'\fI\fR .IX Subsection "block_include_file_in_pm()" .PP .Vb 11 \& 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 .Ve .PP \fI\f(CI\*(C`block_pod()\*(C'\fI\fR .IX Subsection "block_pod()" .PP .Vb 10 \& 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 .Ve .PP \fI\f(CI\*(C`block_final()\*(C'\fI\fR .IX Subsection "block_final()" .PP .Vb 10 \& 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. .Ve .SS "All Other Methods" .IX Subsection "All Other Methods" \fI\f(CI\*(C`death_message()\*(C'\fI\fR .IX Subsection "death_message()" .PP .Vb 7 \& Usage : $self\->death_message( [ I ] ) \& 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 .Ve .PP \fI\f(CI\*(C`log_message()\*(C'\fI\fR .IX Subsection "log_message()" .PP .Vb 5 \& 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 : .Ve .PP \fI\f(CI\*(C`pod_section()\*(C'\fI\fR .IX Subsection "pod_section()" .PP .Vb 7 \& Usage : $self\->pod_section($heading, $content) within \& block_pod() \& Purpose : When writing POD sections, you have to \*(Aqescape\*(Aq \& the POD markers to prevent the compiler from treating \& them as real POD. This method \*(Aqunescapes\*(Aq them and puts header \& and closer around individual POD headings within pm file. \& Arguments : Variables holding POD section name and text of POD section. .Ve .PP \fI\f(CI\*(C`pod_wrapper()\*(C'\fI\fR .IX Subsection "pod_wrapper()" .PP .Vb 11 \& Usage : $self\->pod_wrapper($string) within block_pod() \& Purpose : When writing POD sections, you have to \*(Aqescape\*(Aq \& the POD markers to prevent the compiler from treating \& them as real POD. This method \*(Aqunescapes\*(Aq 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 .Ve .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fIExtUtils::ModuleMaker\fR, \fIExtUtils::ModuleMaker::Initializers\fR.