Porting/pod_lib.pl - functions for building and installing POD
require './Porting/pod_lib.pl';
This program, when required into other programs in the Perl 5 core distribution, provides functions useful during building and, secondarily, testing.
require
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.pl
Note: 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).
autodie
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.
255
Comment
Prints ABORTED to STDERR.
ABORTED
open_or_die()
Opens a file or fails if it cannot.
String holding filename to be opened. Example:
$fh = open_or_die('utils.lst');
Handle to opened file.
slurp_or_die()
Read the contents of a file into memory as a single string.
String holding name of file to be read into memory.
$olddelta = slurp_or_die('pod/perldelta.pod');
String holding contents of file.
write_or_die()
Write out a string to a file.
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);
Implicitly returns true value upon success.
pods_to_install()
Create a lookup table holding information about PODs to be installed.
None.
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', # ... },
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()
List of one or more arguments.
Boolean true or false
Reference to a suboutine.
Various other arguments.
Example:
$state = get_pod_metadata( 0, sub { warn @_ if @_ }, 'pod/perltoc.pod'); get_pod_metadata( 1, sub { warn @_ if @_ }, values %Build);
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 }
To install vars, copy and paste the appropriate command in to your terminal.
cpanm
cpanm vars
CPAN shell
perl -MCPAN -e shell install vars
For more information on module installation, please visit the detailed CPAN module installation guide.