NAME
Porting/pod_lib.pl - functions for building and installing POD
SYNOPSIS
require './Porting/pod_lib.pl';DESCRIPTION
This program, when required into other programs in the Perl 5 core distribution, provides functions useful during building and, secondarily, testing.
As of this writing, the functions in this program are used in these other programs:
installman
installperl
pod/buildtoc
pod/perl.pod
Porting/new-perldelta.pl
Porting/pod_rules.plNote: Since these functions are used during the Perl build process, they must work with miniperl. That necessarily implies that these functions must not rely on XS modules, either directly or indirectly (e.g., autodie).
SUBROUTINES
my_die()
Purpose
Exit from a process with an error code and a message.
Arguments
List of arguments to be passed with the error message. Example:
close $fh or my_die("close 'utils.lst': $!");Return Value
Exit code
255.Comment
Prints
ABORTEDto STDERR.
open_or_die()
Purpose
Opens a file or fails if it cannot.
Arguments
String holding filename to be opened. Example:
$fh = open_or_die('utils.lst');Return Value
Handle to opened file.
slurp_or_die()
Purpose
Read the contents of a file into memory as a single string.
Arguments
String holding name of file to be read into memory.
$olddelta = slurp_or_die('pod/perldelta.pod');Return Value
String holding contents of file.
write_or_die()
Purpose
Write out a string to a file.
Arguments
List of two arguments: (i) String holding name of file to be written to; (ii) String holding contents to be written.
write_or_die($olddeltaname, $olddelta);Return Value
Implicitly returns true value upon success.
verify_contiguous()
Purpose
Verify that a file contains exactly one contiguous run of lines which matches the passed in pattern.
croak()s if the pattern is not found, or found in more than one place.Arguments
Name of file
Contents of file
Pattern of interest
Name to report on error
Return Value
The contents of the file, with
qr/\0+/substituted for the pattern.
process()
Purpose
Read a file from disk, pass the contents to the callback, and either update the file on disk (if changed) or generate TAP output to confirm that the version on disk is up to date.
dies if the file contains anyNULbytes. This permits the callback routine to useNULbytes as placeholders while manipulating the file's contents.Arguments
Description for use in error messages
Name of file
Callback
Passed description and file contents, should return updated file contents.
Test number
If defined, generate TAP output to
STDOUT. If defined and false, generate an unnumbered test. Otherwise this is the test number in the ok line.Verbose flag
If true, generate verbose output.
Return Value
Does not return anything.
pods_to_install()
Purpose
Create a lookup table holding information about PODs to be installed.
Arguments
None.
Return Value
Reference to a hash with a structure like this:
$found = { 'MODULE' => { 'CPAN::Bundle' => 'lib/CPAN/Bundle.pm', 'Locale::Codes::Script_Retired' => 'lib/Locale/Codes/Script_Retired.pm', 'Pod::Simple::DumpAsText' => 'lib/Pod/Simple/DumpAsText.pm', # ... 'Locale::Codes::LangVar' => 'lib/Locale/Codes/LangVar.pod' }, 'PRAGMA' => { 'fields' => 'lib/fields.pm', 'subs' => 'lib/subs.pm', # ... },Comment
Broadly speaking, the function assembles a list of all .pm and .pod files in the distribution and then excludes certain files from installation.
get_pod_metadata()
Purpose
Arguments
List of one or more arguments.
Boolean true or false
Reference to a subroutine.
Various other arguments.
Example:
$state = get_pod_metadata( 0, sub { warn @_ if @_ }, 'pod/perltoc.pod'); get_pod_metadata( 1, sub { warn @_ if @_ }, values %Build);Return Value
Hash reference; each element provides either a list or a lookup table for information about various types of POD files.
'aux' => [ # utility programs like 'h2xs' and 'perlbug' ] 'generated' => { # lookup table for generated POD files like 'perlapi.pod' } 'ignore' => { # lookup table for files to be ignored } 'pods' => { # lookup table in "name" => "short description" format } 'readmes' => { # lookup table for OS-specific and other READMEs } 'delta_version' => [ # major version number, minor no., patch no. ] 'delta_target' => 'perl<Mmmpp>delta.pod', 'master' => [ # list holding entries for files callable by 'perldoc' ] 'copies' => { # patch version perldelta => minor version perldelta }