ExtUti...ardText(3pm)

🎀 ExtUtils::ModuleMaker::StandardText(3pm) 🎀

User Contributed Perl Documentation — okay bestie, this is the manual page for ExtUtils::ModuleMaker::StandardText. It's giving quasi-private methods and it's lowkey iconic. 💖

🌸 NAME 🌸

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

💫 DESCRIPTION 💫

okay so 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: (empty)

🍓 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: Originally adapted from David Golden's ExtUtils::ModuleMaker::TT
• Comment: Updated to reflect ExtUtils::Manifest 1.70 (distributed with Perl 5.26) plus travis and appveyor configuration files

💅 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: drop text from any file on disk into your .pm file — like subroutine stubs you want in each of several extra modules. 💅
• Returns: a string holding the text of that arbitrary file.
• Argument: $module — pointer to the module being built (because EU::MM can build more than one module, bestie); for the primary module it's a pointer to $self.
• Throws: n/a (no drama).
• Comment: it references $self->{INCLUDE_FILE_IN_PM}, and that value must be a path to a single, readable file. no cap, it has to be readable.

block_pod()

• Usage: $self->block_pod($module) inside text_pm_file()
• Purpose: compose the main POD section inside a pm file. ✨
• Returns: string holding the main POD section.
• Argument: $module — pointer to the module being built (EU::MM can build multiple modules, fr fr); for the primary module it's a pointer to $self.
• Throws: n/a.
• Comment: this method is a likely candidate for alteration in a subclass. 👑
• Comment: in the StandardText formulation, it contains these 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 the code and comment that conclude a pm file and guarantee the module returns a true value. ✅
• Returns: string containing that code and comment.
• Argument: $module — pointer to the module being built (multiple modules possible, iykyk); for the primary module it's a pointer to $self.
• Throws: n/a.
• Comment: likely candidate for alteration in a subclass — e.g., some people may not want that 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 an error message composed from the elements in the list passed by reference as the argument. 💀
• Returns: [ To come. ] (yes, literally that placeholder, we're keeping it real)
• Argument: reference to an array holding the list of accumulated error messages.
• Comment: different functioning in modulemaker interactive mode.

log_message()

• Usage: $self->log_message( $message ) in print_file;
• Purpose: prints the log message (currently to STDOUT) if $self->{VERBOSE} is set. 🫶
• Returns: n/a
• Argument: scalar holding the message to be logged.
• Comment: (none — it's empty in the original, no shade)

pod_section()

• Usage: $self->pod_section($heading, $content) within block_pod()
• Purpose: when you're writing POD sections you have to 'escape' the POD markers so the compiler doesn't treat them as real POD. This method 'unescapes' them and puts a header and closer around individual POD headings inside the pm file. 🌸
• Arguments: variables holding the POD section name and the text of the POD section.

pod_wrapper()

• Usage: $self->pod_wrapper($string) within block_pod()
• Purpose: same escape situation — when writing POD sections you have to 'escape' the POD markers so the compiler doesn't treat them as real POD. This method 'unescapes' them and puts a header and closer around the main POD block in the pm file, along with the warning about stub documentation. 🎀
• Argument: string holding the text of the POD that 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 because it supplies the last =cut. don't skip it.

👀 SEE ALSO 👀

• ExtUtils::ModuleMaker
• ExtUtils::ModuleMaker::Initializers

---

and that's the whole page, bestie. this was ExtUti...ardText(3pm) — aka ExtUtils::ModuleMaker::StandardText(3pm) — from perl v5.36.0, dated 2023-01-27. slay, you read the whole thing. 💖