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.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).

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 ABORTED to 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 makefile or makefile constructor contains exactly one contiguous run of lines which matches a given pattern. croak()s if the pattern is not found, or found in more than one place.

  By "makefile or makefile constructor" we mean a file which is one of the right-hand values in this list of key-value pairs:

  manifest => 'MANIFEST',
  vms => 'vms/descrip_mms.template',
  nmake => 'win32/Makefile',
  gmake => 'win32/GNUmakefile',
  podmak => 'win32/pod.mak',
  unix => 'Makefile.SH',

  (Currently found in %Targets in Porting/pod_rules.pl.)

• Arguments

  • Name of target

    String holding the key of one element in %Targets in Porting/pod_rules.pl.

  • Contents of file

    String holding slurped contents of the file named in the value of the element in %Targets in Porting/pod_rules.pl named in the first argument.

  • Pattern of interest

    Compiled regular expression pertinent to a particular makefile constructor.

  • Name to report on error

    String holding description.

• Return Value

  The contents of the file, with qr/\0+/ substituted for the pattern.

• Example (drawn from Porting/pod_rules.pl do_unix()):

  my $makefile_SH = slurp_or_die('./Makefile.SH');
  my $re = qr/some\s+pattern/;
  my $makefile_SH_out =
      verify_contiguous('unix', $makefile_SH, $re, 'copy rules');

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 any NUL bytes. This permits the callback routine to use NUL bytes 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

  Create a data structure holding information about files containing text in POD format.

• 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 'perldoc' ]
  '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 }

• Comment

  Instances where this subroutine is used may be found in these files:

  pod/buildtoc
  Porting/new-perldelta.pl
  Porting/pod_rules.pl