++ed by:
ABRAXXA ADAMJS ALEXBIO ANDREFS ARJONES

117 PAUSE user(s)
93 non-PAUSE user(s).

Ricardo SIGNES

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.

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 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);
  • 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 }



Hosting generously
sponsored by Bytemark